Use a loose set of rules for consistent JSDoc comments

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]

@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]

@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.