CODEWITHSUNDEEP
c#c++doxygenswig
Alex
Alex

Reputation: 15343

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

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?

Upvotes: 6

Views: 1730

Answers (2)

emmenlau
emmenlau

Reputation: 1039

As of October 2022, the accepted answer from m7thon has become outdated. I have started work in the (public) merge request https://github.com/swig/swig/pull/2421, based on the nice prior work from https://github.com/swig/swig/pull/1695, to add support for doxygen comments for SWIG-generated C#.

The current status in the above MR still has quite significant limitations. Also it has not yet been extensively tested. But it can already achieve basic documentation in C# XML format, and may be a good starting point for people in need of a solution.

Upvotes: 1

m7thon
m7thon

Reputation: 3043

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?

Upvotes: 5

Related Questions