search

kkaempf / swig-issues

Issues from SWIG (testing)
0 stars 0 forks source link

Doxygen support #64

Open SwigAtSF opened 11 years ago

SwigAtSF commented 11 years ago

Hi,

Since documentation is currently not built, I may going to ask for something that is already implemented. Yet, I didn't notice any information about that. BTW -

Could we imagine to get Doxygen comments used by SWIG in generated wrappers ? It'd be a very nice feature (I especially think about Perl wrappers, but I suppose the documentation generation is generic in SWIG).

Any way, Many thanks to SWIG team for the great work !

Frederic.

SwigAtSF commented 11 years ago

Logged In: YES user_id=171344 Originator: NO

This would be an extremely useful feature for me too. Now that I've made this wrapper for my (proprietary) library, we need documentation to give to customers--documentations for both the C# version and the C++ version. I see no way to write the documentation once to cover both languages, and it would sure be a pain to write it twice, or even to maintain one version that is completely separate from the source code (with no doc-generation tools).

To implement this, the SWIG parser could build a list of comments when they are encountered (rather than throwing them away as a compiler would). Each time a declaration such as a class or function is encountered, the list of comments is associated with the declaration (using a %feature), then the list is cleared. If the parser encounters a blank line or anything else that is not documentable, the list is cleared. It should be possible to copy documentation from one feature to another so that things like %attribute can keep the documentation even as they %ignore the original declaration they are used on.

A second feature for the case when a comment starts on the same line as the declaration would also be nice:

int NumWidgets; // Number of widgets

I guess the means by which documentation is emitted depends on the language. For C# and Java, the comments can be printed out exactly as they appeared in the original code.

I might be willing to implement this myself if someone would give me tips on how to do it (at this point I don't even know how to compile SWIG on my Windows system).

SwigAtSF commented 11 years ago

Logged In: YES user_id=1896083 Originator: NO

There's a program called doxy2swig.py out there on the net, which will read Doxygen's XML output and make docstrings that can be used as input for SWIG. It's intended for the Python docstring feature.

In order to get one of our projects done, I've basically copied the Python docstring support to the C# and Java modules. I've modified a copy of doxy2swig.py to produce docstrings that eventually produce XML documentation for .NET, and Javadoc output. It's also possible to run the generated files through Doxygen again.

I'm wondering if those patches would prove interesting to the development team. I'll be the first to admit they're a bit of a hack; there may be a few things I don't fully understand about the internals.

I also don't know what the SWIG team's roadmap is for the documentation support, nor the intended design, so this was done "blind", basically driven by local project pressure. So if I post, it'd be very unofficial.

SwigAtSF commented 11 years ago

Logged In: YES user_id=242951 Originator: NO

Documentation support and doxygen comes up on the mailing lists every few months. It is definitely a desired feature, but one without anyone to get the dirty work done. Search the mailing lists for various proposals. I suggest you start a thread on swig-devel if you would like to put forward any designs or prototypes. I think there will be interest. I'm certainly interested.

SwigAtSF commented 11 years ago

Logged In: YES user_id=14972 Originator: NO

Assigning to Cheryl as she's working on this as a GSoC project.

Cheryl - if you've not seen this tracker entry before, just have a read of the discussion to see if there are any points you've not already considered.