[Gdal-dev] OGRGeometry::Distance

[Ari Jolma]

Matthew Perry wrote:

>
> 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?

well, looking at Python code makes my heart cry ;-)

temporarily at: http://map.hut.fi/gdal-perl/

these docs are hand-made pods (well, I used some throw-away scripts to 
make the skeleton), converted to HTML with pod2html

>
> 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:


With Perl you can add docs to a module similarly and when the module is 
installed, the doc is automagically available as a man page. With swig 
though, it seems that the pod has to written into a separate file.

>
> 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.


ok, nice, similar to what javadoc does (but frames...grr), the pod2html 
is a bit old-fashioned but I don't know of anything more modern, I use 
the man pages or code usually

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


I'm missing parameter types in the methods, for example in Perl, the 
CopyLayer method's param options is a reference to a list of strings, 
and that is not obvious from that doc. That kind of info is necessary 
for the programmer (scripter).

>
> 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.


I like the idea of having the doc right next to the code and am 
disappointed because swig does not seem to allow that in the case of 
Perl. In this case we, however, would be best of having the docs in the 
swig interface files (ogr.i etc), but they would need to be written in 
language-independent way. I'm not sure if that's doable.

Ari

>
> Any thoughts?
> -- 
> Matt Perry
> perrygeo at gmail.com <mailto:perrygeo at gmail.com>
> http://www.perrygeo.net 



-- 
Prof. Ari Jolma
Kartografia ja Geoinformatiikka / Cartography and Geoinformatics
Teknillinen Korkeakoulu / Helsinki University of Technology
POBox 1200, 02015 TKK, Finland
Email: ari.jolma at tkk.fi URL: http://www.tkk.fi/~jolma