gmane.comp.programming.swig.devel

Cheryl | 18 Jul 06:50

GSoC "Doxygen Translator" Progress

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/259 or send me an email!

Thank you,

Cheryl Foil

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/

headers

David Piepgrass | 18 Jul 17:20

Re: [SPAM] GSoC "Doxygen Translator" Progress

> 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.

I would like the option to transfer comments directly unmodified to C#,
especially if it turns out you don't have time to do a proper
translation. I don't use doxygen yet, but I have the impression that
doxygen for C# supports the same syntax as doxygen for C++, so direct
transfer might even be enough. It would be even better if you could
translate doxygen to XML doc comments, though; then both Doxygen and
Sandcastle-based doc generation tools could be applied to the C#
wrappers (I think I prefer Sandcastle via SHFB because the output seems
more professional to me).

Direct comment transfer is the kind of thing that just about anybody
would find useful, I think. It could even be enabled by default. Users
would see the comments transferred automatically and think to themselves
"wow! neat!"

Thanks for doing this important project!

- David Piepgrass

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/

headers

William S Fulton | 23 Jul 09:53

Re: GSoC "Doxygen Translator" Progress

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

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/

headers

Olly Betts | 25 Jul 11:08

Re: GSoC "Doxygen Translator" Progress

On 2008-07-23, William S Fulton <wsf <at> fultondesigns.co.uk> wrote:
> 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.

Doxygen can do that, but there are various reasons why you might want to
override a C/C++ documentation comment for another language (e.g. it
might give some example code, or talk about something C/C++-specific or
link to an external document which isn't useful), so it's probably
useful to provide features to allow replacing a comment entirely, and
perhaps also to append to a comment.

> 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?

Note that Doxygen is GPL, so we would have to convince the authors to
relicense the parser code to incorporate it into SWIG.  We did consider
asking them, but it's a very simpler grammar and we suspected that the
effort to implement it would be comparable to adapting an existing
parser anyway.

Cheers,
    Olly

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/

headers

William S Fulton | 26 Jul 02:41

Re: GSoC "Doxygen Translator" Progress

Olly Betts wrote:
> On 2008-07-23, William S Fulton <wsf <at> fultondesigns.co.uk> wrote:
>> 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.
> 
> Doxygen can do that, but there are various reasons why you might want to
> override a C/C++ documentation comment for another language (e.g. it
> might give some example code, or talk about something C/C++-specific or
> link to an external document which isn't useful), so it's probably
> useful to provide features to allow replacing a comment entirely, and
> perhaps also to append to a comment.
> 
That's a good point.

>> 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?
> 
> Note that Doxygen is GPL, so we would have to convince the authors to
> relicense the parser code to incorporate it into SWIG.  We did consider
> asking them, but it's a very simpler grammar and we suspected that the
> effort to implement it would be comparable to adapting an existing
> parser anyway.

Ah okay thanks for update.

William

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/