Re: [Jsdoc-user] some questions regarding jsdoc

[Gabriel R. <gab...@gm...>]

On Tue, Nov 15, 2005 at 01:25:09PM +0100, tob...@or... wrote:
> 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.
> 

Thanks for the info about how you're using JSDoc. It's always nice to
hear things like this :)


> 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 = "Hello, World!";

I've just fixed this problem, thanks for reporting it. A while back I
added a step in the preprocessor to shrink down all string literals to
avoid problems that were occurring with segfaults in some builds of
perl, without noticing that it broke this functionality. I've removed
that preprocessor step, as I'm now encouraging people to get a build of
perl that doesn't segfault on recursive regexes instead of trying to
work around it in JSDoc.


> 
> 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 
>  */
> var globalVariable = 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).
> 

For the moment, global variables like this are simply ignored. There's
been talk of adding a '@global' tag or something similar to tell JSDoc
to add these to the global class, but I haven't implemented it yet. I'd
say it's coming, but I can't say when exactly.

> 
> 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() {
> }
> 
> /** 
>  * @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.
> 

If two versions of function bar are in the same scope as shown above,
only one of them will be available at execution. JSDoc can also only
handle a single version of a function with a given name, although I
believe JSDoc will take the first version it find, as opposed to a JS
interpreter, which will take the last. Or am I missing something?

Thanks a lot for using JSDoc, as well as posting to the list. If there's
anything else, just let me know.

Regards,

    Gabriel