jsdoc-user

RE: [Jsdoc-user] some questions regarding jsdoc

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

hi gabriel

thanks for your quick reply.

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

great! i certainly encourage you to avoid fixing other people's bugs.
(but sometimes it just has to be :)

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

> 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=20
think of any good reason at all why such globals should be excluded=20
from a documentation...

> 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=20
application server we are using. script files are located in=20
directories which determine the prototype (or class) they belong to.=20
this way, we can define a method bar() in two (or more) directories,=20
say Foo and FooBar, and make them instance methods of different=20
prototypes. (it's not really good practice anymore and we are=20
currently elaborating on that, anyway).

but i don't want to bother you with such details. it's just that i=20
thought it would feel natural if JSDoc was to take the @member tag with=20
a higher priority and document a method according to it -- just as it=20
takes e.g. @extend simply as is without further checking if there really =

is such a parent class...

ciao,
tobi


ps. sorry for the list-inadequate layout of my first e-mail... i hope
this one's better now.

RE: [Jsdoc-user] some questions regarding jsdoc

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

hi gabriel

> a long story short: hopefully I'll release in the next day or two (or
> maybe even in the next hour or two).     =20

good news! looking forward to the release, but no hurries.

> 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?     =20

i consider a command-line option the best solution but i would be fine =
with the @global tag as well. you know your established user community =
best; thus, you will make the right decision to avoid breaking something =
for them anyway.
=20
> 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 :) =20

well, we are working with java *and* rhino and as i already said we =
really need a good and meaningful javascript documentation feature. =
(certainly, a java version of jsdoc would be much more valuable for us =
than the perl one -- no matter how excellent it already is.) do you =
think we could join our forces here?

btw. i found some more issues; do you want me to report them as bugs =
immediately or is it ok if i post them here again?

ciao,
tobi

Re: [Jsdoc-user] some questions regarding jsdoc

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

Hi,

> > a long story short: hopefully I'll release in the next day or two (or
> > maybe even in the next hour or two).      
> 
> good news! looking forward to the release, but no hurries.

As you've maybe already seen, the new version was released a couple of
days ago (I'm just a bit behind in handling e-mail....)

> > 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 :)  
> 
> well, we are working with java *and* rhino and as i already said we really need a good and meaningful javascript documentation feature. (certainly, a java version of jsdoc would be much more valuable for us than the perl one -- no matter how excellent it already is.) do you think we could join our forces here?

Well, there are still some issues that I'm thinking about with all of
this, not to mention the fact that putting aside enough time to really
think all of this through is proving to be a challenge in itself :(
However, in any case I'm interested in going towards a version based
around a real parser, and java/rhino certainly looks like the best way
to go. Once things do start moving in that direction, help will
certainly be appreciated!

> btw. i found some more issues; do you want me to report them as bugs immediately or is it ok if i post them here again?

Well, either is ok, although it's nice to have them actually logged in
the bug-reporting system so I don't forget about them. Actually, what's
nicest is if they're reported in the bug-reporting system AND posted in
this list, but I realize that takes more time and effort, so just do
what you've got time/energy for.


Gabriel

RE: [Jsdoc-user] some questions regarding jsdoc

[<sch...@ma...>]

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

Same goes for us, a example:

er have applications in folders organized like:

applications/app/em01/em01.xul
applications/app/em02/em01.js
applications/app/em02/em02.xul
applications/app/em02/em02.js

each xul file has a script tag like <script src=""em01.js" />

while each js page contains our so called controller (getting vars 
fromthe ui and sticking them into apis)

em01.js
function FXPAGE() {

}

FXPAGE.prototype.load() {

}

....

So we could use that too. btw: last tip for own @tags worked well. Greets
Sebastian 
-----------------------------------------------------------------------------
  - Mayflower GmbH - http://www.mayflower.de - E-Mail: in...@ma... -

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