Date: Wed, 31 Oct 2012 23:11:58 -0500 Subject: Re: doxygen-derived docstrings for the python bindings From: dan@xxxxxxxxxxxxxx To: libftdi@xxxxxxxxxxxxxxxxxxxxxxx
I reviewed your patch to automate docstring production as had already tried it for another project:
0. Hey I also use ipython a lot! This is some wet shit, right!
Thanks for the review! My lack of cmake fu is apparent. The updated patch set should take care of most of the comments.
1. Your patch breaks out-of-source build because of: ${CMAKE_CURRENT_BINARY_DIR}/doxy2swig.py which should become ${CMAKE_CURRENT_SOURCE_DIR}/doxy2swig.py
Done.
2. Your patch breaks parallel compilation because the swig target is built before ftdi1_doc.i. I think you're gonna have to create a custom_target for the generation of ftdi1_doc.i on which the swig call depends.
Done. Splitting the xml generation out as a separate step was the trick.
3. Your patch breaks bindings build if doxygen is not avalable, so xml => ftdi1_doc.i are not generated and build fails.
Done.
4. Otherwise the xml documentation does accurately document the parameters:
but maybe the c prototype should be removed when it does not match the actual python prototype because of the argout typemaps, prefix mangling,... :
The combination of setting %feature("autodoc","1"); and the doxy2swig.py -n option to not output prototypes works well. Disagreements then show up in the "Returns:" section of the docstring, but that is direct from the doxygen comments.
It doesn't seem to be, I'm sure there are lots of projects using the swig/doxy combination who would be happy to not use their ad-hoc setups to avoid twice-documenting the exported functions.
The commits also live on github on my "doxygen-swig" branch
