`reject-function-type` should not flag `@typedef {Function}`

[TheJaredWilcurt]

This bug is blocking my library's dependency update PR.

Bug

In a recent release reject-function-type was enabled by default in the recommended rules.

Code like this is correctly being flagged:

/**
 * @param {Function} fooBar
 */
function quux (fooBar) {
  fooBar(3);
}

The problem is when you go to correct the issue, by defining the fooBar function in a @typedef, the correction is being flagged too, which would be impossible to resolve (infinite typedefs definitions all the way down).

Solution

1. Do not run this rule against @typedef types.

   -`augments`, `class`, `constant`, `enum`, `implements`, `member`, `module`, `namespace`, `param`, `property`, `returns`, `throws`, `type`, `typedef`, `yields`
   +`augments`, `class`, `constant`, `enum`, `implements`, `member`, `module`, `namespace`, `param`, `property`, `returns`, `throws`, `type`, `yields`

2. Update the documentation to convey how to resolve this issue by writing a valid function type definition and referencing it:

// BAD
// Using the type "Function" does not communicate the
// inputs/outputs of the function.

/**
 * @param {Function} fooBar
 */
function quux (fooBar) {
  fooBar(3);
}

// GOOD
// Create a named definition for the function that includes its params and return.
// Then reference the named definition as the type instead of a generic "Function"

/**
 * @typedef {Function} FOOBAR
 * @param   {number}   baz
 * @return  {number}
 */

/**
 * @param {FOOBAR} fooBar
 */
function quux (fooBar) {
  fooBar(3);
}

This fix allows for the defining of reusable function typedefs that can be referenced by multiple type definitions when the same function shape is used on methods, or imported into different files for reuse.

ESLint Config

Just importing the recommended rules.

Environment

• Node: v24.10.0 (latest)
• npm: v11.6.2 (latest)
• ESLint: v9.37.0 (latest)
• ESLint-Plugin-JSDoc: v61.1.1 (latest)

[brettz9]

Is there a reason you are not using @callback?

[TheJaredWilcurt]

I have not used it in over a decade...... so I forgot it existed 🤔

[TheJaredWilcurt]

Might still be worth updating the docs to show the use of @callback, as the intended solution to this linting violation.

/**
 * @callback          FOOBAR
 * @param    {number} baz
 * @return   {number}
 */

/**
 * @param {FOOBAR} fooBar
 */
function quux (fooBar) {
  fooBar(3);
}

[TheJaredWilcurt]

Created #1569

[github-actions]

🎉 This issue has been resolved in version 61.1.3 🎉

The release is available on:

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

Your semantic-release bot 📦🚀