Add ESLint rules to enforce our docs standards

Feature Description

Essentially the same as #924, but for JavaScript.

---

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

There should be ESLint rules to enforce the following:

Semantical

• Every description of everything starts with a capital letter (descriptions, parameter docs, return docs, …).
• Every description of everything ends in a dot (descriptions, parameter docs, return docs, …).
• For functions, the first word of the description must end in an “s” (this is probably 99% reliable, but most importantly should never yield a false positive - I don’t think there are any exceptions to the grammatical rule of 3P verbs ending in an “s”).

Organizational

• Every param and return tag has a type and description.
• Every function doc-block should have a since tag.
• The order of tags (if present, for each) should be since (multiple entries allowed), deprecated, private, param (multiple entries allowed), return.
• For methods and functions, tags should be grouped: since/deprecated/private should be grouped together, separated by a blank line from param/return which should be grouped together.
• All param tag types and descriptions in a single doc-block should be indented in a way that they are aligned with each other.

Implementation Brief

• Build on the work in #722 (PR: #1847) that allows us to write custom ESLint rules
• For requiring param and return types, etc., add to .eslintrc.json:

    "jsdoc/check-types": ["error"],
    "jsdoc/require-param": ["error"],
    "jsdoc/require-param-description": ["error"],
    "jsdoc/require-param-name": ["error"],
    "jsdoc/require-param-type": ["error"],
    "jsdoc/require-returns-check": ["error"],
    "jsdoc/require-returns-description": ["error"],
    "jsdoc/require-returns-type": ["error"],
    "jsdoc/require-returns": ["error"],
    "jsdoc/no-undefined-types": ["error"],
    "jsdoc/valid-types": ["error"],

• Add rules for each of the points above
• Consider using https://github.com/gajus/eslint-plugin-jsdoc for some of the above rules and as inspiration/a utility library for our own JSDoc rules.
• Parse any JSDoc comments with a JSDoc parser and ensure tags like @since exist and match our format

JSDoc blocks can be straightforwardly-extracted using this code in an ESLint rule:

'jsdoc-rule-name': {
    create( context ) {
        const source = context.getSourceCode();
        return {
            '*': ( node ) => {
                const jsDoc = source.getJSDocComment( node );
                if ( ! jsDoc ) {
                    return;
                }

                if ( ! jsDocPassesCheck( jsDoc ) ) {
                    context.report( { node, message: `Missing something in JSDoc.`, data: { name: node.name } } );
                }
            },
        };
    },
}

though there is likely a more efficient selector 😄

Afterward: be sure to fix all errors flagged by ESLint.

Because of the unknowns in managing the parsers and the amount of errors encountered when enabling even the suggested rules from eslint-plugin-jsdoc, this is a reasonably-larged sized issue and is best-handled by someone familiar with ESLint (eg. probably me 😆 ).

QA Brief

• Ensure no ESLint errors are encountered, and create/modify a few JSDoc blocks with JSDoc entries that should cause the above checks to fail and ensure an error is raised when running npm run lint:js.

Changelog entry

• N/A

[felixarntz]

@tofumatt @aaemnnosttv Since this is not critical for plugin usage and therefore shouldn’t block the release, I suggest we create a follow-up issue to fix the above valid points and then consider this one completed.

[aaemnnosttv]

@felixarntz @tofumatt the new issue is here (https://github.com/google/site-kit-wp/issues/2154) and ready for an IB 👍