Finished removing unecessary (placating missing-jsdoc) JSDocs (#562)

* Marked missing-jsdoc as deprecated Continues #400. * Finished removing unecessary (placating missing-jsdoc) JSDocs Fixes #557 * Added recommended_ruleset.js removal * Really disabled missing-jsdoc * Yup, re-ran auto-updating tasks locally * Fixed informativeDocsRule post-merge
microsoft · Oct 23, 2018 · 8d3988a · 8d3988a
1 parent 628d94d
commit 8d3988a
Show file tree

Hide file tree

Showing 166 changed files with 17 additions and 498 deletions.
diff --git a/README.md b/README.md
@@ -72,7 +72,7 @@ Rule Name   | Description | Since
 `insecure-random`               | Do not use insecure sources for random bytes. Use a secure random number generator instead. Bans all uses of Math.random and crypto.pseudoRandomBytes. Better alternatives are crypto.randomBytes and window.crypto.getRandomValues.<br/>References:<br/>* [CWE 330](https://cwe.mitre.org/data/definitions/330.html)<br/>* [MDN Math.random](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random)<br/>* [Node.js crypto.randomBytes()](https://nodejs.org/api/crypto.html#crypto_crypto_randombytes_size_callback)<br/>* [window.crypto.getRandomValues()](https://developer.mozilla.org/en-US/docs/Web/API/window.crypto.getRandomValues)<br/> | 2.0.11
 `jquery-deferred-must-complete` | When a JQuery Deferred instance is created, then either reject() or resolve() must be called on it within all code branches in the scope. For more examples see the [feature request](https://github.com/Microsoft/tslint-microsoft-contrib/issues/26). | 1.0
 `max-func-body-length`          | Avoid long functions. The line count of a function body must not exceed the value configured within this rule's options. <br>You can setup a general max function body length applied for every function/method/arrow function e.g. \[true, 30\] or set different maximum length for every type e.g. \[true, \{ "func-body-length": 10 , "func-expression-body-length": 10 , "arrow-body-length": 5, "method-body-length": 15, "ctor-body-length": 5 \}\]. To specify a function name whose parameters you can ignore for this rule, pass a regular expression as a string(this can be useful for Mocha users to ignore the describe() function). Since version 2.0.9, you can also ignore single- and multi-line comments from the total function length, eg. \[true, \{ "ignore-comments": true \}\] | 2.0.3
-`missing-jsdoc`                 | All files must have a top level [JSDoc](http://usejsdoc.org/) comment. A JSDoc comment starts with /** (not one more or one less asterisk) and a JSDoc at the 'top-level' appears without leading spaces. Trailing spaces are acceptable but not recommended. | 1.0
+`missing-jsdoc`                 | Deprecated - This rule can be replaced with TSLint's file-header. All files must have a top level [JSDoc](http://usejsdoc.org/) comment. A JSDoc comment starts with /** (not one more or one less asterisk) and a JSDoc at the 'top-level' appears without leading spaces. Trailing spaces are acceptable but not recommended. | 1.0
 `missing-optional-annotation`   | Deprecated - This rule is now enforced by the TypeScript compiler. A parameter that follows one or more parameters marked as optional is not itself marked optional | 0.0.1
 `mocha-avoid-only`              | Do not invoke Mocha's describe.only, it.only or context.only functions. These functions are useful ways to run a single unit test or a single test case during your build, but please be careful to not push these methods calls to your version control repository because it will turn off any of the other tests.| 1.0
 `mocha-no-side-effect-code`     | All test logic in a Mocha test case should be within Mocha lifecycle method and not defined statically to execute when the module loads. Put all assignments and initialization statements in a before(), beforeEach(), beforeAll(), after(), afterEach(), afterAll(), or it() function. Code executed outside of these lifecycle methods can throw exceptions before the test runner is initialized and can result in errors or even test runner crashes. This rule can be configured with a regex to ignore certain initializations. For example, to ignore any calls to `RestDataFactory` configure the rule with: `[true, { ignore: '^RestDataFactory\\..*' }]`| 2.0.10

diff --git a/recommended_ruleset.js b/recommended_ruleset.js
@@ -126,7 +126,6 @@ module.exports = {
         "max-line-length": [true, 140],
         "member-access": true,
         "member-ordering": [true, { "order": "fields-first" }],
-        "missing-jsdoc": true,
         "mocha-unneeded-done": true,
         "new-parens": true,
         "newline-per-chained-call": true,
@@ -257,6 +256,7 @@ module.exports = {
         /**
          * Deprecated rules.  The following rules are deprecated for various reasons.
          */
+        "missing-jsdoc": false,
         "missing-optional-annotation": false,  // now supported by TypeScript compiler
         "no-duplicate-case": false,
         "no-duplicate-parameter-names": false, // now supported by TypeScript compiler

diff --git a/src/chaiPreferContainsToIndexOfRule.ts b/src/chaiPreferContainsToIndexOfRule.ts
@@ -8,9 +8,6 @@ import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
 const FAILURE_STRING: string = 'Found chai call with indexOf that can be converted to .contain assertion: ';
 
-/**
- * Implementation of the chai-prefer-contains-to-index-of rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/chaiVagueErrorsRule.ts b/src/chaiVagueErrorsRule.ts
@@ -12,9 +12,6 @@ const FAILURE_STRING_COMPARE_TRUE: string = BASE_ERROR + 'Move the strict equali
 const FAILURE_STRING_COMPARE_FALSE: string = BASE_ERROR + 'Move the strict inequality comparison from the expect ' +
     'call into the assertion value. ';
 
-/**
- * Implementation of the chai-vague-errors rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/exportNameRule.ts b/src/exportNameRule.ts
@@ -8,9 +8,7 @@ import {AstUtils} from './utils/AstUtils';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
 export const OPTION_IGNORE_CASE: string = 'ignore-case';
-/**
- * Implementation of the export-name rule.
- */
+
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/functionNameRule.ts b/src/functionNameRule.ts
@@ -41,9 +41,6 @@ interface Options {
     readonly validateStatics: string;
 }
 
-/**
- * Implementation of the function-name rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/importNameRule.ts b/src/importNameRule.ts
@@ -6,9 +6,6 @@ import {Utils} from './utils/Utils';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 import { isObject } from './utils/TypeGuard';
 
-/**
- * Implementation of the import-name rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/informativeDocsRule.ts b/src/informativeDocsRule.ts
@@ -28,7 +28,7 @@ interface Options {
 export class Rule extends Lint.Rules.AbstractRule {
     public static metadata: ExtendedMetadata = {
         description: 'Enforces that comments do more than just reiterate names of objects.',
-        options: null,
+        options: undefined,
         optionsDescription: 'Not configurable.',
         optionExamples: [
             true,
@@ -65,10 +65,10 @@ export class Rule extends Lint.Rules.AbstractRule {
     }
 }
 
-function parseOptions(ruleArguments: any[]): Options {
+function parseOptions(ruleArguments: unknown[]): Options {
     const rawOptions: RawOptions = ruleArguments.length === 0
         ? {}
-        : ruleArguments[0];
+        : <RawOptions>ruleArguments[0];
 
     return {
         aliases: parseAliasesOption(

diff --git a/src/insecureRandomRule.ts b/src/insecureRandomRule.ts
@@ -10,9 +10,6 @@ const MATH_FAIL_STRING: string = 'Math.random produces insecure random numbers.
 const NODE_FAIL_STRING: string = 'crypto.pseudoRandomBytes produces insecure random numbers. ' +
     'Use crypto.randomBytes() instead';
 
-/**
- * Implementation of the insecure-random rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/jqueryDeferredMustCompleteRule.ts b/src/jqueryDeferredMustCompleteRule.ts
@@ -6,9 +6,6 @@ import {AstUtils} from './utils/AstUtils';
 import {Utils} from './utils/Utils';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the jquery-deferred-must-complete rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/maxFuncBodyLengthRule.ts b/src/maxFuncBodyLengthRule.ts
@@ -6,9 +6,6 @@ import {ExtendedMetadata} from './utils/ExtendedMetadata';
 import {forEachTokenWithTrivia} from 'tsutils';
 import { isObject } from './utils/TypeGuard';
 
-/**
- * Implementation of the max-func-body-length rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/missingJsdocRule.ts b/src/missingJsdocRule.ts
@@ -4,9 +4,6 @@ import * as Lint from 'tslint';
 import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the missing-jsdoc rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {
@@ -16,17 +13,24 @@ export class Rule extends Lint.Rules.AbstractRule {
         options: null, // tslint:disable-line:no-null-keyword
         optionsDescription: '',
         typescriptOnly: true,
-        issueClass: 'Non-SDL',
+        issueClass: 'Ignored',
         issueType: 'Warning',
         severity: 'Low',
         level: 'Opportunity for Excellence',
-        group: 'Clarity',
-        commonWeaknessEnumeration: '398, 710'
+        group: 'Deprecated',
+        recommendation: 'false,'
     };
 
     public static FAILURE_STRING: string = 'File missing JSDoc comment at the top-level: ';
 
+    private static isWarningShown: boolean = false;
+
     public apply(sourceFile: ts.SourceFile): Lint.RuleFailure[] {
+        if (Rule.isWarningShown === false) {
+            console.warn('Warning: missing-jsdoc rule is deprecated. ' +
+                'Replace your usage with the TSLint missing-jsdoc rule.');
+            Rule.isWarningShown = true;
+        }
         return this.applyWithWalker(new MissingJSDocWalker(sourceFile, this.getOptions()));
     }
 }

diff --git a/src/missingOptionalAnnotationRule.ts b/src/missingOptionalAnnotationRule.ts
@@ -4,9 +4,6 @@ import * as Lint from 'tslint';
 import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the missing-optional-annotation rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/mochaAvoidOnlyRule.ts b/src/mochaAvoidOnlyRule.ts
@@ -5,9 +5,6 @@ import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 import {MochaUtils} from './utils/MochaUtils';
 
-/**
- * Implementation of the mocha-avoid-only rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/mochaNoSideEffectCodeRule.ts b/src/mochaNoSideEffectCodeRule.ts
@@ -10,9 +10,6 @@ import { isObject } from './utils/TypeGuard';
 
 const FAILURE_STRING: string = 'Mocha test contains dangerous variable initialization. Move to before()/beforeEach(): ';
 
-/**
- * Implementation of the mocha-no-side-effect-code rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/mochaUnneededDoneRule.ts b/src/mochaUnneededDoneRule.ts
@@ -8,9 +8,6 @@ import {MochaUtils} from './utils/MochaUtils';
 
 const FAILURE_STRING: string = 'Unneeded Mocha Done. Parameter can be safely removed: ';
 
-/**
- * Implementation of the mocha-unneeded-done rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noBackboneGetSetOutsideModelRule.ts b/src/noBackboneGetSetOutsideModelRule.ts
@@ -5,12 +5,6 @@ import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {AstUtils} from './utils/AstUtils';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-backbone-get-set-outside-model rule.
- *
- * Currently only makes sure that get and set Backbone methods are called
- * on the this reference.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noBannedTermsRule.ts b/src/noBannedTermsRule.ts
@@ -4,9 +4,6 @@ import * as Lint from 'tslint';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 import {BannedTermWalker} from './utils/BannedTermWalker';
 
-/**
- * Implementation of the no-banned-terms rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noConstantConditionRule.ts b/src/noConstantConditionRule.ts
@@ -6,9 +6,6 @@ import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 import { isObject } from './utils/TypeGuard';
 
-/**
- * Implementation of the no-constant-condition rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noControlRegexRule.ts b/src/noControlRegexRule.ts
@@ -4,9 +4,6 @@ import * as Lint from 'tslint';
 import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-control-regex rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noCookiesRule.ts b/src/noCookiesRule.ts
@@ -4,9 +4,6 @@ import * as Lint from 'tslint';
 import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-cookies-rule rule.
- */
 export class Rule extends Lint.Rules.TypedRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noDeleteExpressionRule.ts b/src/noDeleteExpressionRule.ts
@@ -4,9 +4,6 @@ import * as Lint from 'tslint';
 import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-delete-expression rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noDisableAutoSanitizationRule.ts b/src/noDisableAutoSanitizationRule.ts
@@ -5,9 +5,6 @@ import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {AstUtils} from './utils/AstUtils';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-disable-auto-sanitization rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noDocumentDomainRule.ts b/src/noDocumentDomainRule.ts
@@ -4,9 +4,6 @@ import * as Lint from 'tslint';
 import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-document-domain rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noDocumentWriteRule.ts b/src/noDocumentWriteRule.ts
@@ -5,9 +5,6 @@ import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {AstUtils} from './utils/AstUtils';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-document-write rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noDuplicateCaseRule.ts b/src/noDuplicateCaseRule.ts
@@ -4,9 +4,6 @@ import * as Lint from 'tslint';
 import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-duplicate-case rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noDuplicateParameterNamesRule.ts b/src/noDuplicateParameterNamesRule.ts
@@ -4,9 +4,6 @@ import * as Lint from 'tslint';
 import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-duplicate-parameter-names rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noEmptyInterfacesRule.ts b/src/noEmptyInterfacesRule.ts
@@ -4,9 +4,6 @@ import * as Lint from 'tslint';
 import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-empty-interfaces rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noEmptyLineAfterOpeningBraceRule.ts b/src/noEmptyLineAfterOpeningBraceRule.ts
@@ -5,9 +5,6 @@ import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 import {forEachTokenWithTrivia} from 'tsutils';
 
-/**
- * Implementation of the no-empty-line-after-opening-brace rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noExecScriptRule.ts b/src/noExecScriptRule.ts
@@ -6,9 +6,6 @@ import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
 import {AstUtils} from './utils/AstUtils';
 
-/**
- * Implementation of the no-exec-script rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noForInRule.ts b/src/noForInRule.ts
@@ -4,9 +4,6 @@ import * as Lint from 'tslint';
 import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-for-in rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noFunctionConstructorWithStringArgsRule.ts b/src/noFunctionConstructorWithStringArgsRule.ts
@@ -5,9 +5,6 @@ import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {AstUtils} from './utils/AstUtils';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-function-constructor-with-string-args rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noFunctionExpressionRule.ts b/src/noFunctionExpressionRule.ts
@@ -5,9 +5,6 @@ import { AstUtils } from './utils/AstUtils';
 import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-function-expression rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noHttpStringRule.ts b/src/noHttpStringRule.ts
@@ -5,9 +5,6 @@ import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {Utils} from './utils/Utils';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-http-string rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {

diff --git a/src/noIncrementDecrementRule.ts b/src/noIncrementDecrementRule.ts
@@ -4,9 +4,6 @@ import * as Lint from 'tslint';
 import {ErrorTolerantWalker} from './utils/ErrorTolerantWalker';
 import {ExtendedMetadata} from './utils/ExtendedMetadata';
 
-/**
- * Implementation of the no-increment-decrement rule.
- */
 export class Rule extends Lint.Rules.AbstractRule {
 
     public static metadata: ExtendedMetadata = {