Feature Request: eslint & eslint-plugin-jsdoc integration

[unicornware]

Description

I'm attempting to integrate this plugin into my workflow, but it doesn't seem the plugin is integrated with eslint-plugin-jsdoc, nor eslint itself.

Specifically, the lack of support for the tagNamePreference setting in eslint-plugin-jsdoc results in faulty errors regarding tags.

I'm not entirely sure, but I also suspect that the lack of integration with eslint (or maybe prettier-vscode?) means the following:

• Issues yielded by this plugin are only displayed by directly running eslint
  • If I open a file with alleged issues, my editor (VSCode) doesn't show any red squigglies where the plugin identified the issues; I have to run eslint to get a full report
• Issues that are auto-fixable are not fixed on save
  • Normally when I save a file that has auto-fixable issues (even if the file doesn't have any changes), those issues are fixed on save. This does not happen with issues yielded by this plugin; I have to run eslint --fix instead

Example

tagNamePreference settings:

{
    jsdoc: {
      tagNamePreference: {
        augments: 'extends',
        constant: 'const',
        fileoverview: 'file',
        returns: 'return'
      }
    }
}

Take the following file:

/**
 * @file Katas - tribonacci
 * @module katas/tribonacci
 */

/**
 * Given a starting sequence, `[a, b, c]`, the function returns an array with
 * the first `n` elements of the sequence.
 *
 * @see https://codewars.com/kata/556deca17c58da83c00002db
 *
 * @example tribonacci([1, 1, 1], 10) => [1, 1, 1, 3, 5, 9, 17, 31, 57, 105]
 * @example tribonacci([0, 0, 1], 10) => [0, 0, 1, 1, 2, 4, 7, 13, 24, 44]
 *
 * @param {[number, number, number]} args - Starting sequence
 * @param {number} n - Total number of elements in sequence
 * @return {number[]} First `n` elements of sequence
 */
const tribonacci = (
  [a, b, c]: [number, number, number],
  n: number
): number[] => {
  // Base case: If n is less than or equal to zero, return empty array
  if (n <= 0) return []

  /** @const {number} sum - Sum of {@link a}, {@link b}, and {@link c} */
  const sum: number = a + b + c

  // Generate and return sequence
  return [a, ...tribonacci([b, c, sum], n - 1)]
}

export default tribonacci

After running eslint ./src/katas/tribonacci.ts --exit-on-fatal-error --report-unused-disable-directives --fix:

/Users/lex/Projects/UNICORNWARE/katas/src/katas/tribonacci.ts
  17:11  error  Insert `s`                                                                       prettier/prettier
  26:12  error  Insert `tan`                                                                     prettier/prettier

✖ 8 problems (8 errors, 0 warnings)
  8 errors and 0 warnings potentially fixable with the `--fix` option.

• 17:11: the plugin wants me to use @returns => my settings dictate using @return
• 26:12: the plugin wants me to use @constant => my settings dictate using @const

[hosseinmd]

My suggestion is, don't use eslint-plugin-jsdoc and prettier-plugin-jsdoc both.

[unicornware]

@hosseinmd

given #161, i’ve already opted for removing prettier-plugin-jsdoc. that’s not really a solution in my book, however, nor is it even a solution at all for folks already not using eslint-plugin-jsdoc.

if you take a look at the jsdoc website, you'll see that some block tags have synonyms.

• @return is a synonym for @returns, as is @const for @constant

the tagNamePreference setting is support for synonyms. so for devs using synonyms, but not eslint-plugin-jsdoc, they too will encounter faulty errors because prettier-plugin-jsdoc does not have the same support. simply banning synonym usage would not be a viable solution either.

[hosseinmd]

This is our synonyms https://github.com/hosseinmd/prettier-plugin-jsdoc/blob/4c0b2f6fead8911f0f316361af426087d346ea66/src/roles.ts#L48

[unicornware]

@hosseinmd

if synonyms are truly supported, it doesn't make sense to me why this plugin doesn't work with eslint-plugin-jsdoc, which makes this seem like more of a bug.

how does this library determine a tag is valid? are the keys of TAGS_SYNONYMS included in that validation?

if i'm interpreting your comment correctly, i don't think the keys are being included as valid tags.

One TAG TYPE can have different titles called SYNONYMS. We want to avoid different titles in the same tag so here is map with...[what] we want to have in final jsDoc.

it's one thing to enforce consistency (using the original tag or the synonym, but not both), but it seems to me that the library is purposely excluding synonyms from being used at all. it's attempting to force the use of the original tag with zero regard for what's in my codebase (i use @const and @return consistently). my suggestion would be to implement an option similar to tagNamePreference, or at least something where the map is somehow user-provided. this way, consistency (if that is the intention) is dictated by the user.

[hosseinmd]

The main aim of synonyms is creating a standard for tags name, I don't want to create option for this, you should move to this standard because of consistency between packages. Maybe these synonyms don't have a reason, but used in many packages, we want to have a consistency between packages.

[hosseinmd]

If you think these synonyms isn't good, I agree with you, give us your suggestion we could fix it if others accept.

[turadg]

we want to have a consistency between packages

Please don't make that a goal of this project. Its main value is consistency within a codebase and making it inflexible makes it harder to adopt into codebases. The default settings suffice to nudge people towards your chosen norms.

[hosseinmd]

Please don't make that a goal of this project. Its main value is consistency within a codebase and making it inflexible makes it harder to adopt into codebases. The default settings suffice to nudge people towards your chosen norms.

Yes you are totaly right. but implemention is hard, some logic was hard code,