require-description with descriptionStyle: body produces "Missing JSDoc block description" when @description is used

[joeyparrish]

Expected behavior

When I set the descriptionStyle: 'body' option on jsdoc/require-description, and my code uses @description instead of omitting it, I expect to get a message that indicates I should not use that tag.

Actual behavior

Instead the error says "Missing JSDoc block description", which I find misleading and unhelpful.

ESLint Config

module.exports = {
  extends: ['plugin:jsdoc/recommended'],
  rules: {
    'jsdoc/require-description': ['error', {descriptionStyle: 'body'}],
  },
};

ESLint sample

/** @description Foo! */
function foo() {}

Environment

• Node version: v10.21.0
• ESLint version v7.4.0
• eslint-plugin-jsdoc version: v29.1.3

[joeyparrish]

I think I have a patch that I'm happy with, but I haven't spent the time to figure out the project's tests and update those. Here's what I've done in requireDescription.js:

    if (descriptionStyle === 'body') {
      const descTags = _lodash.default.filter(jsdoc.tags,
          (tag) => tag.tag == 'desc' || tag.tag == 'description');
      if (descTags.length) {
        const tagName = descTags[0].tag;
        report(`Remove the @${tagName} tag from the block description`);
      } else {
        report('Missing JSDoc block description.');
      }
      return;
    }

Whichever of the two description tags you used, it will tell you explicitly to remove it. What do you think?

[brettz9]

This should be helpful, thanks. Hope to take a look in the next day or so.

[brettz9]

Currently, the descriptionStyle option, even when set to the specific "body" or "tag" case, only insists that the desired style is present. It doesn't complain--and your solution doesn't either--about a user having both. For example, this:

/**
 * Block style description
 * @desc And a tag style description
*/

...will satisfy any of the conditions and will not be reported.

So, I think the message should not instruct the user to remove the @desc style (in case they want both for some reason--since the option isn't designed to force only one style, but to merely require one or the other (or either)). But it might be reworded like:

`Remove the @${tagName} tag to leave a plain block description or add additional description text above the @${tagName} line.`

[gajus]

🎉 This issue has been resolved in version 29.2.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[joeyparrish]

Thank you so much for the fix! I appreciate your time and attention.