jsdoc-informative-docs generates a report whenever you use @class

[ThosRTanner]

Expected behavior

/** Some Description
 *
 * @class 
 *
 * @param {number} value - Some useful text
 */
function MyAmazingThing(value)
{
    this.thing = value;
}

should not produce a "This description only repeats the name it provides" warning on the @class line. The jsdoc documentation on @class doesn't require anything else on the line, and to be honest, the only description that is applicable to some classes is the short one.

Actual behavior

The @class line generates the above warning.

ESLint Config

---
plugins:
- jsdoc

rules:

  "jsdoc/informative-docs": warn

ESLint sample

See above

Environment

• Node version: v18.16.0

• ESLint version v8.38.0

• eslint-plugin-jsdoc version: 43.0.7

[brettz9]

Since the issue here apparently relates to the algorithm for determining what is "informative", please file your concern with https://github.com/JoshuaKGoldberg/are-docs-informative/issues . I figure the exact decision about what should be allowed may end up being subjective, so my recommendation is to consider whether your recommendation can be phrased as a choice of how to make the behavior more configurable (beyond the configuration that is already offered by the package and our use of it).

If the package ends up allowing more configuration to accommodate differences of opinion about what is informative or not, feel free to submit an issue here so we can pass on that configuration.

Closing as I think that is the approach to take, but feel free to comment further as needed.

[JoshuaKGoldberg]

Hmm, I think this is an issue in eslint-plugin-jsdoc. Right now, informative-docs isn't trimming the text it passes to are-docs-informative. The Boolean(text) check that's supposed to filter out blank text isn't accounting for whitespace. That means when there's a tag like @class, it calls the equivalent of:

areDocsInformative('\n', 'MyAmazingThing')

...which is false.

Sent #1047 to fix.

In the meantime @ThosRTanner, you can work around this issue by not having a blank line after the @class tag.

/** Some Description
 *
 * @class
 * @param {number} value - Some useful text
 */

[github-actions]

🎉 This issue has been resolved in version 43.0.8 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[ThosRTanner]

the fix works. thank you