On Mon, Oct 29, 2012 at 4:28 AM, xantares 09 <[email protected]> wrote:
>
> 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.
6. Otherwise there was a google summer of code 2012 resulting in a swig
> branch that can automate docstring and javadoc
> https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2012-doxygen/
> It don't know whether it is merged.
>
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
https://github.com/etihwnad/libftdi.git
Dan
--
SDG
www.whiteaudio.com
--
libftdi - see http://www.intra2net.com/en/developer/libftdi for details.
To unsubscribe send a mail to [email protected]
0001-Enable-separate-doxygen-XML-output.patch
Description: Binary data
0002-Extract-doxygen-from-ftdi.c-to-python-docstrings.patch
Description: Binary data
0003-Tweak-doxy2swig.py-output-to-include-Returns-header.patch
Description: Binary data
