search

AaronNGray / jsdoc-toolkit

Automatically exported from code.google.com/p/jsdoc-toolkit
0 stars 0 forks source link

Parsing problem when strong typing is used #253

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
What steps will reproduce the problem?
Use strong typing
(http://wiki.ecmascript.org/doku.php?id=proposals:bound_this) in your JS
code, i.e.

function test(a : Number, b : String) : Number{
    return b + (a*2);
}

What is the expected output? What do you see instead?
JsDoc will now generate the following parameter list:
a
Number
b
String

...thus the types are interpreted as parameter names.

What version of the product are you using? On what operating system?
JSDoc 2.3.2 on Win Vista

Please provide any additional information below.
I patched JSDOC.Walker.onParamList to:

        else if (paramTokens[i].is("NAME") && !( i > 0 &&
paramTokens[i-1].is("PUNC") && paramTokens[i-1].name === "COLON")) {

which works for us, but I don't think that this is a great solution.

Original issue reported on code.google.com by Danny.G...@gmail.com on 16 Sep 2009 at 8:06

GoogleCodeExporter commented 9 years ago 
Actually it would be great if the type could be automatically used as implicit
parameter (or return) type. Maybe the parser should add it to the NAME-token?

Original comment by Danny.G...@gmail.com on 16 Sep 2009 at 8:28

GoogleCodeExporter commented 9 years ago 
That's cool that you can patch things to do what you want but I have no will to 
support this before version 3 is 
released. You can still use JsDoc Toolkit with any version of JavaScript by 
adding the -n option to turn code 
parsing off, then add explicit tags for @name and @param in all doc comments.

Original comment by micmath on 16 Sep 2009 at 5:58

GoogleCodeExporter commented 9 years ago 
> That's cool that you can patch things
Absolutely, the beauty of open source. :)

Not sure if I understand this correctly, though. I can certainly use @name and 
@param
in all script files together with -n, but the downside of this approach is that
undocumented functions are not part of the docs at all (so this is not really a 
good
option). It is fine if you decide not to support ECMAScript as this is your 
project.
I would also like to do some research/development into this direction and 
contribute,
but it would be great to get some guidance how this would fit best into the 
existing
framework.

One issue is making the parser stable enough to ignore the colons, I can't 
think of
any reason why this should not be part of JsDoc Toolkit as it doesn't break 
anything.
A second step would be using the typing information for the documentation which 
could
reduce the documenting effort as the code already defines the types and there 
is no
need to duplicate this into the documentation. As the latter is a little 
*magic*, I'd
understand if that should not be part of the Toolkit.

It would be great if you could shed some light on why this should not be part of
JsDoc tollkit (effort/time, architectural concerns, anything else).

Original comment by Danny.G...@gmail.com on 17 Sep 2009 at 12:39

GoogleCodeExporter commented 9 years ago 
I did not say I would not support ECMAScript, only that I have no will to 
support this feature before version 3 is released.

As for your remark, "I can't think of any reason why this should not be part of 
JsDoc Toolkit as it doesn't break anything," 
allow me to explain my point of view on this issue (it is already explained 
elsewhere on the mailing list, but I will repeat it 
here all in one place for clarity):

The code parsing aspect of JsDoc Toolkit involves static analysis of a dynamic 
language. This is a very hard thing to do, and 
is always guaranteed to be wrong some of the time. It would take anyone about 
10 seconds to think of 10 different ways to 
break the parsing technique I use if they were trying. In spite of this 
fragility I estimate that at least 70% of the code, and 
90% of my time/effort on this project is spent on trying to keep the static 
analysis (partially) working enough to be useful. 
But actually it's never enough because someone is always going to come up with 
a new idea for how it needs to be 
corrected or extended. In fact, if you go back far enough on the mailing list, 
you'll see I only added the static analysis under 
protest in the first place.

If I were going to do code parsing properly I wouldn't try to do it with a 
parser written in JavaScript, that would be 
ridiculously slow. I'd write a full-blown JavaScript engine in a faster 
language like compiled C or Java. And actually these 
already exist, they are named SpiderMonkey and Rhino respectively. In fact 
Rhino is distributed with the JsDoc Toolkit 
project. It's been maintained for a very long time by some very talented 
programmers and it would be perfect for the job: it 
can parse JavaScript source code but unfortunately it doesn't give me access to 
that parsed code object afterwords. 
According  to the Rhino mailing list, that ability is coming soon (in Rhino 
1.7R3 perhaps?). At the moment we are still 
waiting.

When that does become available I will have to learn enough Java to try and 
rewrite JsDoc Toolkit to use Rhino's parser and 
then I can get out of the static analysis business for good. That will be in 
JsDoc Toolkit version 3. At that point whatever 
JavaScript syntax Rhino understands, so too will JsDoc Toolkit. I really have 
no interest whatsoever in trying to maintain a 
complete, up-to-date JavaScript parser written in JavaScript, but what limited 
code parsing currently exists should be 
considered a helpful bonus. The plain, basic way of documenting your code is 
with @name and @param, even if it is more 
verbose.

On the other hand, are you aware that JsDoc Toolkit has long supported a sort 
of type-hinting documentation like so:

function getPerson(/**String*/ name) /**Array*/ {
    // takes a String and returns an Array
}

This is documented here: http://code.google.com/p/jsdoc-toolkit/wiki/InlineDocs

And you are welcome to modify the source code of my project according to the 
license as much as you please, but for the 
reasons I explained I don't intend to extend JsDoc Toolkit's static code 
analysis abilities any further until version 3, it's slow 
and fragile enough as it is. If you are interested in contributing then perhaps 
you can find a way to get JsDoc Toolkit to use 
Rhino to do the static code analysis, that really would be something we could 
use going forward and would make my life 
much easier in the process!

Original comment by micmath on 17 Sep 2009 at 8:38

GoogleCodeExporter commented 9 years ago 
I've attached a patch that parses the type information from parameter lists and 
functions (return values) and automatically adds the type to the documentation, 
just in case somebody needs it before version 3 is released.

Original comment by Danny.G...@gmail.com on 15 Oct 2010 at 9:10

Attachments: