[Helma-user] New helmadoc/jsdoc based reference

[Hannes Wallnoefer]

Hi Chris,

thanks for the excellent work, and for sharing it. I think this looks
very good.

I have a few minor issues:

* All the global constructors and functions are marked as <static>. I
don't think this is correct. These are properties of the global
object, not some object constructor. Maybe this is due to some trick
necessary to generate the page, in which case I could live with it.

* The req, res, app, path etc objects are documented with their
variable name. I think it would be better to assume type names such as
Request, Response, Application, Path for the documentation and treat
the global variables as singletons of these types (which in fact they
are).

* I don't think it's a good thing to mix JSdoc and JavaDoc, as both
are targeted to distinct groups of developers. I think it'll be
confusing for Helma newbies to see the Helma Javadoc, and once you are
proficient enough to make use of it, you'll know where to find it.

Finally, we should proceed fast to integrate this into the Helma
package build. Helma 1.6.0 is long overdue, and missing js
documentation is the only thing missing.

hannes

2007/2/18, Chris Zumbrunn <chris at zumbrunn.com>:
> 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
>
> _______________________________________________
> Helma-user mailing list
> Helma-user at helma.org
> http://helma.org/mailman/listinfo/helma-user
>