Is there a JSDoc standard?

Question

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.

Answer 1

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

Answer 2

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