[Swig-devel] GSoC "Doxygen Translator" Progress

[Cheryl <che...@gm...>]

Hello!

I will also be writing weekly updates of my GSOC project to the development
mailing list. :)

So far I have been working on a means to translate Doxygen comments into
other documentation languages that would be more suitable for the target
languages. The language I am first aiming for is JavaDoc for the Java
module, but I hope to also write something for another language module
before GSOC concludes. The end result will be that you will have an option
to have any Doxygen comments that exist in your interface file placed in the
appropriate documentation language in the resulting proxy file that SWIG
produces. If the community would also like a simple option to transport
Doxygen comments found in an interface file directly, without modification,
into the resulting proxy file, I would be happy to add that functionality as
well.

Right now I have a parser written for Doxygen comments that creates a tree
full of logical entities easy to translate into another language. For
example, the command "\b word" results in a node containing the command, b,
and the word to be made bold. A more complicated command such as \param
contains a tree with the parameter label as the first node, and all
following nodes make up the parameter description- this could be simply
plain text or a combination of text and additional Doxygen commands. After
the most basic functionality is in place, I'm going to be working more with
the SWIG side of my project. The majority of my work so far has been in a
separate module. The SWIG parser itself merely places all valid Doxygen
comments as attributes in the parse tree- for example, the Doxygen comments
for a specific function reside in that function's node. These individual
"blobs" of Doxygen will be handed to my module, which parses them and
rewrites them into the target documentation language. Then the target
language module will write the translated comments into the proxy file.

The next step in my project will be working in more depth with SWIG itself.
I look forward to this very much because it gives me a great opportunity to
increase my interaction with the community. :) So far my experience has been
limited to manipulating the parse tree. Once the entire process is
functional and the SWIG-based code is robust, I will be spending more time
fortifying my module. For now there is not much to easily experiment until I
have hooked it into SWIG end to end, but in the coming weeks any available
prodding to my code would be quite welcome. :) I will also be sending across
a request for valid interface files containing Doxygen Comments (preferably
as attachments) on swig-user so I can ensure my module works properly- these
or anything else you could offer would be greatly appreciated! I would also
love to know what tags you use most frequently or what target documentation
languages would benefit the community most. If you are interested in more
about my project, please check out my blog at
http://planet-soc.com/blog/259or send me an email!

Thank you,


Cheryl Foil