[Jsdoc-user] some questions regarding jsdoc

[<tob...@or...>]

hi there

first of all, congrats for this great tool. i am very delighted using =
jsdoc with javascript code and cannot think of working without the =
resulting api docs anymore.

if i might introduce myself shortly: i am a developer at the online =
branch of austrian broadcast station ORF [1]. we are using and =
developing a java-based, open-source application server called HOP (or =
helma object publisher) [2] which incorporates rhino [3] to enable us =
writing the production code in ecmascript.

so we produce pretty a lot of javascript code and thus, my colleages and =
me are very interested in good documentation -- like the one jsdoc =
provides.

thus, we are really keen on extensively using jsdooc for our basic =
documentation. however, i just noticed some (minor) things troubling us =
and i wanted to let you know about them:

1. string constants (marked with the @final tag) do not appear in a =
meaningful way on the page of "constant field values" (see attached =
screenshot). i expected to see the actual string value, instead all i =
get is a cryptic "s"...

the code causing the "duplo.TEST" entry is here:

/**
 * @final
 */
duplo.TEST =3D "Hello, World!";


2. i wondered a lot about what happens to global fields, ie. variables =
which aren't assigned a function but a "simple" value, like:

/**
 * @type Number=20
 */
var globalVariable =3D 123;

it does not show up anywhere in the jsdoc-generated output but actually, =
i expect it to become a field in GLOBALS (or whatever name i choose with =
the --globals-name argument).


3. if i am using a function name twice, once globally and another time =
for a class method, one of them is left out in the docs. e.g.

function bar() {
   return 123;
}

/**
 * @constructor
 */
function Foo() {
}

/**=20
 * @member Foo
 */
function bar() {
   return "abc";
}

i expected to find bar() twice in the generated index, once as method of =
the Foo class, and once as global function. but all i get is =
documentation about the class method.


hopefully, i am not stating anything obvious or redundant (actually, i =
took a look through the bug reports and mailing-list messages but might =
have missed something).

moreover, i hope you find this information valuable and probably can =
solve these issues.

best regards,
tobi


--
[1] http://orf.at
[2] http://helma.org
[3] http://www.mozilla.org/rhino/