[OpenLayers-Users] Javascript documentation

[Christopher Schmidt]

On Tue, Mar 13, 2007 at 01:39:32PM +1100, Glen Stampoultzis wrote:
> I noticed the javascript comments in open layers look a lot like javadoc so
> I thought that maybe you were using a tool to convert them to documentation
> but then I looked in your source tree and noticed a bunch of text file's
> that seem to be used for this purpose.  I was wondering why duplicate this
> in two places.  Are the comments in the javascript designed to be extracted
> by a tool?

JSDoc is a very complex tool (read: it's powered entirely by 5 multiline
regular expressions). It segfaults when running over all the OpenLayers
code. For a long time, we didn't have a way to get anything out of it if
the class had a subclass.

We've fixed some of these issues, and will be deploying new JSDoc pages
with the 2.4 release. At that time, the doc/*.txt files which I wrote by
hand will go away. Trust me, no one knows more than me how much they
suck: those were about 30 hours of my life I'll never get back.

Regards,
-- 
Christopher Schmidt
MetaCarta