[Mapserver-dev] SWIG MapScript docs

[Sean Gillies]

On Feb 16, 2004, at 2:34 PM, Daniel Morissette wrote:

> Hi,
>
> We often get the comment from people who try to use Perl MapScript or 
> other SWIG-based MapScript that the docs are out of date or incomplete 
> and that what's there is hard to use. Is there something we could do 
> to improve that and make sure that the SWIG-based MapScript docs are 
> always up to date?
>
> In the case of PHP MapScript we have a mapscript/php3/README which is 
> used as the base for the website docs and as an ultimate reference for 
> all PHP MapScript stuff. This README is updated by the developers 
> everytime we change something to PHP MapScript so it's always up to 
> date.
>
> Perhaps the same could be done for the SWIG MapScript: we could create 
> a MAPSCRIPT.TXT file (or equivalent) in the mapscript directory 
> besides the mapscript.i file, and everytime mapscript.i is modified, 
> developers would be required to update the documentation file.  Then 
> users could at least go to that file to make sure they get the latest 
> and greatest docs.
>
> Just a thought... but I'm sure users would welcome that...
>
> Daniel

No argument; the SWIG mapscript documentation is deficient.

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

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.

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.

Just my $.02
Sean

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