[Mapserver-dev] SWIG MapScript docs

[Daniel Morissette]

Um... it seems that we have different views on the issue... more 
comments below...

Sean Gillies wrote:
> 
> I don't know if maintaining a text doc is a solution I want to spend time
> on (personally).  My thinking is that for developers, everything is in
> mapscript.i. 

There are almost no comments in mapscript.i, so are you saying that 
everytime you need to know what a function does you dig in mapscript.i 
to find the corresponding method, then drill down into the source until 
you find the meaning of argument a, b, and c and what return value you 
can expect?

I think it has to be made easier than that, even for developers.

> End users, on the other hand, want nicely formatted docs
> in the style of their target language.  The text file could fall into
> a crack in the middle.
> 

Formatting is nice to have, but I don't think it is that important, as 
long as the information is there, that it's accurate and in a readable 
format.


> SWIG is a great tool for building useful modules for programmer/hackers.
> It's not so great for making modules for end users.  And I think that's
> just the way it is.
> 

It's just too easy to blame SWIG for that.  It's the responsibility of 
the developers to document the stuff they write.  Maybe SWIG could have 
come with some documentation tool, but since it doesn't, that doesn't 
remove our responsibility of properly documenting the code we write.


> More and more I think the solution may be that we maintain core
> functionality with mapscript and that Perl/PHP/Python/Ruby developers
> extend mapscript with modules that leverage these languages' own specific
> documentation systems.
> 

I think we still need a central location where all the core mapscript 
functions are documented in a simple format, and as close to the source 
code as possible so that it's easy for the developers to maintain.

This core documentation can then be used to derive language-specific 
docs if someone wants to.  I don't think we can realistically expect 
that a developer who implements a new method in mapscript.i will go and 
update 4 sets of documentation in 4 different formats for 
Perl/PHP/Python/Ruby.

I wonder if we could use Doxygen to document mapscript.i ... Doxygen is 
usually quite powerful with other languages.  I just don't know if it 
would be able to understand the structure of a swig interface file.

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