dx-spec

dx-spec copied to clipboard

Another thing that JSDoc unfortunately leaves undocumented: how many times can you use a tag? If you use a tag more than once, which value wins?

Taking a cue from the tags to use list #17:

Use once only

• author: for multiple authors, use a nested list.
• deprecated
• since
• copyright
• ignore
• license
• readonly
• version

Multi-use allowed

• param
• returns
• throws
• todo
• fires

Rationale: there should be no ambiguity like JSON's unfortunate key order ambiguity, and in cases where you might wonder "Is it copyrighted by X AND Y, or did someone update this and want to change the designation", it should be obvious. Most straightforward cases are version and since: a variable must have been introduced in some specific version - it can't be introduced in multiple versions.

I agree, although I wonder how many of these we actually need. We can likely document param, throws, and returns inline. I'm honestly not sure if there should be a "fires" since there's no standard event emitter in every environment