> Date: Sat, 27 Oct 2012 00:45:34 -0500
> Subject: doxygen-derived docstrings for the python bindings
> From: dan@xxxxxxxxxxxxxx
> To: libftdi@xxxxxxxxxxxxxxxxxxxxxxx
>
> My current usage of libftdi is solely through the python bindings
> talking to a FT4232-based board. In that capacity, I spend much time
> at an ipython console
>
> The attached patches first enable XML generation in doxygen, then
> generate docstrings for the python bindings from the function
> documentation in ftdi.c. It uses a BSD-licensed script to generate an
> .i file for SWIG which is then included from ftdi1.i. Having the
> docstrings available from a python console has been a nice addition
> over even the function signature only.
>
> On top of the bindings, I've made a custom SPI class which handles
> arbitrary port output bit(s) as chip-selects and a bit-banged I2C
> class that uses configurable pins for SDA/SCL and leaves the rest of
> the port bits as gpio's. If it gets extracted from the
> application-specific stuff, I'll post those somewhere public and ping
> the list.
>
> Thanks,
> Dan
>
Hi,
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!
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
2. Your patch breaks parallel compilation because the swig target is built before ftdi1_doc.i.
[ 33%] [ 38%] Swig source
Generating ftdi1_doc.i
[ 50%] [ 50%] [ 55%] [ 61%] [ 66%] [ 72%] [ 77%] [ 88%] [ 88%] [ 94%] Building C object examples/CMakeFiles/bitbang_cbus.dir/bitbang_cbus.c.o
Building C object examples/CMakeFiles/baud_test.dir/baud_test.c.o
Building C object examples/CMakeFiles/eeprom.dir/eeprom.c.o
Building C object examples/CMakeFiles/bitbang2.dir/bitbang2.c.o
Building C object examples/CMakeFiles/bitbang.dir/bitbang.c.o
Building C object examples/CMakeFiles/bitbang_ft2232.dir/bitbang_ft2232.c.o
Building C object examples/CMakeFiles/serial_test.dir/serial_test.c.o
Building C object examples/CMakeFiles/simple.dir/simple.c.o
Building C object examples/CMakeFiles/find_all.dir/find_all.c.o
Building C object examples/CMakeFiles/stream_test.dir/stream_test.c.o
Linking C executable simple
Linking C executable find_all
Linking C executable bitbang
Linking C executable bitbang2
Linking C executable bitbang_cbus
Linking C executable serial_test
Linking C executable eeprom
Linking C executable bitbang_ft2232
Linking C executable baud_test
[ 94%] Built target docs
[ 94%] Built target simple
[ 94%] [ 94%] [ 94%] [ 94%] Built target bitbang
Built target bitbang_ft2232
Built target find_all
Built target bitbang2
[ 94%] Built target serial_test
[ 94%] [ 94%] Linking C executable stream_test
Built target eeprom
Built target bitbang_cbus
[ 94%] Built target baud_test
/home/michel/projects/libftdi/bindings/ftdi1.i:5: Error: Unable to find '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.
3. Your patch breaks bindings build if doxygen is not avalable, so xml => ftdi1_doc.i are not generated and build fails.
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,... :
In [4]: ftdi1.read_eeprom_location?
read_eeprom_location(context, eeprom_addr) -> (return_code, eeprom_val)
int
ftdi_read_eeprom_location(struct ftdi_context *ftdi, int eeprom_addr,
unsigned short *eeprom_val)
Read eeprom location
Parameters:
-----------
ftdi: pointer to ftdi_context
eeprom_addr: Address of eeprom location to be read
eeprom_val: Pointer to store read eeprom location
retval:
0: :: all fine
-1: :: read failed
-2: :: USB device unavailable
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.
Regards,
M.
