[OpenLayers-Dev] Documentation sources and versions

[Cameron Shorter]

Thanks for the clarifications.

I probably should point out what triggered my questions. I've been 
answering questions from a new user who was reading about vector 
functions from JSDocs (built from the trunk), but using the 2.3 release.

It would have helped if we publish a version of JSDocs for each release, 
and include version number in the docs.

The old version of JSDoc includes an option to pass in header 
information into the JSDoc output. We used this feature in Mapbuilder to 
pass in version information during the build process. We can probably do 
something similar for OL.

Christopher Schmidt wrote:
> 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
>>
>>     
>
>   


-- 
Cameron Shorter
Systems Architect, http://lisasoft.com.au
Tel: +61 (0)2 8570 5050
Mob: +61 (0)419 142 254