[Helma-user] New helmadoc/jsdoc based reference

[Chris Zumbrunn]

Hi there,

In order to share the current state of the ongoing documentation  
effort, I uploaded several renderings of what I've been experimenting  
with. Hopefully, the core reference is now pretty much completely  
documented. If you notice mistakes or any hidden jewels that are  
still missing, please let me know. The same goes for things you think  
should be deprecated and that aren't marked as such.

All the built-in properties and methods are now documented using  
javadoc style comments in "artificial" code files:

http://helma.zumbrunn.net/reference/source/

These files are checked into the CVS repository as "reference" in the  
apps module:

http://adele.helma.org/source/viewcvs.cgi/reference/

If this reference is included in an application as a repository, the  
"artificial" code lives inside the core* prefixed prototypes and  
would not effect a running application. This makes it possible to  
include the reference as a repository during development in order to  
see the documentation for the built-in methods and properties  
together with the documentation for the application that is being  
developed, when accessing the helmadoc generated documentation  
through the showAPI and renderAPI links in the manage application. An  
example of how this currently looks like, using the welcome app as a  
guinea pig, can be seen here:

http://helma.zumbrunn.net/reference/helmadoc/

Of course, having javadoc formatted source files for our reference  
also opens up all kinds of other posibilities, such as using JSDoc to  
render the documentation or using the files as libraries for code  
completion and inline documentation in Aptana. Here is an example of  
a rendering using JSDoc:

http://helma.zumbrunn.net/reference/jsdoc/

The advantage of this approach is that it looks very much like what  
we are all used to from standard javadoc generated documentation, for  
example the docs for Helma's Java API:

http://helma.zumbrunn.net/reference/javadoc/

Using JSDoc, I also experimented with templates that would adjust the  
look & feel to integrate with the current Helma website. Here are  
three different renderings, one for only the built-in core  
functionality, one for the core + helmaLib and one for the core +  
helmaLib + the new jala lib:

http://helma.zumbrunn.net/reference/core/
http://helma.zumbrunn.net/reference/corelib/
http://helma.zumbrunn.net/reference/combined/

The general idea in all this is to come up with a way of formatting  
the files in a way that will work reasonably well for as many  
different use cases as possible, including helmadoc, JSDoc, JSDoc2  
and scriptdoc. Targeting all these different tools is a bit of a  
compromise, which can cause some minor problems in any of the three  
environments currently.

Any critic, suggestions or other feedback will be very much appreciated.

Cheers,
Chris