Add documentation requirements for @template descriptions, similar to @param

[spaceribs]

Motivation

To better support and require generic type descriptions via @template

Current behavior

No rules require @template to be defined, or require a description if it is defined.

Desired behavior

The following rules are created/added:

"jsdoc/require-template"
"jsdoc/require-template-description"
"jsdoc/require-template-name"

This rule should detect if a generic is added to a function, class, type alias or interface and perform
the same functionality as jsdoc/require-param

Alternatives considered

None, could not find this functionality, only similar patterns

[brettz9]

You can get the require-template-name behavior with the jsdoc/match-name rule as follows:

        {
          match: [
            {
              disallowName: '/^$/',
              tags: [
                'template',
              ],
            },
          ],
        },

For require-template-description, see match-description with the tags option.

For require-template, I am having trouble seeing why you would want to add it to every function, etc.

You could use jsdoc/no-restricted-syntax though it wouldn't auto-add a missing @template (it would just report that one was missing); you'd need to add further to the context as desired:

        {
          contexts: [
            {
              comment: 'JsdocBlock:not(*:has(JsdocTag[tag=template]))',
              context: 'ArrowFunctionExpression,FunctionDeclaration,FunctionExpression,TSDeclareFunction',
              message: '@template required on each block',
            },
          ],
        },

[spaceribs]

that certainly works in the meantime, but I'd assume type parameters are just as important to document as parameters? why wouldn't we want to make it a more straightforward process for requiring an explanation as to what is expected to be passed in?

[brettz9]

Can you give me a precise example of code where you'd like to see @template required?

[spaceribs]

@brettz9 sure, here's an example I'm working with:

/**
 * A tuple of the coordinates and the value at the coordinate.
 */
export type Pairs<D, V> = [D, V | undefined];

/**
 * For a particular axis, a tuple representing the element before
 * and after
 */
export type BeforeAfter<D, V> = [Pairs<D, V>, Pairs<D, V>];

[brettz9]

Ok, I see, so you are using TypeScript syntax rather than using JavaScript with a TypeScript flavor and you want to enforce @template only when generics are used in the signature.

So I see a need for require-template as a rule, though I think require-template-name and require-template-description can be met by match-name and match-description rather than proliferating the rules here.

We might be able to add our nameRequired internal metadata to the @template tag, however, causing our valid-types rule to report any missing names for @template since I expect we can effectively require it with this tag.

[spaceribs]

makes sense, I requested the others because it seems to match the established pattern, no problems nixing that.