1625549 - Enable ESLint rule valid-jsdoc for all directories used by sphinx-js

Status: NEW

(Developer Infrastructure :: Lint and Formatting, enhancement)

Description

[Michael Cooper [:mythmon]]

When building docs, we specify a subset of directories that are processed by sphinx-js with jsdoc. However, many of the files in these directories contain problems in their documentation comments that prevent jsdoc from working correctly. This makes it harder to write documentation, and makes the output of ./mach doc noisier.

We should enable the ESLint rule valid-jsdoc for all of the directories in that list. It would be great if we could keep that list and the directories where the rule is enabled in sync automatically, but manually would be fine too.

Comment 1

[Mark Banner (:standard8)]

valid-jsdoc is now deprecated, so we should consider switching to something like eslint-plugin-jsdoc, e.g. bug 1510561.

I've actually been thinking about setting up a single set of jsdoc rules and applying that everywhere in the tree where we currently have jsdoc rules. That would help to make things consistent.

If we could get that list of jsdoc into something that we could read from node, then we could import it into the top-level .eslintrc.js just like we do for the ignore list.