Conform doc comments to TSDoc spec (experiment)

.eslintrc.json

@@ -11,7 +11,7 @@
         "es6": true
     },
     "plugins": [
-        "@typescript-eslint", "jsdoc", "no-null", "import", "eslint-plugin-local"
+        "@typescript-eslint", "jsdoc", "no-null", "import", "eslint-plugin-local", "eslint-plugin-tsdoc"
     ],
     "overrides": [
         // By default, the ESLint CLI only looks at .js files. But, it will also look at
@@ -22,7 +22,13 @@
         //
         // ESLint in VS Code will lint any opened file (so long as it's not eslintignore'd), so
         // that will work regardless of the below.
-        { "files": ["*.ts", "*.mts", "*.cts", "*.mjs", "*.cjs"] }
+        { "files": ["*.ts", "*.mts", "*.cts", "*.mjs", "*.cjs"] },
+        {
+            "files": ["*.js", "*.mjs", "*.cjs"],
+            "rules": {
+                "tsdoc/syntax": "off"
+            }
+        }
     ],
     "rules": {
         "@typescript-eslint/adjacent-overload-signatures": "error",
@@ -104,6 +110,9 @@
 
         // eslint-plugin-jsdoc
         "jsdoc/check-alignment": "error",
+
+        // eslint-plugin-tsdoc
+        "tsdoc/syntax": "error",
 
         // eslint
         "constructor-super": "error",

package.json

@@ -74,6 +74,7 @@
         "eslint-plugin-jsdoc": "^39.3.6",
         "eslint-plugin-local": "^1.0.0",
         "eslint-plugin-no-null": "^1.0.2",
+        "eslint-plugin-tsdoc": "^0.2.16",
         "fancy-log": "latest",
         "fs-extra": "^9.1.0",
         "glob": "latest",

scripts/buildProtocol.ts

@@ -124,7 +124,7 @@ function writeProtocolFile(outputFile: string, protocolTs: string, typeScriptSer
 
     /**
      * 1st pass - generate a program from protocol.ts and typescriptservices.d.ts and emit core version of protocol.d.ts with all internal members stripped
-     * @return text of protocol.d.t.s
+     * @returns text of protocol.d.t.s
      */
     function getInitialDtsFileForProtocol() {
         const program = ts.createProgram([protocolTs, typeScriptServicesDts, path.join(typeScriptServicesDts, "../lib.es5.d.ts")], options);

src/compiler/binder.ts

@@ -2996,7 +2996,7 @@ namespace ts {
             }
         }
 
-        /** For `x.prototype = { p, ... }`, declare members p,... if `x` is function/class/{}, or not declared. */
+        /** For `x.prototype = { p, ... }`, declare members p,... if `x` is function/class/`{}`, or not declared. */
         function bindPrototypeAssignment(node: BindableStaticPropertyAssignmentExpression) {
             setParent(node.left, node);
             setParent(node.right, node);
@@ -3067,8 +3067,8 @@ namespace ts {
         }
 
         /**
-         * For nodes like `x.y = z`, declare a member 'y' on 'x' if x is a function (or IIFE) or class or {}, or not declared.
-         * Also works for expression statements preceded by JSDoc, like / ** @type number * / x.y;
+         * For nodes like `x.y = z`, declare a member 'y' on 'x' if x is a function (or IIFE) or class or `{}`, or not declared.
+         * Also works for expression statements preceded by JSDoc, like `/ ** @type number * / x.y`;
          */
         function bindStaticPropertyAssignment(node: BindableStaticNameExpression) {
             Debug.assert(!isIdentifier(node));

src/compiler/builder.ts

@@ -973,7 +973,7 @@ namespace ts {
         }
 
         /**
-         * @param optionKey key of CommandLineOption to use to determine if the option should be serialized in tsbuildinfo
+         * @param optionKey - key of CommandLineOption to use to determine if the option should be serialized in tsbuildinfo
          */
         function convertToProgramBuildInfoCompilerOptions(options: CompilerOptions, optionKey: "affectsBundleEmitBuildInfo" | "affectsMultiFileEmitBuildInfo") {
             let result: CompilerOptions | undefined;