[Gdal-dev] Documenting the Swig bindings

[Frank Warmerdam]

Ari Jolma wrote:
> Bindings developers,
> 
> What do you think, would it be a good idea to document the bindings 
> directly in code? Are the different language versions similar enough 
> that it would make sense to write documentation into the interface 
> files, and then produce the docs with doxygen? The language 
> differences/particulars could be covered in a separate section perhaps.
> 
> I made this try: http://map.hut.fi/doc/GDAL_OGR_Bindings/html/index.html
> 
> The only problem is that doxygen needs some help with the *.i files. I 
> used the doxygenfilter. I extended it with a very simple 
> SwigInterfaceFilter, which basically removes the Swig-specific 
> %-commands and removes the "Shadow" string before it gives the file to 
> doxygen. Otherwise I just created almost vanilla Doxyfile and ran doxygen.

Ari,

I'm at best lukewarm on this idea.  The generated bindings are still
in terms of the C++ types ("char **options" for instance) so I don't think
the users are getting that much support in their own language. And it still
seems to leave us needing to duplicate the meaningful portion of the docs
unless I'm misunderstanding the intent.

Best regards,
-- 
---------------------------------------+--------------------------------------
I set the clouds in motion - turn up   | Frank Warmerdam, warmerdam at pobox.com
light and sound - activate the windows | http://pobox.com/~warmerdam
and watch the world go round - Rush    | President OSGeo, http://osgeo.org