Check JSDoc @param tag names (#18777)

Author: Andy

src/compiler/checker.ts

@@ -19792,6 +19792,15 @@ namespace ts {
             }
         }
 
+        function checkJSDocParameterTag(node: JSDocParameterTag) {
+            checkSourceElement(node.typeExpression);
+            if (!getParameterSymbolFromJSDoc(node)) {
+                error(node.name,
+                    Diagnostics.JSDoc_param_tag_has_name_0_but_there_is_no_parameter_with_that_name,
+                    unescapeLeadingUnderscores((node.name.kind === SyntaxKind.QualifiedName ? node.name.right : node.name).escapedText));
+            }
+        }
+
         function checkJSDocAugmentsTag(node: JSDocAugmentsTag): void {
             const cls = getJSDocHost(node);
             if (!isClassDeclaration(cls) && !isClassExpression(cls)) {
@@ -22523,7 +22532,7 @@ namespace ts {
                 case SyntaxKind.JSDocTypedefTag:
                     return checkJSDocTypedefTag(node as JSDocTypedefTag);
                 case SyntaxKind.JSDocParameterTag:
-                    return checkSourceElement((node as JSDocParameterTag).typeExpression);
+                    return checkJSDocParameterTag(node as JSDocParameterTag);
                 case SyntaxKind.JSDocFunctionType:
                     checkSignatureDeclaration(node as JSDocFunctionType);
                     // falls through

src/compiler/diagnosticMessages.json

@@ -3519,6 +3519,10 @@
         "category": "Error",
         "code": 8023
     },
+    "JSDoc '@param' tag has name '{0}', but there is no parameter with that name.": {
+        "category": "Error",
+        "code": 8024
+    },
     "Only identifiers/qualified-names with optional type arguments are currently supported in a class 'extends' clause.": {
         "category": "Error",
         "code": 9002

tests/baselines/reference/jsdocParamTagInvalid.errors.txt

@@ -0,0 +1,9 @@
+/a.js(1,21): error TS8024: JSDoc '@param' tag has name 'colour', but there is no parameter with that name.
+
+
+==== /a.js (1 errors) ====
+    /** @param {string} colour */
+                        ~~~~~~
+!!! error TS8024: JSDoc '@param' tag has name 'colour', but there is no parameter with that name.
+    function f(color) {}
+    

tests/baselines/reference/jsdocParamTagInvalid.symbols

@@ -0,0 +1,6 @@
+=== /a.js ===
+/** @param {string} colour */
+function f(color) {}
+>f : Symbol(f, Decl(a.js, 0, 0))
+>color : Symbol(color, Decl(a.js, 1, 11))
+

tests/baselines/reference/jsdocParamTagInvalid.types

@@ -0,0 +1,6 @@
+=== /a.js ===
+/** @param {string} colour */
+function f(color) {}
+>f : (color: any) => void
+>color : any
+

tests/baselines/reference/jsdocParamTagTypeLiteral.errors.txt

@@ -0,0 +1,78 @@
+tests/cases/conformance/jsdoc/0.js(3,20): error TS8024: JSDoc '@param' tag has name 'unrelated', but there is no parameter with that name.
+
+
+==== tests/cases/conformance/jsdoc/0.js (1 errors) ====
+    /**
+     * @param {Object} notSpecial
+     * @param {string} unrelated - not actually related because it's not notSpecial.unrelated
+                       ~~~~~~~~~
+!!! error TS8024: JSDoc '@param' tag has name 'unrelated', but there is no parameter with that name.
+     */
+    function normal(notSpecial) {
+        notSpecial; // should just be 'any'
+    }
+    normal(12);
+    
+    /**
+     * @param {Object} opts1 doc1
+     * @param {string} opts1.x doc2
+     * @param {string=} opts1.y doc3
+     * @param {string} [opts1.z] doc4
+     * @param {string} [opts1.w="hi"] doc5
+     */
+    function foo1(opts1) {
+        opts1.x;
+    }
+    
+    foo1({x: 'abc'});
+    
+    /**
+     * @param {Object[]} opts2
+     * @param {string} opts2[].anotherX
+     * @param {string=} opts2[].anotherY
+     */
+    function foo2(/** @param opts2 bad idea theatre! */opts2) {
+        opts2[0].anotherX;
+    }
+    
+    foo2([{anotherX: "world"}]);
+    
+    /**
+     * @param {object} opts3
+     * @param {string} opts3.x
+     */
+    function foo3(opts3) {
+        opts3.x;
+    }
+    foo3({x: 'abc'});
+    
+    /**
+     * @param {object[]} opts4
+     * @param {string} opts4[].x
+     * @param {string=} opts4[].y
+     * @param {string} [opts4[].z]
+     * @param {string} [opts4[].w="hi"]
+     */
+    function foo4(opts4) {
+        opts4[0].x;
+    }
+    
+    foo4([{ x: 'hi' }]);
+    
+    /**
+     * @param {object[]} opts5 - Let's test out some multiple nesting levels
+     * @param {string} opts5[].help - (This one is just normal)
+     * @param {object} opts5[].what - Look at us go! Here's the first nest!
+     * @param {string} opts5[].what.a - (Another normal one)
+     * @param {Object[]} opts5[].what.bad - Now we're nesting inside a nested type
+     * @param {string} opts5[].what.bad[].idea - I don't think you can get back out of this level...
+     * @param {boolean} opts5[].what.bad[].oh - Oh ... that's how you do it.
+     * @param {number} opts5[].unnest - Here we are almost all the way back at the beginning.
+     */
+    function foo5(opts5) {
+        opts5[0].what.bad[0].idea;
+        opts5[0].unnest;
+    }
+    
+    foo5([{ help: "help", what: { a: 'a', bad: [{ idea: 'idea', oh: false }] }, unnest: 1 }]);
+    

tests/cases/compiler/jsdocParamTagInvalid.ts

@@ -0,0 +1,7 @@
+// @allowJs: true
+// @checkJs: true
+// @noEmit: true
+
+// @Filename: /a.js
+/** @param {string} colour */
+function f(color) {}