swallowzhang / jsdoc-toolkit

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

Trying to document function as a member of undocumented symbol #316

Closed GoogleCodeExporter closed 8 years ago

GoogleCodeExporter commented 8 years ago
What steps will reproduce the problem?
1. Download the attached file
2. Run jsdoc-toolkit (I used the options -v -a -p)

What is the expected output? What do you see instead?
Output looks okay, but I do get the following warning:
"Trying to document publicFn as a member of undocumented symbol that."

What version of the product are you using? On what operating system?
jsdoc-toolkit 2.4.0 on Debian 5.0

Please provide any additional information below.
To get rid of another warning I had to add the first comment which "defined" an 
object called "Module". However, there is no such object because of how 
requirejs works. The the whole Module.*-concept is only used to structure the 
modules for the documentation.

But the real issue is that the variable 'that' is defined. Why is jsdoc 
insisting that it doesn't?

Original issue reported on code.google.com by RaphaelP...@gmail.com on 16 Feb 2011 at 9:59

Attachments:

GoogleCodeExporter commented 8 years ago
[deleted comment]
GoogleCodeExporter commented 8 years ago
that' is defined, we all agree about that, however 'that' is undocumented. You 
believe it is documented because you wrote a doclet right next to it, however 
that doclet has a @name tag, so it does not apply to the code next to it. Read 
the docs for the @name tag to learn more about this: "Be warned though, by 
using the @name tag you are telling JsDoc Toolkit to ignore the surrounding 
code and to treat your documentation comment in isolation."

http://code.google.com/p/jsdoc-toolkit/wiki/TagName

To see what I mean, you can move that doclet anywhere in your code and it will 
work the same: it is not associated with 'that'. Therefore, later on, when you 
try to document "that.publicFn" it's warning you that you haven't documented 
"that".

Adding @name Module.Submodule#that.publicFn to the last doclet should do what 
you want.

By the way, I have been working with James Burke (of RequireJS) and will 
provide first-class support for documenting modules in JSDoc 3, which I am 
planning to release in the next month or so.

Original comment by micmath on 16 Feb 2011 at 11:59

GoogleCodeExporter commented 8 years ago
Thank you for your quick answer, it works beautifully.

First-class support for RequireJS is wonderful news indeed. I hope refactoring 
the doclets wont't be too tedious :)

Original comment by RaphaelP...@gmail.com on 16 Feb 2011 at 12:10

GoogleCodeExporter commented 8 years ago
Comment above made almost 4 months ago "I have been working with James Burke 
(of RequireJS) and will provide first-class support for documenting modules in 
JSDoc 3, which I am planning to release in the next month or so."

Any update on that?

Original comment by bkardell@gmail.com on 7 Jul 2011 at 3:00

GoogleCodeExporter commented 8 years ago
You can try out the alpha version here:
https://github.com/micmath/jsdoc

Your feedback is welcome.

Preliminary documentation on this can be found here:
http://usejsdoc.org/howto-commonjs-modules.html

Original comment by micmath on 7 Jul 2011 at 4:05