Re: [Jsdoc-user] some questions regarding jsdoc

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

Hi,

> btw. when do you plan to release the next version of JSDoc?

Well, I was actually just about to release it yesterday evening, and
then I noticed that a bunch of the unit tests were failing. It looks
like this is just related to changes in the behaviour of the
preprocessor and probably nothing is really broken, so I just have to go
through and double-check all of that before I release it. To make a long
story short: hopefully I'll release in the next day or two (or maybe
even in the next hour or two). 

> > 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.
> 
> is there a pointer to follow this discussion? it's just that i cannot 
> think of any good reason at all why such globals should be excluded 
> from a documentation...

I just checked, and this has been entered as a request on SourceForge.
You can view the issue at
<http://sourceforge.net/tracker/index.php?func=detail&aid=1239787&group_id=30801&atid=400647>. I suppose the main thing I'm not sure about is if this should 
just become default behaviour or not. If it does just become default
behaviour, there's definitely a lot of potential for it to be a real
annoyance to existing users, so it might be introduced as a command-line
option, or global variables that are to be documented could have to be
marked with a @global tag or something like that. Any other suggestions?

> > 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?
> 
> nope, you're totally right. this is kind of a speciality of hop, the 
> application server we are using. script files are located in 
> directories which determine the prototype (or class) they belong to. 
> this way, we can define a method bar() in two (or more) directories, 
> say Foo and FooBar, and make them instance methods of different 
> prototypes. (it's not really good practice anymore and we are 
> currently elaborating on that, anyway).
> 
> but i don't want to bother you with such details. it's just that i 
> thought it would feel natural if JSDoc was to take the @member tag with 
> a higher priority and document a method according to it -- just as it 
> takes e.g. @extend simply as is without further checking if there really 
> is such a parent class...

Yes, this is another one of those things that is really difficult (or
impossible) to get right to satisfy everyone. The far-away plan for JSDoc
is to rewrite it in Java using Rhino, and then just let Rhino decide
what's what instead of me trying to fish it out with regular expressions
:)


Regards,

    Gabriel