[Gdal-dev] OGRGeometry::Distance

[Matthew Perry]

Ari,

On 9/18/05, Ari Jolma <ari.jolma at tkk.fi> wrote:
> 
> It might be confusing to document the "intermediate" C/C++ API, which is
> between GDAL C++ and the swig-based language bindings, if that's what
> you mean. I mean from the users' point of view.


I agree. I think the C++ and the C methods are already documented 
seperately. What we really need is docs for the swig interface. 

However, all the
> swig-based language interfaces should be as similar as possible (or at
> least implement the common base), but I'm not sure if their docs can be
> based on some common meta information. Matthew, I wrote initial docs for
> the swig/Perl bindings, they at least list all existing methods, 


Wow. I didn't even know there were ogr/perl bindings! That's OK for me since 
looking at Perl code makes my head hurt ;-) Are they available anywhere? How 
did you generate these docs? 

I was thinking of an automated method to regenerate the docs every time the 
bindings changed. Python offers a very simple way to do this with the epydoc 
module. You document the classes directly in the code itself using their 
basic epytext markup:

def Distance( self, other ):
'''
Returns the minimum distance between this geometry and another.
@type other: OGR.Geometry
@param other: Geometry to calculate distance to.
@rtype: float
@return: Distance between Geometries
'''
return _gdal.OGR_G_Distance( self._o, other._o )

Then run one command to generate the docs:

epydoc -o /www/ogr_docs/ ogr

And you have complete class documentation. I've posted the example at 
http://perrygeo.net/ogr_docs/index.html . Of course the 
OGR.Geometry.Distance method was the only one I documented so it looks a 
little sparse but you get the idea. 

This technique would be acceptable IF all the swig interfaces were kept in 
sync with the Python version. 

Are there similar/better methods out there for maintaing perl docs? It seems 
that a solution where we maintain the class documentation in the code itself 
would be preferable to maintaining a separate document but this may be my 
inexperience talking.

Any thoughts?
-- 
Matt Perry
perrygeo at gmail.com
http://www.perrygeo.net
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/gdal-dev/attachments/20050919/bfcc7ea8/attachment.html