[OpenLayers-Dev] OpenLayers API doc

[christopher.schmidt at nokia.com]

On Aug 9, 2011, at 3:57 AM, ext Marc Jansen wrote:

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

While I'd love to see better API Documentation, I despair of ever finding
tools that do it sufficiently. My recent perusal of the various competitors
to OpenLayers in documentation basically came to the conclusion that
there are two options: tons of manual labor, or bad docs :) But I'm happy
to go with whatever people want to do for it -- I don't think that any
of the tools are likely to lose us what we already have with NaturalDocs.

That said, In my experience, what people want is not better API docs (which
probably won't help a ton), but more concrete usage demonstrations -- expanded
content like http://docs.openlayers.org/library/introduction.html to cover
the entire library. In looking at the things that people said they liked
better, that was pretty much the clear indication that people would like
documentation the most: thorough and complete walkthrough-style examples
of as many parts of the library as possible.

http://crschmidt.net/blog/archives/472/perceived-flaws-ofopenlayers/ has
the results of what I looked through, which examined 5 different web mapping
libraries stated to be alternatives to OpenLayers, and what documentation
they offer.

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

The Sphinx stuff inside of the GeoExt library looks a bit more like line
noise than I'd personally prefer, and I'm not sure how much benefit the
GeoExt docs offer over the NaturalDocs we have; I think the complaint with
OpenLayers is less about how the docs look, and more about what the docs 
*are*. I'm willing to adjust that notion (even without evidence; it's not
a strong conviction), but I think that sphinx would be a major change,
and I'm not sure how much it would help?

Although, it would let us better integrate our API docs with the rest of
our docs -- for that reason alone, it's almost certainly worth considering.
I think tighter integration between reference docs and prose documentation
is absolutely neccesary to help improve the perception of the documentation
in OpenLayers.

-- Chris

>> [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
> 
> _______________________________________________
> Dev mailing list
> Dev at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/openlayers-dev