[postgis-devel] [WKT Raster] API Reference

[Pierre Racine]

>0. Are we documentig API? If we are, C API too or SQL only?

I would concentrate on the SQL API since only a few people need doc on the C API. We are not really releasing  a C API like GDAL. Just make sure to carefully document the code.

>1. Integrated in Trac Wiki or separated as a bunch of HTML pages (perhaps Doxygen'ed)?

As you might have seen I started to document stuff at http://trac.osgeo.org/postgis/wiki/WKTRaster/Documentation01 and I'm just about to submit you a 10 pages document for revision :-)

I think this page is a good start not taking too much of our time and allowing others to contribute. I think Doxygen is very nice but it makes of the documentation a developer only task, preventing other users inputs (like with the actual PostGIS one). And sometimes (often) developpers are very bad documention writers... At some point we might be able to find some good writers willing to contribute in the official doc instead of just in the users wiki. In brief for now I think a single wiki page will make us produce a better start than starting with a very pro Doxygen setup.

>2. If Trac, all one big Wiki page or C API/SQL function per Wiki page.
>The first option is simple. For the second one, I've been thinking of
>something like:
>
>http://trac.osgeo.org/postgis/wiki/api/core/rt_raster_to_wkb
>
>http://trac.osgeo.org/postgis/wiki/api/pg/RASTER_envelope
>
>http://trac.osgeo.org/postgis/wiki/sql/RT_Width

I would go for simplicity: this page only for now... In most cases, each function need only a couple of line, not a page.

>3. Or, WKT Raster should grab doc engine from PostGIS and
>feed it with its own meat, so in future it's easy to merge
>both, WKT Raster doc into PostGIS doc?

Later maybe? If we merge with PostGIS we have to copy and paste. 

How easy is it to write stuff (other than API) for Doxygen? I find nothing is easier than a Wiki... Login, Edit, Write, Save... Simplicity and speed is the key if we actually want the doc to be writen and updated. If it's just a bit more complicated we just won't do it.

Pierre