Rule to disallow inline object types

[cobaltt7]

Motivation

I want to restrict using @type {{ foo: bar}} and instead use @typedef comments with descriptions.

Current behavior

Not implemented AFAIK.

Desired behavior

A new rule. This could also have an option for a minimum amount of properties before it reports an error.

Alternatives considered

This could maybe be part of check-types.

[brettz9]

To prevent use of @type, you can add the following with the jsdoc/check-tag-names rule:

{"settings": {"jsdoc": {"tagNamePreference": {"type": false}}}

[brettz9]

Closing as the supplied suggestion should implement the core desired functionality though feel free to comment further as needed.

[cobaltt7]

I'm sorry for not getting back to you sooner. I think you misunderstood what I wanted.
What I don't want:

/** @type {{ foo: string; bar: number; }} - Description */

(or @param, etc)
What I prefer:

/** @type {FooAndBar} - Description */
/**
  @typedef FooAndBar
  @property {string} Foo - Description
  @property {number} Bar - Description
  */

I still want to allow

/** @type {string} */

[brettz9]

You said you wanted to instead "use @typedef comments with descriptions." yet in your example, @type still can have a description. Was that a mistake? If you do want to prevent descriptions, you can use:

{"settings": {"jsdoc": {"tagNamePreference": {"description": false}}}

I get the idea that you don't want multiple properties and instead really want namepaths only. I think we could technically confine things to namepaths.

However, per the JSDoc docs, it would seem that @type is attached to a particular JavaScript feature and not so much meant as an abstract descriptor, though as with most things JSDoc, I guess it's not spelled out so precisely. But just consider that @typedef is for the definition of a type, so @type should be for an instance of a defined type, something your examples do not suggest. I can see an argument for typecasts using namepaths only, but I don't get the picture that this is what you want.

[cobaltt7]

You said you wanted to instead "use @typedef comments with descriptions." yet in your example, @type still can have a description. Was that a mistake? If you do want to prevent descriptions, you can use:

Sorry, I meant that my reasoning for wanting this was so I could require descriptions on object types.

But just consider that @typedef is for the definition of a type, so @type should be for an instance of a defined type, something your examples do not suggest. I can see an argument for typecasts using namepaths only, but I don't get the picture that this is what you want.

I only use JSDoc for types, and this works fine for me

[brettz9]

Ok, I think a rule which restricts @type to using namepaths, and perhaps optionally allowing for single simple types like "string" might work makes sense. Most people will probably be attaching @type to a language construct and adding the description above @typedef, but such a rule wouldn't have anything to do with enforcing descriptions either way, so it wouldn't matter (and people could enforce their own description policies if they did wish so). No guarantees about getting to implementing the rule, but I think such a rule has a place.

[brettz9]

I realized that you should only need something like the following:

'jsdoc/no-restricted-syntax': ['error', {
  contexts: [
    {
      comment: 'JsdocBlock:has(JsdocTag[tag=type][parsedType.type!=JsdocTypeStringValue][parsedType.type!=JsdocTypeNumber][parsedType.type!=JsdocTypeName])',
      context: 'any',
      message: '@type should be limited to numeric or string literals and names; use a @typedef instead',
    }
  ]
}]

This will allow any kind of name such as MyType or boolean and also literals like "some string value" and 147.

If you wanted to disallow a subset of types which referred to built-in types (and reserve @type only for paths to @typdef), you might add something like the following to the contexts option array to exclude them:

{
  comment: 'JsdocBlock:has(JsdocTag[tag=type][parsedType.type=JsdocTypeName][parsedType.value=/^(true|false|null|undefined|boolean|number|string|object|array|symbol|any|\*)$/])',
  context: 'any',
  message: '@type names should not be built-in types; use a @typedef instead',
}

You can tweak the above as needed, so I think this issue can actually be closed, though feel free to comment further as needed.

(Note that the documentation PR attached to this issue is not the same as your needs as I tried to address just now; the PR is somewhat related, however, so that is why I attached it to the issue.)

[github-actions]

🎉 This issue has been resolved in version 39.7.1 🎉

The release is available on:

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

Your semantic-release bot 📦🚀