[postgis-devel] Doxygen

[Paragon Corporation]

Kevin,

Great job.  Thanks for doing this and I see its working already.  This
really makes me very happy.  My latest changes to the source have appeared
already.

Actually I added a link to WKT Raster already under Development and WKT
Raster section, but I won't be offended if WKT Raster folks move it to
somewhere more appropriate.
http://trac.osgeo.org/postgis/

One thing I did notice while I was looking at all the nice call graphs and
so forth, is that while our code in many places has useful descriptions for
the functions,  we seem to be missing some * so that they are not appearing
in the documentation.  So our comments are generally autodoc unfriendly.

It seems a shame that if we put in effort in describing our functions that
they don't appear in the dev docs.  For example lwcollection.c I went in and
put * next to those that were already commented -- 

http://postgis.refractions.net/documentation/postgis-doxygen/dc/d71/lwcollec
tion_8c_e22dfa24dd7e5bf731b03d6ffa0e0a93.html#e22dfa24dd7e5bf731b03d6ffa0e0a
93

Of course I don't have that much experience with Doxygen so not sure which
commenting style makes sense.  The asterick approach seems too close in
style to inline code comments you don't need to see except when you are in
the code so perhaps the QT style would make more sense.

Then I guess there are several switches we need to be aware of that we can
put in front of comments to make the documented comments more useful and
appear in the right places in the documentation which would add a tiny bit
of effort to our process, but make our dev documentation all the more useful
to prospective developers.

http://www.stack.nl/~dimitri/doxygen/docblocks.html

like \struct, \fn, \brief \file \enum  seem to be the most relevant for our
code.

Thanks Regina  

-----Original Message-----
From: postgis-devel-bounces at postgis.refractions.net
[mailto:postgis-devel-bounces at postgis.refractions.net] On Behalf Of Kevin
Neufeld
Sent: Friday, May 01, 2009 12:38 AM
To: PostGIS Development Discussion
Subject: [postgis-devel] Doxygen

Hi all,

I've added a nightly build script to the our buildbot that generates html
Doxygen documentation for PostGIS trunk and WKTRaster.

http://postgis.refractions.net/documentation/postgis-doxygen
http://postgis.refractions.net/documentation/raster-doxygen

I've added a link to the postgis doxygen on the wiki, but was not sure where
a link to the raster dox should go - I'll let you WKTRaster folks do that.

There is a new doxygen.cfg.in configuration file in the doc directory for
both projects that Doxygen uses to generate the dox.  Feel free to update
the config files to tweak the dox if you want.

Cheers,
Kevin
_______________________________________________
postgis-devel mailing list
postgis-devel at postgis.refractions.net
http://postgis.refractions.net/mailman/listinfo/postgis-devel