16

I know there are various flavours of JSDoc around. And it seems that each implementation of a JSDoc parser recognizes its own set of tags. For example, consider the differences in tags between http://usejsdoc.org/ and http://www.techrepublic.com/blog/programming-and-development/create-useful-relevant-javascript-documentation-with-jsdoc/451.

At this point, I am just confused. Is there a canonical implementation of JSDoc or a widely recognized set of core tags? Is there best implementation of JSDoc?

EDIT

As asked in the comment below, the reason for this question is that I need to parse JSDoc comments for use with a tool that we are creating. See this question": Are there any open source JSDoc parser written in Javascript?

I'm concerned that I will have to roll my own parser, and if I do, I need to know which tags need to be supported.

But, on a deeper level, it's concerning to me that that there is no consistent specification (or reference implementation). This makes JSDoc feel a bit ad hoc to me.

Community
  • 1
  • 1
Andrew Eisenberg
  • 28,387
  • 9
  • 92
  • 148
  • It would help to know what is your specific question. Are you switching from one to another doc generation tool? Or is this a hypothetical so you can have the flexibility in the future? Which tags do you want to use that aren't in all implementations? – Ruan Mendes Aug 07 '12 at 18:22
  • I'm afraid JSDoc is not a standard yet. It's kind of like when there was JScript and JavaScript, but no ECMAScript – Ruan Mendes Aug 07 '12 at 19:01
  • Right...but I'm OK if there is not Standard (capital 'S'), but would like to know if there is an unofficial standard (small 's') way of using it and tool that implements it. – Andrew Eisenberg Aug 07 '12 at 19:36

2 Answers2

5

The one I think is the most feature complete is the one used by google closure compiler

One of the cool things about using google closure compiler is that it will do type checking on your functions that have been marked with type information.

I feel your pain, I deal with this all day long. Here's an example of a non-standard feature that I have to code/doc around. Ext-JS uses @cfg to document the properties for the initialization object you pass into a widget. The IDE I use, IntelliJ, uses JSDoc to provide better code suggestions and it even understands Ext's dialect. For most things, it works well. However, many times I have to duplicate the documentation somehow to make both my IDE and the doc tool (Ext's version of jsdoc) understand it, not very DRY. Here's one example: 

...
/** 
 * @cfg {string} title // Ext-JS grabs the type from this line
 * @type string // My IDE grabs the type from this line
 */
 title: null // My IDE requires this line to recognize the cfg
             // as a property of the object even though all cfgs
             // are available in the object
...
Ruan Mendes
  • 90,375
  • 31
  • 153
  • 217
  • In the end, we are using closure compiler syntax. It seems the most complete and well documented of all the flavours of jsdoc that I have found. – Andrew Eisenberg Aug 28 '12 at 03:06
4

I too share your pain. It's annoying that this isn't standardized. While I agree with Mr. Juan Mendes that Closure Compiler's features are the most complete (and probably the most awesome!),

I've always thought of the tag list found here http://code.google.com/p/jsdoc-toolkit/w/list as being the closest thing we have to a real spec. It might be out of date, yet still it might be closer to what many parsers and IDEs implement, moreso than Closure Compiler would be.

See also Wikipedia for the bare minimum of consensus on what tags should be there. http://en.wikipedia.org/wiki/JSDoc

Though if your product supports the Closure Compiler flavour of JSDoc, that will bring it one step closer to becoming the defacto standard. :D

jcairney
  • 2,913
  • 1
  • 16
  • 16