[Helma-user] New helmadoc/jsdoc based reference

[tobias.schaefer at orf.at]

hi chris

first of all: i really adore the output you achieved from running jsdoc over the artificial code files. nice templating work!

as i think this documentation should be published at helma.org the sooner the better (or: finally <g>), i'd like to help answering some questions that arose:

1. running jsdoc as ant task

stefan pollach has solved this issue and we included it in jala's hopkit. it provides defining tasks in javascript and pre-processes the code files to reduce jsdoc hic-ups to a minimum. you can find all necessary information in the source code of hopkit's lib.xml [1].

2. eliminating the global constructor

actually, i am not sure why you're doing this, anyway. simply defining the global functions as is (ie. without defining a "global" constructor function and prefixing any global function with "global.") should give you more reasonable output.

as an example you might take a look at this url:
http://p3k.org/source/lib3k/trunk/docs/Global.html

the naming of the global "class" can be manipulated with jsdoc's --globals-name parameter.

3. objects without an actual constructor

to avoid having non-existent constructor references for app, req, res etc. in the jsdoc output you can use global functions together with jsdoc's @member tag and then remove the constructor function from your "pseudo"-code:

/** 
 * Description of the method
 * ...
 * @member app
 */
function methodName(/* ... */) {
   //...
};

using such constructs with jsdoc you won't get any constructor in the output anymore. the link text in the left frame ("All Classes") will be the same as what you put after @member ("app" in this case).

hope that helps, and that this excellent documentation will soon find a prominent place at helma.org.
:)

keep up the good work,
tobi


--
[1] https://opensvn.csie.org/traccgi/jala/browser/branches/release-1.1/util/HopKit/lib.xml#L159