What's the correct casing to use for jsDoc comments?

Question

I've recently started using jsdoc comments for documenting our javascript code, however I'm finding conflicting examples of the usage of the @param tag.

See https://code.google.com/p/jsdoc-toolkit/wiki/TagParam (PascalCase)

and https://developers.google.com/closure/compiler/docs/js-for-compiler (camel/lowercase).

camelCase makes sense to me since:

var foo = 1;
console.log(typeof foo); // outputs "number"

What's the correct casing to use for jsDoc @param comments? Or does it not matter? I'm planning to use it for document generation as well as running the code through google closure to get type checking.

Thanks!

score 16 · Accepted Answer · answered Mar 20 '13 at 04:29

16

The conflicting examples for JSDoc type expressions involve the JavaScript primitive types string, number and boolean, which have corresponding wrapper types: String, Number, and Boolean.

From Closure: The Definitive Guide:

The use of wrapper types is prohibited in the Closure Library, as some functions may not behave correctly if wrapper types are used where primitive types are expected.

See MDN: Distinction between string primitives and String objects.

answered Mar 20 '13 at 04:29

Christopher Peisert

21,862
3
86
117

4

In most cases, you want the primitive type rather than the Object type. The compiler will automatically box (promote) the primitive type when necessary, but the reverse isn't true. – Chad Killingsworth Mar 20 '13 at 15:03
Thanks cpeisert! I'll definitely have to get that book! – magritte Mar 20 '13 at 19:44
definitely do. It's a great read, not just for it's closure info! – jordancpaul Apr 06 '13 at 09:06
3

What about 'function'? – Nappy Sep 26 '13 at 10:33

What's the correct casing to use for jsDoc comments?

1 Answers1