Ari,<br><br><div><span class="gmail_quote">On 9/18/05, <b class="gmail_sendername">Ari Jolma</b> <<a href="mailto:ari.jolma@tkk.fi">ari.jolma@tkk.fi</a>> wrote:</span><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
It might be confusing to document the "intermediate" C/C++ API, which is<br>between GDAL C++ and the swig-based language bindings, if that's what<br>you mean. I mean from the users' point of view.</blockquote><div>
<br>
I agree. I think the C++ and the C methods are already documented
seperately. What we really need is docs for the swig interface. <br>
</div><br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"> However, all the<br>swig-based language interfaces should be as similar as possible (or at
<br>least implement the common base), but I'm not sure if their docs can be<br>based on some common meta information. Matthew, I wrote initial docs for<br>the swig/Perl bindings, they at least list all existing methods, </blockquote>
<div><br>
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? <br>
<br>
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:<br>
<br>
def Distance( self, other ):<br>
'''<br>
Returns the minimum distance between this geometry and another.<br>
@type other: OGR.Geometry<br>
@param other: Geometry to calculate distance to.<br>
@rtype: float<br>
@return: Distance between Geometries<br>
'''<br>
return _gdal.OGR_G_Distance( self._o, other._o )<br>
<br>
Then run one command to generate the docs:<br>
<br>
epydoc -o /www/ogr_docs/ ogr<br>
<br>
And you have complete class documentation. I've posted the example at
<a href="http://perrygeo.net/ogr_docs/index.html">http://perrygeo.net/ogr_docs/index.html</a> . Of course the
OGR.Geometry.Distance method was the only one I documented so it looks
a little sparse but you get the idea. <br>
<br>
This technique would be acceptable IF all the swig interfaces were kept in sync with the Python version. <br>
<br>
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.<br>
<br>
Any thoughts?<br>
</div></div>-- <br>Matt Perry<br><a href="mailto:perrygeo@gmail.com">perrygeo@gmail.com</a><br><a href="http://www.perrygeo.net">http://www.perrygeo.net</a>