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

[brettz9]

Oh, and with #586, combined with a PR to jsdoctypeparser to prevent = except in "closure" and "permissive" modes, this rule's currently sole feature might become obsolete, since valid-types could easily be made (with such a change in jsdoctypeparser) to no longer accept the optional = for "jsdoc" and "typescript" modes (the jsdoctypeparser source also mentions other similar optional types as "deprecated").

Update: On second thought, perhaps jsdoctypeparser should not be changed here since "jsdoc" supports closure types such as the optional = suffix, so I guess this is suitable at the eslint-plugin-jsdoc rule level rather than parser level.

[brettz9]

While I've gone ahead and stopped check-types from reporting Closure optional types when in "closure" mode, an option could be added to force it to be allowed. Other mode-specific changes are also welcome as separate issues, but the initial checklist here is now complete, so is being closed.

Note also that not all of TypeScript is yet supported in jsdoctypeparser, but we do have a mode there now (and which we are using in eslint-plugin-jsdoc) to support TS-specific syntax when in TS mode.

[gajus]

🎉 This issue has been resolved in version 28.5.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀