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.