Add 'no-redundant-jsdoc' rule (palantir#2754)

src/configs/all.ts

@@ -198,6 +198,7 @@ export const rules = {
  "no-boolean-literal-compare": true,
  "no-consecutive-blank-lines": true,
  "no-parameter-properties": true,
+ "no-redundant-jsdoc": true,
  "no-reference-import": true,
  "no-unnecessary-callback-wrapper": true,
  "no-unnecessary-initializer": true,

src/language/formatter/formatter.ts

@@ -53,8 +53,8 @@ export interface FormatterConstructor {
 export interface IFormatter {
  /**
  * Formats linter results
- * @param {RuleFailure[]} failures Linter failures that were not fixed
- * @param {RuleFailure[]} fixes Fixed linter failures. Available when the `--fix` argument is used on the command line
+ * @param failures Linter failures that were not fixed
+ * @param fixes Fixed linter failures. Available when the `--fix` argument is used on the command line
  */
  format(failures: RuleFailure[], fixes?: RuleFailure[]): string;
 }

src/rules/noRedundantJsdocRule.ts

@@ -0,0 +1,132 @@
+/**
+ * @license
+ * Copyright 2017 Palantir Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { getJsDoc } from "tsutils";
+import * as ts from "typescript";
+
+import * as Lint from "../index";
+
+export class Rule extends Lint.Rules.AbstractRule {
+ /* tslint:disable:object-literal-sort-keys */
+ public static metadata: Lint.IRuleMetadata = {
+ ruleName: "no-redundant-jsdoc",
+ description: "Forbids JSDoc which duplicates TypeScript functionality.",
+ optionsDescription: "Not configurable.",
+ options: null,
+ optionExamples: [true],
+ type: "style",
+ typescriptOnly: true,
+ };
+ /* tslint:enable:object-literal-sort-keys */
+
+ public static FAILURE_STRING_REDUNDANT_TYPE =
+ "Type annotation in JSDoc is redundant in TypeScript code.";
+ public static FAILURE_STRING_REDUNDANT_TAG(tagName: string): string {
+ return `JSDoc tag '@${tagName}' is redundant in TypeScript code.`;
+ }
+ public static FAILURE_STRING_NO_COMMENT(tagName: string): string {
+ return `'@${tagName}' is redundant in TypeScript code if it has no description.`;
+ }
+
+ public apply(sourceFile: ts.SourceFile): Lint.RuleFailure[] {
+ return this.applyWithFunction(sourceFile, walk);
+ }
+}
+
+function walk(ctx: Lint.WalkContext<void>): void {
+ const { sourceFile } = ctx;
+ ts.forEachChild(sourceFile, function cb(node) {
+ for (const { tags } of getJsDoc(node, sourceFile)) {
+ if (tags !== undefined) {
+ for (const tag of tags) {
+ checkTag(tag);
+ }
+ }
+ }
+ ts.forEachChild(node, cb);
+ });
+
+ function checkTag(tag: ts.JSDocTag): void {
+ switch (tag.kind) {
+ case ts.SyntaxKind.JSDocTag:
+ if (redundantTags.has(tag.tagName.text)) {
+ ctx.addFailureAtNode(tag.tagName, Rule.FAILURE_STRING_REDUNDANT_TAG(tag.tagName.text));
+ }
+ break;
+
+ case ts.SyntaxKind.JSDocAugmentsTag:
+ // OK
+ break;
+
+ case ts.SyntaxKind.JSDocTemplateTag:
+ case ts.SyntaxKind.JSDocTypeTag:
+ case ts.SyntaxKind.JSDocTypedefTag:
+ case ts.SyntaxKind.JSDocPropertyTag:
+ // Always redundant
+ ctx.addFailureAtNode(tag.tagName, Rule.FAILURE_STRING_REDUNDANT_TAG(tag.tagName.text));
+ break;
+
+ case ts.SyntaxKind.JSDocReturnTag:
+ case ts.SyntaxKind.JSDocParameterTag: {
+ const { typeExpression, comment } = tag as ts.JSDocReturnTag | ts.JSDocParameterTag;
+ if (typeExpression !== undefined) {
+ ctx.addFailureAtNode(typeExpression, Rule.FAILURE_STRING_REDUNDANT_TYPE);
+ }
+ if (comment === "") {
+ // Redundant if no documentation
+ ctx.addFailureAtNode(tag.tagName, Rule.FAILURE_STRING_NO_COMMENT(tag.tagName.text));
+ }
+ break;
+ }
+
+ default:
+ throw new Error(`Unexpected tag kind: ${ts.SyntaxKind[tag.kind]}`);
+ }
+ }
+}
+
+const redundantTags = new Set([
+ "abstract",
+ "access",
+ "class",
+ "constant",
+ "constructs",
+ "default",
+ "enum",
+ "exports",
+ "function",
+ "global",
+ "implements",
+ "interface",
+ "instance",
+ "member",
+ "memberof",
+ "mixes",
+ "mixin",
+ "module",
+ "name",
+ "namespace",
+ "override",
+ "private",
+ "property",
+ "protected",
+ "public",
+ "readonly",
+ "requires",
+ "static",
+ "this",
+]);

test/rules/no-redundant-jsdoc/test.ts.lint

@@ -0,0 +1,35 @@
+/** @typedef {number} T */
+ ~~~~~~~ [tag % ('typedef')]
+
+/** @function */
+ ~~~~~~~~ [tag % ('function')]
+function f() {}
+
+/** @type number */
+ ~~~~ [tag % ('type')]
+const x = 0;
+
+/**
+ * @param {number} x Is a number
+ ~~~~~~~~ [type]
+ * @param y
+ ~~~~~ [param]
+ * @param {number} z
+ ~~~~~ [param]
+ ~~~~~~~~ [type]
+ * @returns {number}
+ ~~~~~~~ [returns]
+ ~~~~~~~~ [type]
+ */
+declare function g(x: number, y: number, z: number): number;
+
+/**
+ * @param x Useful comment
+ * @returns Useful comment
+ */
+declare function h(x: number): number;
+
+[tag]: JSDoc tag '@%s' is redundant in TypeScript code.
+[type]: Type annotation in JSDoc is redundant in TypeScript code.
+[param]: '@param' is redundant in TypeScript code if it has no description.
+[returns]: '@returns' is redundant in TypeScript code if it has no description.

test/rules/no-redundant-jsdoc/tslint.json

@@ -0,0 +1,5 @@
+{
+ "rules": {
+ "no-redundant-jsdoc": true
+ }
+}

yarn.lock

@@ -1591,8 +1591,8 @@ tsutils@^2.12.1:
  tslib "^1.7.1"
 
 tsutils@^2.8.1:
- version "2.8.1"
- resolved "https://registry.yarnpkg.com/tsutils/-/tsutils-2.8.1.tgz#3771404e7ca9f0bedf5d919a47a4b1890a68efff"
+ version "2.10.0"
+ resolved "https://registry.yarnpkg.com/tsutils/-/tsutils-2.10.0.tgz#ae94511df2656eb06e4424056fba5c388887040c"
  dependencies:
  tslib "^1.7.1"