feat(check-values): @throws must not be empty

[sbusch]

@throws requires a value, see https://jsdoc.app/tags-throws.html

For example, https://github.com/autoNumeric/autoNumeric/blob/next/src/AutoNumeric.js is incorrectly declaring
@throws without values.

[brettz9]

Please see my comment at #480 (comment)

And I just noticed your comment there about this. :)

[sbusch]

Originally posted by @brettz9 in #480 (comment)

Btw, FWIW, I noticed your branch on @throws. That sounds like a good idea, but I recommend adding instead as an option to valid-types similar to checkSeesForNamepaths (but instead of checking for namepaths, it would be checking types; and actually, come to think of it, I think it should accept an array instead so users could require types on other tags where it is normally optional, e.g., typedef). (It should be optional though as it technically can be a free-form description.)

[sbusch]

I don't understand what you're meaning with "checking types" and "require types on other tags"?

(For now) I just want to check for empty values (instead of doing a full validation of @throws values), because JSDoc shows the following error with empty @throws tags:

ERROR: The @throws tag requires a value. File: AutoNumeric.js, line: 59

[brettz9]

By "checking types", in the context of eslint-plugin-jsdoc it means checking the curly brackets portion of a tag, e.g., SomeException inside @throws {SomeException} whereas namepaths are typically expected after any type, e.g., someNamepath in @typdef {SomeType} someNamepath or @typedef someNamepath.

So rather than modifying the check-values rule, I suggest modifying the valid-types rule. (Though that rule is called "valid-types", the rule also checks some namepaths like ensuring that @callback has no type in brackets but has a namepath after it, e.g., @callback MyCallback.)

But check-values is more meant for other types of values which are not types or namepaths (and which are not free text descriptions--we have match-description and such for that), such as versions, license identifiers, etc.

As far as "require types on other tags", I mean being able to add a feature like this:

'jsdoc/valid-types': ['error', {tagsWithRequiredType: [
    'throws', 'typedef'
]}]

This would then report cases where there was an empty@throws or @typdef or if it only had a namepath, e.g., @typedef SomeNamepath.

(Ideally, there'd be a tagsWithRequiredNamepath as well so one could avoid @augments {SomeNamepath} passing and insisting on using the jsdoc way which doesn't use curly brackets.)

[brettz9]

And if you were curious, the reason we don't require all tags that accept types/namepaths to automatically have them is because of such as these reasons:

1. The tag explicitly allows different formats (e.g., @see can be a namepath or free text)
2. Closure uses a different approach (e.g., while jsdoc @augments uses no curly brackets, its alias, @extends when used in Closure does expect curly backets)
3. It is not clear in the official jsdoc docs (because of a missing signature, a signature contradicting the examples, etc.) whether the tag requires the type/namepath or not.

[brettz9]

My latest thinking is for valid-types to remove checkSeesForNamepaths and instead accept an option like this:

{
  tags: {
      // Replacement for `checkSeesForNamepaths: true`
      see: {
        // Name position expects a namepath if present (not just plain text)
        name: 'namepath',
        // Indicates that a name position is required (not just that if present, it is a namepath); can also
        //   include "type"; default is an empty array with neither required
        required: ['name'],
        // Explicitly disallows any bracketed type; default is `true` (to allow valid types within
        //   brackets). Note: `type` does not accept "text" as a value (as `name` does) since
        //   bracketed types are not free form in jsdoc whereas the name position can
        //   sometimes be free form (when not a namepath)
        type: false
      }, 
      // The following should probably be applied by default if jsdoc expects at least something for `@throws`
      throws: {
         // If `name` is set to `type`, can be plain text in name position, e.g., `@throws This is an error`; i.e.,
         //   not needing to be a "namepath"; the default
        name: 'text',
        // Must have either type (e.g., `@throws {aType}`) or name (`@throws Some text`); this option is
        //   necessary as distinct from `name` and `type` since it indicates that one or the other is required
        required: ['typeOrName']
      }
    }
}

Besides allowing projects to enforce having some type or name in @throws (and the preexisting checkSeesForNamepaths behavior), it should also allow them to insist on (or prevent) a type being used (rather than allowing free-form text as the spec allows).

@golopot: Are you ok with this API?

[brettz9]

Am now thinking this should be as settings since we have check-types and no-undefined-types (as well as valid-types) which do some checking of types/namepath structure...

[gajus]

🎉 This issue has been resolved in version 30.0.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀