From: William S F. <ws...@fu...> - 2008-07-23 07:53:53
|
Cheryl wrote: > 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. Normally a doxygen comment is associated with a symbol of some sort. Wouldn't the comments be attached to the equivalent symbol in the target language? Would there be a need for a new doxygen feature, something like: %feature("doxygen") Foo::bar(int n) "/** /param n number /return result */" Which would attach itself to the appropriate Foo::bar symbol? I think doxygen has a way to attach comments to a symbol anyway, so probably we should be using that instead instead of the above %feature. > > 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. You've written a doxygen parser which makes the doxygen comments available in a parse tree. That makes perfect sense for providing a generic way to process the comments by each target language. Is this parser all written from scratch or have you been able to utilise the real doxygen parser in any way. If not, was there some reason for not re-using the already existing open source doxygen parser? Or is the structure of doxygen comments pretty easy that writing your own one fairly trivial? > 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/259 or send me an email! > I have some headers I'll send you privately. I'm interested in Java, C# and Python. Parsing the doxygen comments and putting them into the parse tree is a great step forward and simply being able to dump them into the target language is fantastic. It sounds like you are hoping to do even more than that though. Do you have any classic use cases of what you aim to do? For example a comment containing the /param and /return doxygen tags, what will the output look like for the proxy Java function? We have a number of custom javadoc tags. What would the default behaviour be for these? William |