chore: Lint TsDoc. (#6353)

* chore: add linting for tsdoc

* chore: don't require types on return

* chore: remove redundant fileoverview from ts

* chore: change return to returns and add some newlines

* chore: remove license tag

* chore: don't require params/return docs

* chore: remove spurious struct tags

* Revert "chore: change return to returns and add some newlines"

This reverts commit d6d8656.

* chore: don't auto-add param names

* chore: disable require-param bc it breaks on this

* return to returns and add line breaks

* chore: configure additional jsdoc rules

* chore: run format

* Revert "chore: remove license tag"

This reverts commit 1734555.

* chore: allow license tag format

* chore: only require jsdoc on exported items

* chore: add missing jsdoc or silence where needed

* chore: run format

* chore: lint fixes

.eslintrc.json

@@ -88,20 +88,27 @@
     "overrides": [{
         "files": ["**/*.ts", "**/*.tsx"],
         "plugins": [
-            "@typescript-eslint/eslint-plugin"
+            "@typescript-eslint/eslint-plugin",
+            "jsdoc"
         ],
+        "settings": {
+            "jsdoc": {
+                "mode": "typescript"
+            }
+        },
         "parser":  "@typescript-eslint/parser",
         "parserOptions": {
             "project": "./tsconfig.json",
             "tsconfigRootDir": ".",
             "ecmaVersion": 2020,
             "sourceType": "module"
         },
-        "extends": ["plugin:@typescript-eslint/recommended"],
+        "extends": [
+            "plugin:@typescript-eslint/recommended",
+            "plugin:jsdoc/recommended"
+        ],
         "rules": {
             // TS rules
-            // Disable JsDoc validation, since we use TsDoc.
-            "valid-jsdoc": ["off"],
             // Blockly uses namespaces to do declaration merging in some cases.
             "@typescript-eslint/no-namespace": ["off"],
             // Use the updated TypeScript-specific rule.
@@ -126,7 +133,34 @@
             // Temporarily disable. 3 problems.
             "@typescript-eslint/no-empty-interface": ["off"],
             // Temporarily disable. 34 problems.
-            "func-call-spacing": ["off"]
+            "func-call-spacing": ["off"],
+
+            // TsDoc rules (using JsDoc plugin)
+            // Disable built-in jsdoc verifier.
+            "valid-jsdoc": ["off"],
+            // Don't require types in params and returns docs.
+            "jsdoc/require-param-type": ["off"],
+            "jsdoc/require-returns-type": ["off"],
+            // params and returns docs are optional.
+            "jsdoc/require-param-description": ["off"],
+            "jsdoc/require-returns": ["off"],
+            // Disable for now (breaks on `this` which is not really a param).
+            "jsdoc/require-param": ["off"],
+            // Don't auto-add missing jsdoc. Only required on exported items.
+            "jsdoc/require-jsdoc": ["warn", {"enableFixer": false, "publicOnly": true}],
+            // Disable because of false alarms with Closure-supported tags.
+            // Re-enable after Closure is removed.
+            "jsdoc/check-tag-names": ["off"],
+            // Re-enable after Closure is removed. There shouldn't even be types in the TsDoc.
+            // These are "types" because of Closure's @suppress {warningName}
+            "jsdoc/no-undefined-types": ["off"],
+            "jsdoc/valid-types": ["off"],
+            // Disabled due to not handling `this`. If re-enabled, checkDestructured option
+            // should be left as false.
+            "jsdoc/check-param-names": ["off", {"checkDestructured": false}],
+            // Allow any text in the license tag. Other checks are not relevant.
+            "jsdoc/check-values": ["off"]
+
         }
     }]
 }