Minimal set of JSdoc

[christophka]

I want to:

• add a new rule
• edit an existing rule

Explanation or benefit

A minimal set of JSdoc code documentation would be nice to be enforced, as this might provide useful information, especially on typescript interfaces that are used to describe React component props.
Currently, according to the official typescript-eslint plugin roadmap the former completed-docs rule will not be replaced, but rather the eslint-plugin-jsdoc should be used.

Tasklist

If it was agreed upon an adoption, please make sure that:

• CHANGELOG was updated
• RULESET was updated

[maschino]

I'm absolutely +1 for this change. I've looked at the eslint-plugin-jsdoc and the only caveat I found is that we can't enforce the existence of a jsdoc comment, only that the style of a jsdoc comment is correct.

In my opinion all public apis should be well documented through jsdoc. That includes classes, functions, react components and typescript interfaces.

One thing to consider: with the switch to typescript and the issues with defaultProps and proper type inference we resorted to "workarounds" like this:

interface IFooDisplayProps {
  optionalProp?: string;
}

const FooDisplay: React.FC<IFooDisplayProps> = ({ optionalProp = 'foobar' }) => {
  ...
}

For an user it's not clear that optionalProp defaults to foobar without looking at the actual implementation. I'd suggest using the @default jsdoc for that but I'm afraid it won't be possible to enforce via eslint.