问题
I'd like to know if there are any good techniques for constructing/maintaining documentation on the interface.
I'm building an interface from c++ code to python using swig; mostly I'm just %including the c++ header files. I'm dealing with at least dozens of classes and 100's of functions, so automated tools are preferred.
Ideally, I'd like to use the doxygen formatted comments in the c++ headers to populate the docstrings in the python classes/methods.
Alternately, generating separate documentation (in ascii, html...) would also be useful. It looks like this kind of functionality was supported in earlier versions of swig (1.3 and earlier) but I don't see a way to do it with 2.0.
Are there any useful (automated) techniques for documenting the interface?
回答1:
There's some mileage in %feature("autodoc") with SWIG 2.0, which I think is as far is it goes currently.
For example:
%module test
%feature("autodoc", "3");
void foo (int *a, void *bar, double epsilon);
causes some vaguely sane documentation to be inserted.
If that isn't sufficient I think the next easiest step would be to use %pythonprepend to make a marker that's unique enough sed or similar can be used to insert documentation into the interface after SWIG has run automatically:
%pythonprepend foo "MARKER"
and then:
sed -ei 's/MARKER/some documentation' test.py
Where you could find the functions to %pythonprepend by looking over the Doxygen output using a (Python?) script to generate the markers and substitute them after running SWIG.
回答2:
To get your doxygen comments into the python files there exists a python tool called doxy2swig.py on the web as described here.
Create xml documentation from your code. Then use the tool:
doxy2swig.py index.xml documentation.i
and import documentation.i in you swig interface file via
%import "documentation.i"
And its done.
来源：https://stackoverflow.com/questions/11435102/is-there-a-good-way-to-produce-documentation-for-swig-interfaces