Check @param names in JSDoc method documentation

[friflo]

JSDoc applied to methods tend to age. Typically method parameters are added / removed / changed but their documentation remain unchanged.

Typescript compiler should check the @param names and should write an error, if they are not found in the method signature. Maybe this check should be optional, by a compiler flag.

TypeScript Version: (2.0.3)

Code

class TestValidateJSDocParams {
    /** Calculate the sum of the given numbers
     * @param x     first summand
     * @param y     second summand
     * @param z     third summand
     */
    public sum (a: number, b: number) : number {
        return a + b;
    }
}

Expected behavior:
Should log an tsc compiler error for unknown methods parameters: x, y, z

Actual behavior:
Compiles without an error.

[kitsonk]

My personal opinion is that this would be a great linter feature in something like tslint.

[mhegazy]

@kitsonk, while i agree with you in a .ts file, in a .js file we already use the JSDoc comments for type information. the function in the OP, would not be typed correctly as we did not find the documentation for parameter a; so seems like a nice error to show to avoid such situations.

@RyanCavanaugh, we should consider doing this as part of #6802. make JSDoc errors a category by their own. we today swallow all these errors.

[brettz9]

Did #18777 address this? If not, should #15852 subsume this issue?

[sandersn]

@brettz9 #18777 fixes this bug, but only for Javascript, where we use jsdoc for typing. It still feels like a lint feature in Typescript.

[sandersn]

Now that we have info-level diagnostics with codefixes, we could do it that way. Accepting PRs for this one.

This one is a good bit of work, but it's all based on existing code. You'll just have to

1. Give the jsdoc-mismatch error in TS as well, but as an info.
2. Copy the structure of an existing codefix to change the param name.
3. Decide how to fix the error. Do you match by position? By levenshtein distance? Do you default to changing the jsdoc? The parameter? Do you offer to reorder the jsdoc or the parameters?

Make sure the codefix works in JS too!

[Kingwl]

I'd like to have a try on it

[sandersn]

OK, I assigned you to the issue, @Kingwl. Unassign yourself if you decide not to do this.

[Kingwl]

Oh. Sorry. I forget this one.