fimbullinter / wotan

Pluggable TypeScript and JavaScript linter
Apache License 2.0
281 stars 23 forks source link

Add rule to disallow useless JSDoc tags in TypeScript files #385

Open ajafff opened 6 years ago

ajafff commented 6 years ago

JSDoc in TypeScript is primarily used for documentation. Type annotations in JSDoc tags are ignored.

/**
 * Description
 * @function
 * @template {object} T Description
 * @param {T} param Description
 * @return {T} Description
 */
function identity<T extends object>(param: T): T {
  return param;
}

TODO: identify more useless tags

This is basically the same as TSLint's no-redundant-jsdoc

ajafff commented 5 years ago

JSDocParameterTag, maybe also JSDocTypeTag and JSDocPropertyTag, where name is a QualifiedName is redundant in typescript:

/**
 * @param {object} param description <-- only type is redundant
 * @param {string} param.prop other description<-- redundant in typescript
 */
function foo(param) {
    param.prop
}
ajafff commented 5 years ago

Another redundant use of JSDoc in TypeScript is the type assertion syntax:

var numberOrString = Math.random() < 0.5 ? "hello" : 100;
var typeAssertedNumber = /** @type {number} */ (numberOrString)

Basically every JSDoc tag in a comment on a ParenthesizedExpression is redundant

ajafff commented 5 years ago

In addition all JSDoc on EndOfFileToken is useless.