Is there a good way to prepare documentation for swig interfaces?

Question

I would like to know if there are good methods for creating / maintaining interface documentation.

I am creating an interface from C ++ code in python using swig; basically i'm just% including C ++ header files. I deal with at least dozens of classes and 100 functions, so automated tools are preferred.

Ideally, I would like to use doxygen-enabled comments in C ++ headers to populate docstrings in python classes / methods.

Alternatively, creating separate documentation (in ascii, html ...) would also be helpful. It seems that this functionality was supported in earlier versions of swig (1.3 and earlier), but I see no way to do it with 2.0.

Are there any useful (automated) methods for documenting an interface?

Answer 1

There's some run in %feature("autodoc") with SWIG 2.0, which, it seems to me, is as far away as it is now.

For example:

 %module test %feature("autodoc", "3"); void foo (int *a, void *bar, double epsilon); 

leads to the insertion of some vague documentation.

If this is not enough, I think the next simple step would be to use %pythonprepend to make the marker unique enough sed or similar ones can be used to insert documentation into the interface after running SWIG automatically:

 %pythonprepend foo "MARKER" 

and then:

 sed -ei 's/MARKER/some documentation' test.py 

Where can you find the %pythonprepend functions by %pythonprepend at the Doxygen output using a (Python?) Script to generate tokens and replace them after running SWIG.

Answer 2

To get your doxygen comments in python files, there is a python tool called doxy2swig.py on the Internet, as described here .

Create XML documentation from your code. Then use the tool:

doxy2swig.py index.xml documentation.i

and import the documentation.i into your swig interface file via

% import "documentation.i"

And everything is done.