[postgis-devel] [WKT Raster] API Reference

[Mateusz Loskot]

Pierre Racine wrote:
>> 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.

OK

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

OK. I've not reviewed it, but I will.

Honestly, I'm sceptic about two things:

1. If we really need versioned documentation at this moment, before we
don't have 1.0.0 release. Who is going to maintain and merge scattered
docs for micro-versions?

2. One big document. I'd trust the idea of hypertext :-)
IMHO, FAQ definitely belongs to Wiki, not to manual.

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

In fact, I don't think Doxygen would be helpful for us.
PostGIS doc engine seems better.

> And sometimes (often) developpers are very bad documention writers...

or most often :-)

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

I only brainstormed about Doxygen, actually, I asked.
Big documents...I'm sceptic but you decide.

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

Yup, PostGIS approach works here well.

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

Not exactly. PostGIS uses XML, so we will need to rewrite.

> How easy is it to write stuff (other than API) for Doxygen?

It's easy, but let's give it up :-)

> I find
> nothing is easier than a Wiki... Login, Edit, Write, Save...

Yes, that's right.

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

-> hypertext!

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org