[OpenLayers-Dev] OpenLayers API doc

[Marc Jansen]

Hi Eric,

good to bring this topic up again!
 

On 09.08.2011 09:45, Eric Lemoine wrote:
> Hi
>
> Some of us among the OpenLayers devs have been contemplating the idea
> of offering a better API documentation for OpenLayers.

I'd count myself to those devs. And from the first feedback about common
pitfalls/annoyances of OpenLayers I see that many users do not like our
current documentation.

> With this email
> I'd like to gather comments, opinions, and ideas regarding the current
> API documentation, and what we should do to improve it.
>
> I've been looking at JsDoc lately. (Yes, I know we moved from JsDoc to
> NaturalDocs 4 years ago! [1]) Using JsDoc annotations would provide us
> with two things: (1) generate a nice API documentation using JsDoc
> Toolkit [2], and (2) fully benefit from the Google Closure compiler
> (code optimization, type checking, warnings, etc) [3]. What I also
> find interesting about JsDoc is that it is a standard for annotating
> JavaScript code; other tools, like dox [4], support it.
>
> Any comment or experience is welcome! Thank you.

We have worked with JsDoc and liked it. What about the usual suspect
Sphinx? And an output equivalent to the one of GeoExt?

> [1] <http://osgeo-org.1803224.n2.nabble.com/finally-fed-up-with-jsdoc-td1833145.html>
> [2] <http://code.google.com/p/jsdoc-toolkit/>
> [3] <http://code.google.com/closure/compiler/docs/js-for-compiler.html>
> [4] <https://github.com/visionmedia/dox>
>
> PS: I'm interested to work on that at the FOSS4G code sprint.
>
I am also interested in this particular topic and would gladly help at
the FOSS4G codesprint.

Best regards,
Marc