JSDoc/GCC/TypeScript mode

[brettz9]

#354 proposes adding a mode setting for allowing different behavior between TypeScript, Closure, and regular jsdoc. This setting could be used for other tweaks:

• Avoid parseClosureTemplateTag in no-undefined-types except for closure
• Toggle check-syntax behavior (report non-GCC when in closure mode)
• Start checking module for namepaths (see "todo" in jsdocUtils.js source), but only for "jsdoc" (and "closure"?) mode (TS doesn't support)
• valid-types
  • valid-types - Ensure tags with optional type (tagsWithOptionalTypePosition) only allow for package, private, protected, public, and static if in closure mode.
  • valid-types - Only allow @extends {SomeType} with brackets if in closure mode.
  • valid-types - Only allow @typedef {SomeType} (without a name) in closure mode.
  • Report name on @interface in Closure
• Don't check optional name on @interface in Closure
• For check-tag-names, avoid allowing @template except in closure and typescript
• For check-tag-names, add other GCC tags for closure mode (GCC specific tags support #306)
• check-tag-names to prefer other defaults with tagNamePreference (return over returns)
• See about getting jsdoctypeparser (e.g., see Typescript types should parse correctly jsdoctypeparser/jsdoctypeparser#50 on TypeScript support) to support different modes so long as jsdoc/TypeScript/Closure differ in the formats supported (might have comments which are used to build alternate versions of the peg file, e.g., stripping out those for TypeScript or Closure only). One explicitly desired rule to be avoided for closure per Disallow {[string]} array notation #495 is to disallow tuples. Might also have a tolerant version (the default?) which accepted all forms though (?).

Might accept a version in an array along with the mode string in case jsdoc, Closure, or TypeScript make breaking changes or add more features.

[l1bbcsg]

check-syntax is another important rule to tweak. Currently it tweaks agains GCC style, but in gcc mode it could have the opposite behavior.

check-types rule, preferredTypes and tagNamePreference settings could use different defaults in GCC mode, i.e. prefer return over returns.

[brettz9]

Thanks, @l1bbcsg , I've amended the original post to include check-syntax, but I mentioned check-tag-names instead of check-types in relation to tagNamePreference; do you have an example of a type that differs from gcc if check-types also should toggle behavior?

[l1bbcsg]

One case I can think of is that Function and function both could be used in GCC code and have different meaning.

Technically, Boolean and boolean are also different types, but I can't think of any real-world scenario where you could find a difference.

You can look into GCC types in details here: Types in the Closure Type System

[brettz9]

Both Function and function could be used in regular jsdoc as well, though in regular jsdoc, there is no function() (with parentheses). The fact that regular jsdoc should not handle function() type syntax is reflected already in the to-do for getting jsdoctypeparser to support different modes and setting such a mode.

Re: real world differences between Boolean and boolean, typeof treats them differently: typeof new Boolean(true) === 'object' vs. typeof true === 'boolean'. The rule check-types prefers boolean since use of Object-wrapped primitives is generally frowned upon. I don't see that this should differ between regular jsdoc and GCC.

[ExE-Boss]

Actually, @template is valid when in TypeScript mode.

[brettz9]

Ah, good catch, thanks @ExE-Boss ! Amended...