Javascript: Use a loose set of rules for consistent JSDoc comments

[kripod]

While using JSDoc should not be mandatory, I think that its users should aim for more consistency, which may be achieved by the following set of loose ESLint rules:

"valid-jsdoc": ["error", {
  "prefer": {
    "arg": "param",
    "argument": "param",
    "class": "constructor",
    "return": "returns",
    "virtual": "abstract"
  },
  "preferType": {
    "Boolean": "boolean",
    "Number": "number",
    "object": "Object",
    "String": "string"
  },
  "requireReturn": false
}]

[ljharb]

Airbnb does not use JSDoc, and although we haven't officially strictly banned it, that's possible in the future. We could certainly set up all those rules but leave the rule disabled, but I'm not sure what value that adds.

[kripod]

For people who don't use JSDoc, the given set of rules does nothing. Those rules only get applied for lines of JSDoc already (being) written.

[ljharb]

Comments starting with "/**" may not be JSDoc, but this rule would warn on them.

[ljharb]

Separately, enabling any kind of useful linting rules for JSDoc might give the false impression that using JSDoc at all is a good idea - which it's not.

[bryankennedy]

@ljharb Could you expand your thoughts, or point me to some reading behind your (Airbnb's) dislike of JSDoc? Seen this referenced in a couple issues, and I'm just trying to understand.

Edit - Nevermind, sorry...saw that you did just what I was asking about here.

[ljharb]

@bryankennedy Sure!

1. code comments should never explain "what", only "why" and history/motivation. Good code is clean and self-documenting.
2. without a tool that prevents it, these sorts of comments rapidly go out of sync with the code, rendering them worse than nothing (misinformation is worse than no information)
3. regarding docs generation, if your API is too complex to hand-write, then it's too complex :-) using tools that make it easier for you to do bad things (making your API overly complex, for example) aren't good tools.

[bryankennedy]

Thanks! I've trying to figure out how to handle multi-line comments consistently. Eslint doesn't have a good way to --fix the good to bad comment examples here.

It can change:

// Multiline comment
// About something

to:

/*
 * Multiline comment
 * About something
 */

but not to:

/**
 * Multiline comment
 * About something
 */

As a result I was trying to understand the motivation for ** if JSDoc itself is frowned on. I'm probably mixing commenting philosophy and visual appearance concerns here.

[ljharb]

Using ** in comments is fine if you like :-) that’s not the issue with JSDoc. Perhaps you could ask eslint to add a config option for that?

[moroine]

I get your point, and actually it makes sense.

On our company we use jsdoc to help with the IDE for autocomplete & type checking.