[Mapserver-dev] SWIG MapScript docs

[Sean Gillies]

On Feb 17, 2004, at 9:40 AM, Daniel Morissette wrote:

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

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!

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

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.

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.

cheers,
Sean
--
Sean Gillies
sgillies at frii dot com
http://users.frii.com/sgillies