[Mapserver-dev] SWIG MapScript docs

[Daniel Morissette]

Sean Gillies wrote:
> 
> I don't think it's quite fair to cast me as advocating no 
> documentation.  I'm
> on record in many places (list, bugzilla) proposing discussion of improving
> mapscript documentation.  We're finally having it, and that's great!
> 

Sorry for misinterpreting your previous email.  I have to admit that I 
was surprised to see that reply from you when I know how much you seemed 
to care about proper software development practices.

So we're thinking along the same line, that's great.

> I think we simply disagree on what it means to properly document the code.
> A text file like the PHP/mapscript README doesn't quite satisfy me.  It's
> not as reliable as the code itself, and is also not in a state from 
> which we
> can generate excellent language-specific docs with hyperlinks between 
> classes
> and symbols (javadoc and pydoc are what I'm thinking of).
> 

Agreed, but at least we've got that README, and it turns out that users 
of other MapScript flavours use it as an ultimate reference... it's a 
comment from one of those Perl MapScript users that led me to starting 
this thread yesterday.

Note that it doesn't have to be a text file.  I just know that text 
files work because they are simple enough for anyone to update. 
Sometimes when you aim too high you end up with nothing... mostly when 
dealing with volounteers from around the world.  It's easier to 
encourage someone to update a text file than it is to force them to 
learn a bunch of documentation procedures or to force them to use 
specific tools that they are not used to.

If we can find another format that's easy to maintain and that provides 
the ability to generate language-specific docs with hyperlinks and nice 
graphics then I'm all for it.


> You mention Doxygen.  Wouldn't we have to write a skeleton mapscript module
> all over again to feed into Doxygen?  If so, I'd rather just do it in 
> Python
> and use epydoc to generate some javadoc-like stuff.
> 

Nope. Doxygen directly uses comments embedded in the source code. If I'm 
not mistaken it uses almost the same syntax as javadoc.

The drawback is that Doxygen would probably treat mapscript.i as a C/C++ 
file and document the functions as C/C++ functions. There may also be 
issues related to the .h files that are #included in mapscript.i, so we 
may need to do some work to control what Doxygen extracts and what it 
doesn't.

While this wouldn't be perfect, it would be better than nothing, and the 
textual description of the function's behavior, its inputs and its 
outputs would still apply to all languages.


> What about XML instead of a text file?  We could render it into HTML in 
> a way
> that emulated the Doxygen docs.  There must be a DTD we can use.
> 

Sure... as long as the XML structure is simple enough to be picked up 
quickly by the developers.  We could probably explore the DocBook route 
since that's what is used for the rest of the MapServer docs.

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