[Helma-user] New helmadoc/jsdoc based reference

[Chris Zumbrunn]

On Feb 23, 2007, at 10:24 , Hannes Wallnoefer wrote:

> * 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.

Yes, it's due to trickery but would probably not be unavoidable. It's  
really the same issue you raised below, regarding res, req, app,  
session etc.

> * 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 initially had them documented as prototypes, like this...

Response.prototype.abort = function(){};

...but of course that's not correct either, since there is no such  
constructor and res really is instantiated in Java, not Javascript.  
There is a helma.framework.ResponseBean class in Java, but there is  
no prototype in Javascript. From the users perspective, the res  
singleton is all there is. There is no type.

I agree that the way I currently document all this is isn't entirely  
clean and I'm happy to change it. I'm just not sure how to better  
approach it without confusing new users even more.

You think it would be better to document them as Response.abort() etc  
even though Response will be undefined?

> * 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.

Ok, I agree.

> 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.

I think for the docs we include in the package, we just use the  
standard JSDoc output, without any custom templates, right?

So, we would make that the default helma package includes a "docs"  
directory with two sub directories, one for the framework and one for  
the helmalib. Is that what you had in mind as well?

Chris