inner functions with var are treat as __globals__

[GoogleCodeExporter]

function a(){
  var b = function(){}
}

such above code, jsdoc-toolkit will generate b as global functions. the latest 
version.

Original issue reported on code.google.com by XianAn.C...@gmail.com on 24 May 2008 at 9:12

[GoogleCodeExporter]

I'm using Version 2.0.0 (which is the latest) and no matter what I try I can't 
reproduce this problem.

(Use the -a and -p options)

/** @constructor */
function A(){
    /** an inner variable */
    var b = function(){}
}

When A is marked as a constructor, then b is listed as an "inner method" of A. 
If you don't mark A as a 
constructor, then b isn't listed in the documentation at all.

There isn't any way I can get b to be documented as a global. Can you provide 
any more information? Exactly 
what version of JsDoc Toolkit are you using? What are the exact command line 
options you are using? Can you 
attach the exact source file you are documenting?

Original comment by micmath on 25 May 2008 at 7:55

• Changed state: MoreInfoRequired

[GoogleCodeExporter]

[deleted comment]

[GoogleCodeExporter]

hi,  micmath,

Sorry for missing details. I attach a zip file include the js file and 
generated documentation, please download 
and see it. And the command line I use is 

alias jsdoc='java -jar /Applications/jsdoc-toolkit/jsrun.jar 
/Applications/jsdoc-toolkit/app/run.js -
t=/Applications/jsdoc-toolkit/templates/jsdoc 
-d=/Volumes/Users/realazy/Sites/jsdoc -a'

p.s. when I use this form

function a(){
  var b = function(){}
}

there is no problem, but this form will:

function a(){
  var a,
         b = function(){}
}

and this is a valid javascript syntax.

regards

realazy

Original comment by XianAn.C...@gmail.com on 26 May 2008 at 2:13

Attachments:

• testsuite.zip

[GoogleCodeExporter]

function a(){
  var a,
         b = function(){}
}

Yes, it is valid JavaScript but is not supported by JsDoc Toolkit's automatic 
name parser. If you wish to use 
that JavaScript syntax you will have to provide the name yourself, like so:

/** @constructor */
function A(){
    var a,
    /** @name A-b */
    b = function(){}
}

Or, if you prefer you can tag it like so:

/** @constructor */
function A(){
    var a,
    /**
        @inner
        @memberOf A#
     */
    b = function(){}
}

If you wish to simply have the JsDoc Toolkit parser ignore the block of inner 
variables you can use this tag:

/** @constructor */
function A(){
    /**#@+ @ignore */
    var a,
    b = function(){}
    /**#@-*/
}

Original comment by micmath on 26 May 2008 at 10:49

[GoogleCodeExporter]

Original comment by micmath on 26 May 2008 at 10:50

• Changed state: Invalid

[GoogleCodeExporter]

Thanks micmath, though. It's a feature but not a bug, right? But I still expect 
the parser can solve this small 
issue then I can saving a lot of typing. :)

Original comment by XianAn.C...@gmail.com on 29 May 2008 at 10:09

[GoogleCodeExporter]

I never said it was a "feature." In fact the current behavior is probably a 
"bug,"
which can be avoided by using the technique I illustrated. What you now present 
is a
feature request so that you don't have to use that technique. However such a 
feature
would be, in my opinion, difficult to implement.

I freely admit there are many "valid JavaScript" patterns that the JsDoc parser
doesn't recognize. It is true however that there have been lots of improvements 
in
this area over the original JSDoc.pm application, but we all might as well know 
it
will never be 100% perfect. For example here are a few more perfectly valid 
patterns
that are not recognized by JsDoc:

var A = B = function(){};
var C = (B || []);
var D = (C == 1)? null : A;
// obviously A, B, C and D refer to a function

My answer will always be: I know it isn't perfect but you never have to use the 
code
parser in JsDoc Toolkit version 2. I know of at least one very large project 
that
always uses the -n option and completely ignores all the code -- all of their
documentation comes purely from the doc comments. True, it's more verbose but
probably less verbose than the equivalent NaturalDocs or POD would be.

All that said, there's a good reason this project is open source; this is a 
perfect
example of where a user such as yourself can implement a wanted feature 
themselves
and give something back to the rest of the community for all the free software 
we've
provided.

If your suspicion is true, and it is a "small issue," I look forward to your 
patch
submission.

Original comment by micmath on 29 May 2008 at 1:05

[GoogleCodeExporter]

If some of my words had offended you, I just say sorry here, micmath. In fact, 
what I say about "small issue", I 
mean that it is the documentation's issue itself, not jsdoc-toolkit. 

jsdoc-toolkit is very powerful tool, and it make my life easier, I think 
everybody in the community, including 
me, all very thanks to your effort, right, all we know programming/developing 
tools such as jsdoc-toolkit is 
hard and time cost.

And what the shame is my programming level, currently I can not submit any 
patch or improvement to jsdoc-
toolkit, I can only do some javascript programming, but I am make great efforts 
to learn some other 
programming language, hope some day I can devote something useful to the 
community. 

Believe me, I report bug just because I hope jsdoc-toolkit can grow better and 
better, and any other purpose, because I have tied to it.

Original comment by XianAn.C...@gmail.com on 30 May 2008 at 2:39