[OpenLayers-Dev] Documentation sources and versions

[Christopher Schmidt]

On Sat, Apr 28, 2007 at 06:13:28AM +1000, Cameron Shorter wrote:
> Looking around at the documentation I've found 3 locations for it.
> 
> http://openlayers.org/doc/reference.html
> This seems to be run against 2.3?
> Where is the source for this documentation? Is it in SVN? Can I find the 
> 2.4rc2 version somewhere?

The source for this is gone. It was a workaround for the fact that I
didn't have working jsdoc output. Since it is a historical oddity, it
has now  been removed. (it was possible to generate this via the
'./docs.sh' script in the build directory.)

> http://dev.openlayers.org/docs/index.html
> I assume this is run against 2.4rc2?

Against SVN, once an hour.

> http://trac.openlayers.org/wiki/Documentation
> Is this still being maintained?

The idea is that the wiki will eventually have documentation for things
which don't make sense in JSDoc, like more complex paragraphs of text.

> Recommendation 1:
> * Put version number with documentation.

Documentation on the website is likely to always be based on the latest
SVN. Other documentation can be built based on the revision you have on
your own.

> Recommendation 2:
> * Deprecate at least one of the documentation locations in order to 
> reduce developer effort required to maintain it. I suspect 
> http://trac.openlayers.org/wiki/Documentation should be deprecated, or 
> at least we should remove the link to it from http://openlayers.org

That page should probably be reduced in content -- but right now, it has
examples that you can't find in any other documentatoin. One of these
things (because of the lack of jsdoc support for prototype-like
functionality in the current JSDoc) is the class structure that
http://trac.openlayers.org/wiki/Documentation provides. It does say on
that page:

"""
Automatically generated API documentation is available from JSDoc on
dev.openlayers.org.
"""

In general, I think that we just need a hell of a lot of work on
documentation, but I have neither the time nor inclination. Someone to
keep the wiki stuff up to date -- even if it's ust a class hierarchy --
would make me much happier, but until we have either that (or  better
jsdoc2 output), I'd like to keep the class outline we have. 

Regards,
> -- 
> Cameron Shorter
> Systems Architect, http://lisasoft.com.au
> Tel: +61 (0)2 8570 5050
> Mob: +61 (0)419 142 254
> 
> _______________________________________________
> Dev mailing list
> Dev at openlayers.org
> http://openlayers.org/mailman/listinfo/dev
> 

-- 
Christopher Schmidt
MetaCarta