[Mapserver-dev] SWIG MapScript docs

[Daniel Morissette]

Steve Lime wrote:
> That's cause we do a shitty job of keeping the authors (like Lowell)
> up-to-date. 


Well, nobody knows better than the developers themselves what a function 
does and what its inputs/outputs are.  Someone like Lowell can do some 
polishing of the docs, but at least the first pass of the documentation 
for a new method or class needs to be written by the developer who 
implemented that method or class.


> We're also spreading
> ourselves thin by trying to maintain a full-blown version for every
> language, including PHP. That's 
> probably not necessary, at least for SWIG. There are syntactical
> differences to be sure and those 
> could be addressed up front in the documentation, but it's funny how
> much perl and PHP code
> look alike sometimes. My preference would be to:
> 
> 1) make every effort to keep versions in sync, that is, don't improve
> one without alerting the other camp

Yup.  As discussed before, we need that independently of the 
documentation issue, and a possible way to handle this is through bugzilla.

For those who were not part of that discussion, what I suggested was 
that when someone makes a change to a flavor of MapScript (SWIG or PHP) 
then he creates a bug to document his change, and also another bug for 
the other group to apply the same change (with a reference to the 
original bug).

> 2) look at some sort of integrated set of documentation
> 3) the documentation is a HOWTO just like all other MapServer
> documentation
> 

It seems that structured text (see other messages in this thread) may be 
a way to go for that integrated set of docs. Let's see...

> 
> MapScript should be viewed as one, unified, API rather than the 6 or so
> seperate ones it is today. That
> was the idea originally.
> 

Agreed.

BTW, we also know that at least the PHP version has some 
exceptions/differences that would need to be documented (there are 
probably also exceptions between SWIG versions as well).  So the 
integrated documentation needs a mechanism to document exceptions per 
language similar to what you described for JavaScript vs browser exceptions.

I think it's very feasible to have a unified set of docs, we've done it 
in other projects where a C API doc produced by Doxygen is reused for 
PHP or VB/Delphi and that works very well: you just need to read the 
documentation differently depending on your scripting language.

e.g. the following docs for MITAB.DLL applies to C, Delphi, VB, and 
MapBasic, with a few exceptions documented for VB:
http://mitab.maptools.org/mitab-docs/mitab__capi_8cpp.html

Daniel
-- 
------------------------------------------------------------
  Daniel Morissette               dmorissette at dmsolutions.ca
  DM Solutions Group              http://www.dmsolutions.ca/
------------------------------------------------------------