[OpenLayers-Dev] OpenLayers API doc

[Paul Spencer]

I've had a chance to be playing with jsdoc and google closure compiler a bit lately and I would say that it is not very easy to script the conversion in a meaningful way.  There are a few 'quick' things that can be done to get jsdoc to produce some documentation such as adding @class, @lends, @constructs and @extends in specific places that could be automated.  Dealing with parameters is more complex and will probably have to be done by hand, especially getting the type information nailed that will make the warnings from the compiler much more interesting.  Also, naturaldocs does 'intelligent' things with longer descriptions but jsdoc requires that html markup be added to create headers, paragraphs, lists etc.  Again, something that might be scriptable but probably needs quite a bit of hands on to get it to work smoothly

Cheers

Paul


On 2011-08-09, at 3:07 PM, Matt Priour wrote:

> I think the similarity between Natural Docs and JSDoc that the majority of
> conversion could be done via script.
> There are more documentation options and IDE's that understand JSDoc than
> Natural Docs. So I think it certainly couldn't hurt.
> 
> However, I agree with Christopher that the real need is walkthrough style
> tutorials and possibly even a "code playground" similar to what Google APIs
> has. Additionally, regularly highlighting uses of OpenLayers in the wild
> would help people understand what is possible with this great library. The
> issue is and always has been that such documentation and community
> cheerleading takes time and that is a very expensive commodity for most of
> the active OpenLayers devs and power users.
> 
> Matt Priour
> Kestrel Computer Consulting
> 
> -----
> Matt Priour
> Kestrel Computer Consulting
> --
> View this message in context: http://osgeo-org.1803224.n2.nabble.com/OpenLayers-API-doc-tp6667194p6669324.html
> Sent from the OpenLayers Dev mailing list archive at Nabble.com.
> _______________________________________________
> Dev mailing list
> Dev at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/openlayers-dev


__________________________________________

   Paul Spencer
   Chief Technology Officer
   DM Solutions Group Inc
   http://research.dmsolutions.ca/

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/openlayers-dev/attachments/20110809/09592d4e/attachment.html