Generating doxygen comments for swig-generated C# that wraps C++

Question

I have a project written in C++ where I'm using swig to generate some C# wrappers as well. The C++ code uses Doxygen style comments to annotate the classes and functions. Is it possible to get Swig to take those doxygen comments and produce doxygen comments for the C# wrapper classes and functions?

Answer 1

Currently, SWIG does not parse code comments including Doxygen documentation at all.

There is a SWIG branch in development since a couple of years to enable SWIG to deal with Doxygen comments, but even that currently (AFAIK) only maps them to Java and Python documentation.

The best option currently is therefore to extract the Doxygen documentation from the C++ source code and insert it into the SWIG generated wrapper. To understand how this can be done, here is a brief explanation of what doxy2swig.py does (and this is indeed meant for python docstrings):

1. Let Doxygen extract the documentation into its XML format
2. Parse the XML, and reformat into suitable Python docstrings
3. Write %feature("docstring") SWIG directives to tell SWIG to attach the docstrings to the wrapped classes and methods.

Basically, something similar can be done for C# as well. I do not know how to do (2) for C#, i.e., how to translate the Doxygen XML output into suitable C# documentation, this you may need to implement yourself (perhaps by modifying the doxy2swig.py script).

For (3) there is a neat trick that is sort of documented here, noting that the same can also be done for C# using the %csclassmodifiers and %csmethodmodifiers. These SWIG feature directives are AFAIK used to prepend either public or protected to C# methods or classes. But they can be hijacked to prepend the extracted documentation (+ the public keyword, not to forget). So they effectively allow the same functionality as the %feature("docstring") directive for Python.

Finally, I don't know C#, but what is the point of having the Doxygen comments included in the C# wrapper? If you only want to use Doxygen to generate documentation, you can do this from the C++ sources directly, so you don't gain anything. In Python, the docstrings can be displayed as help at runtime, and are used by some IDEs. Does C# have this, too?