v4.1.0 doc update

girgez · Dec 16, 2016 · bf8084a · bf8084a
1 parent dc0ceca
commit bf8084a
Show file tree

Hide file tree

Showing 18 changed files with 277 additions and 24 deletions.
diff --git a/_data/formatters.json b/_data/formatters.json
@@ -6,6 +6,13 @@
     "sample": "\n<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<checkstyle version=\"4.3\">\n    <file name=\"myFile.ts\">\n        <error line=\"1\" column=\"14\" severity=\"warning\" message=\"Missing semicolon\" source=\"failure.tslint.semicolon\" />\n    </file>\n</checkstyle>",
     "consumer": "machine"
   },
+  {
+    "formatterName": "codeFrame",
+    "description": "Framed formatter which creates a frame of error code.",
+    "descriptionDetails": "\nPrints syntax highlighted code in a frame with a pointer to where\nexactly lint error is happening.",
+    "sample": "\nsrc/components/Payment.tsx\nParentheses are required around the parameters of an arrow function definition (arrow-parens)\n  21 |     public componentDidMount() {\n  22 |         this.input.focus();\n> 23 |         loadStripe().then(Stripe => Stripe.pay());\n     |                          ^\n  24 |     }\n  25 |\n  26 |     public render() {",
+    "consumer": "human"
+  },
   {
     "formatterName": "filesList",
     "description": "Lists files containing lint errors.",

diff --git a/_data/rules.json b/_data/rules.json
@@ -70,7 +70,7 @@
   {
     "ruleName": "ban",
     "description": "Bans the use of specific functions or global methods.",
-    "optionsDescription": "\nA list of `['object', 'method', 'optional explanation here']` or `['globalMethod']` which ban `object.method()` \nor respectively `globalMethod()`.",
+    "optionsDescription": "\nA list of `['object', 'method', 'optional explanation here']` or `['globalMethod']` which ban `object.method()`\nor respectively `globalMethod()`.",
     "options": {
       "type": "list",
       "listType": {
@@ -83,7 +83,7 @@
       }
     },
     "optionExamples": [
-      "[true, [\"someGlobalMethod\"], [\"someObject\", \"someFunction\"], \n                          [\"someObject\", \"otherFunction\", \"Optional explanation\"]]"
+      "[true, [\"someGlobalMethod\"], [\"someObject\", \"someFunction\"],\n                          [\"someObject\", \"otherFunction\", \"Optional explanation\"]]"
     ],
     "type": "functionality",
     "typescriptOnly": false
@@ -142,7 +142,7 @@
     },
     "optionExamples": [
       "true",
-      "[true, [\"classes\", \"functions\"]"
+      "[true, \"classes\", \"functions\"]"
     ],
     "type": "style",
     "typescriptOnly": false
@@ -213,6 +213,25 @@
     "type": "functionality",
     "typescriptOnly": false
   },
+  {
+    "ruleName": "import-blacklist",
+    "description": "\nDisallows importing the specified modules directly via `import` and `require`.\nInstead only sub modules may be imported from that module.",
+    "rationale": "\nSome libraries allow importing their submodules instead of the entire module.\nThis is good practise as it avoids loading unused modules.",
+    "optionsDescription": "A list of blacklisted modules.",
+    "options": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minLength": 1
+    },
+    "optionExamples": [
+      "true",
+      "[true, \"rxjs\", \"lodash\"]"
+    ],
+    "type": "functionality",
+    "typescriptOnly": false
+  },
   {
     "ruleName": "indent",
     "description": "Enforces indentation with tabs or spaces.",
@@ -642,6 +661,18 @@
     "type": "typescript",
     "typescriptOnly": true
   },
+  {
+    "ruleName": "no-inferred-empty-object-type",
+    "description": "Disallow type inference of {} (empty object type) at function and constructor call sites",
+    "optionsDescription": "Not configurable.",
+    "options": null,
+    "optionExamples": [
+      "true"
+    ],
+    "type": "functionality",
+    "typescriptOnly": true,
+    "requiresTypeInfo": true
+  },
   {
     "ruleName": "no-internal-module",
     "description": "Disallows internal `module`",
@@ -677,6 +708,25 @@
     "type": "functionality",
     "typescriptOnly": false
   },
+  {
+    "ruleName": "no-magic-numbers",
+    "description": "\nDisallows the use constant number values outside of variable assignments.\nWhen no list of allowed values is specified, -1, 0 and 1 are allowed by default.",
+    "rationale": "\nMagic numbers should be avoided as they often lack documentation, forcing\nthem to be stored in variables gives them implicit documentation.",
+    "optionsDescription": "A list of allowed numbers.",
+    "options": {
+      "type": "array",
+      "items": {
+        "type": "number"
+      },
+      "minLength": 1
+    },
+    "optionExamples": [
+      "true",
+      "[true, 1, 2, 3]"
+    ],
+    "type": "typescript",
+    "typescriptOnly": false
+  },
   {
     "ruleName": "no-mergeable-namespace",
     "description": "Disallows mergeable namespaces in the same file.",
@@ -925,7 +975,7 @@
     "ruleName": "object-literal-key-quotes",
     "description": "Enforces consistent object literal property quote style.",
     "descriptionDetails": "\nObject literal property names can be defined in two ways: using literals or using strings.\nFor example, these two objects are equivalent:\n\nvar object1 = {\n    property: true\n};\n\nvar object2 = {\n    \"property\": true\n};\n\nIn many cases, it doesn’t matter if you choose to use an identifier instead of a string\nor vice-versa. Even so, you might decide to enforce a consistent style in your code.\n\nThis rules lets you enforce consistent quoting of property names. Either they should always\nbe quoted (default behavior) or quoted only as needed (\"as-needed\").",
-    "optionsDescription": "\nPossible settings are:\n\n* `\"always\"`: Property names should always be quoted. (This is the default.)\n* `\"as-needed\"`: Only property names which require quotes may be quoted (e.g. those with spaces in them).\n* `\"consistent\"`: Property names should either all be quoted or unquoted.\n* `\"consistent-as-needed\"`: If any property name requires quotes, then all properties must be quoted. Otherwise, no \nproperty names may be quoted.\n\nFor ES6, computed property names (`{[name]: value}`) and methods (`{foo() {}}`) never need\nto be quoted.",
+    "optionsDescription": "\nPossible settings are:\n\n* `\"always\"`: Property names should always be quoted. (This is the default.)\n* `\"as-needed\"`: Only property names which require quotes may be quoted (e.g. those with spaces in them).\n* `\"consistent\"`: Property names should either all be quoted or unquoted.\n* `\"consistent-as-needed\"`: If any property name requires quotes, then all properties must be quoted. Otherwise, no\nproperty names may be quoted.\n\nFor ES6, computed property names (`{[name]: value}`) and methods (`{foo() {}}`) never need\nto be quoted.",
     "options": {
       "type": "string",
       "enum": [
@@ -1016,21 +1066,22 @@
     "ruleName": "only-arrow-functions",
     "description": "Disallows traditional (non-arrow) function expressions.",
     "rationale": "Traditional functions don't bind lexical scope, which can lead to unexpected behavior when accessing 'this'.",
-    "optionsDescription": "\nOne argument may be optionally provided:\n\n* `\"allow-declarations\"` allows standalone function declarations.\n        ",
+    "optionsDescription": "\nTwo arguments may be optionally provided:\n\n* `\"allow-declarations\"` allows standalone function declarations.\n* `\"allow-named-functions\"` allows the expression `function foo() {}` but not `function() {}`.\n        ",
     "options": {
       "type": "array",
       "items": {
         "type": "string",
         "enum": [
-          "allow-declarations"
+          "allow-declarations",
+          "allow-named-functions"
         ]
       },
       "minLength": 0,
       "maxLength": 1
     },
     "optionExamples": [
       "true",
-      "[true, \"allow-declarations\"]"
+      "[true, \"allow-declarations\", \"allow-named-functions\"]"
     ],
     "type": "typescript",
     "typescriptOnly": false
@@ -1039,7 +1090,7 @@
     "ruleName": "ordered-imports",
     "description": "Requires that import statements be alphabetized.",
     "descriptionDetails": "\nEnforce a consistent ordering for ES6 imports:\n- Named imports must be alphabetized (i.e. \"import {A, B, C} from \"foo\";\")\n    - The exact ordering can be controlled by the named-imports-order option.\n    - \"longName as name\" imports are ordered by \"longName\".\n- Import sources must be alphabetized within groups, i.e.:\n        import * as foo from \"a\";\n        import * as bar from \"b\";\n- Groups of imports are delineated by blank lines. You can use these to group imports\n    however you like, e.g. by first- vs. third-party or thematically.",
-    "optionsDescription": "\nYou may set the `\"import-sources-order\"` option to control the ordering of source\nimports (the `\"foo\"` in `import {A, B, C} from \"foo\"`).\n\nPossible values for `\"import-sources-order\"` are:\n* `\"case-insensitive'`: Correct order is `\"Bar\"`, `\"baz\"`, `\"Foo\"`. (This is the default.)\n* `\"lowercase-first\"`: Correct order is `\"baz\"`, `\"Bar\"`, `\"Foo\"`.\n* `\"lowercase-last\"`: Correct order is `\"Bar\"`, `\"Foo\"`, `\"baz\"`.\n* `\"any\"`: Allow any order.\n\nYou may set the `\"named-imports-order\"` option to control the ordering of named\nimports (the `{A, B, C}` in `import {A, B, C} from \"foo\"`).\n\nPossible values for `\"named-imports-order\"` are:\n\n* `\"case-insensitive'`: Correct order is `{A, b, C}`. (This is the default.)\n* `\"lowercase-first\"`: Correct order is `{b, A, C}`.\n* `\"lowercase-last\"`: Correct order is `{A, C, b}`.\n* `\"any\"`: Allow any order.\n\n        ",
+    "optionsDescription": "\nYou may set the `\"import-sources-order\"` option to control the ordering of source\nimports (the `\"foo\"` in `import {A, B, C} from \"foo\"`).\n\nPossible values for `\"import-sources-order\"` are:\n\n* `\"case-insensitive'`: Correct order is `\"Bar\"`, `\"baz\"`, `\"Foo\"`. (This is the default.)\n* `\"lowercase-first\"`: Correct order is `\"baz\"`, `\"Bar\"`, `\"Foo\"`.\n* `\"lowercase-last\"`: Correct order is `\"Bar\"`, `\"Foo\"`, `\"baz\"`.\n* `\"any\"`: Allow any order.\n\nYou may set the `\"named-imports-order\"` option to control the ordering of named\nimports (the `{A, B, C}` in `import {A, B, C} from \"foo\"`).\n\nPossible values for `\"named-imports-order\"` are:\n\n* `\"case-insensitive'`: Correct order is `{A, b, C}`. (This is the default.)\n* `\"lowercase-first\"`: Correct order is `{b, A, C}`.\n* `\"lowercase-last\"`: Correct order is `{A, C, b}`.\n* `\"any\"`: Allow any order.\n\n        ",
     "options": {
       "type": "object",
       "properties": {
@@ -1071,6 +1122,18 @@
     "type": "style",
     "typescriptOnly": false
   },
+  {
+    "ruleName": "prefer-const",
+    "description": "Requires that variable declarations use `const` instead of `let` if possible.",
+    "descriptionDetails": "\nIf a variable is only assigned to once when it is declared, it should be declared using 'const'",
+    "optionsDescription": "Not configurable.",
+    "options": null,
+    "optionExamples": [
+      "true"
+    ],
+    "type": "maintainability",
+    "typescriptOnly": false
+  },
   {
     "ruleName": "prefer-for-of",
     "description": "Recommends a 'for-of' loop over a standard 'for' loop if the index is only used to access the array being iterated.",
@@ -1083,6 +1146,19 @@
     "type": "typescript",
     "typescriptOnly": false
   },
+  {
+    "ruleName": "promise-function-async",
+    "description": "Requires any function or method that returns a promise to be marked async.",
+    "rationale": "\nEnsures that each function is only capable of 1) returning a rejected promise, or 2)\nthrowing an Error object. In contrast, non-`async` `Promise`-returning functions\nare technically capable of either. This practice removes a requirement for consuming\ncode to handle both cases.\n        ",
+    "optionsDescription": "Not configurable.",
+    "options": null,
+    "optionExamples": [
+      "true"
+    ],
+    "type": "typescript",
+    "typescriptOnly": false,
+    "requiresTypeInfo": true
+  },
   {
     "ruleName": "quotemark",
     "description": "Requires single or double quotes for string literals.",
@@ -1112,7 +1188,7 @@
   {
     "ruleName": "radix",
     "description": "Requires the radix parameter to be specified when calling `parseInt`.",
-    "rationale": "\nFrom [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt): \n> Always specify this parameter to eliminate reader confusion and to guarantee predictable behavior.\n> Different implementations produce different results when a radix is not specified, usually defaulting the value to 10.",
+    "rationale": "\nFrom [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt):\n> Always specify this parameter to eliminate reader confusion and to guarantee predictable behavior.\n> Different implementations produce different results when a radix is not specified, usually defaulting the value to 10.",
     "optionsDescription": "Not configurable.",
     "options": null,
     "optionExamples": [
@@ -1165,6 +1241,18 @@
     "type": "style",
     "typescriptOnly": false
   },
+  {
+    "ruleName": "strict-boolean-expressions",
+    "description": "Usage of && or || operators should be with boolean operands and\nexpressions in If, Do, While and For statements should be of type boolean",
+    "optionsDescription": "Not configurable.",
+    "options": null,
+    "optionExamples": [
+      "true"
+    ],
+    "type": "functionality",
+    "typescriptOnly": true,
+    "requiresTypeInfo": true
+  },
   {
     "ruleName": "switch-default",
     "description": "Require a `default` case in all `switch` statements.",

diff --git a/formatters/codeFrame/index.html b/formatters/codeFrame/index.html
@@ -0,0 +1,22 @@
+---
+formatterName: codeFrame
+description: Framed formatter which creates a frame of error code.
+descriptionDetails: |-
+
+  Prints syntax highlighted code in a frame with a pointer to where
+  exactly lint error is happening.
+sample: |-
+
+  src/components/Payment.tsx
+  Parentheses are required around the parameters of an arrow function definition (arrow-parens)
+    21 |     public componentDidMount() {
+    22 |         this.input.focus();
+  > 23 |         loadStripe().then(Stripe => Stripe.pay());
+       |                          ^
+    24 |     }
+    25 |
+    26 |     public render() {
+consumer: human
+layout: formatter
+title: 'Formatter: codeFrame'
+---
diff --git a/index.md b/index.md
@@ -35,7 +35,7 @@ Lint your TypeScript files!
 tslint -c path/to/tslint.json 'path/to/project/**/*.ts'
 ```
 
-Check out [the full usage guide][1] to learn more...
+Check out [the full usage guide][1] to learn more.
 
 [0]: http://www.typescriptlang.org/
 [1]: usage/cli
diff --git a/rules/ban/index.html b/rules/ban/index.html
@@ -3,7 +3,7 @@
 description: Bans the use of specific functions or global methods.
 optionsDescription: |-
 
-  A list of `['object', 'method', 'optional explanation here']` or `['globalMethod']` which ban `object.method()` 
+  A list of `['object', 'method', 'optional explanation here']` or `['globalMethod']` which ban `object.method()`
   or respectively `globalMethod()`.
 options:
   type: list
@@ -15,7 +15,7 @@
     maxLength: 3
 optionExamples:
   - |-
-    [true, ["someGlobalMethod"], ["someObject", "someFunction"], 
+    [true, ["someGlobalMethod"], ["someObject", "someFunction"],
                               ["someObject", "otherFunction", "Optional explanation"]]
 type: functionality
 typescriptOnly: false

diff --git a/rules/completed-docs/index.html b/rules/completed-docs/index.html
@@ -17,7 +17,7 @@
       - properties
 optionExamples:
   - 'true'
-  - '[true, ["classes", "functions"]'
+  - '[true, "classes", "functions"]'
 type: style
 typescriptOnly: false
 layout: rule

diff --git a/rules/import-blacklist/index.html b/rules/import-blacklist/index.html
@@ -0,0 +1,32 @@
+---
+ruleName: import-blacklist
+description: |-
+
+  Disallows importing the specified modules directly via `import` and `require`.
+  Instead only sub modules may be imported from that module.
+rationale: |-
+
+  Some libraries allow importing their submodules instead of the entire module.
+  This is good practise as it avoids loading unused modules.
+optionsDescription: A list of blacklisted modules.
+options:
+  type: array
+  items:
+    type: string
+  minLength: 1
+optionExamples:
+  - 'true'
+  - '[true, "rxjs", "lodash"]'
+type: functionality
+typescriptOnly: false
+layout: rule
+title: 'Rule: import-blacklist'
+optionsJSON: |-
+  {
+    "type": "array",
+    "items": {
+      "type": "string"
+    },
+    "minLength": 1
+  }
+---
diff --git a/rules/no-inferred-empty-object-type/index.html b/rules/no-inferred-empty-object-type/index.html
@@ -0,0 +1,14 @@
+---
+ruleName: no-inferred-empty-object-type
+description: 'Disallow type inference of {} (empty object type) at function and constructor call sites'
+optionsDescription: Not configurable.
+options: null
+optionExamples:
+  - 'true'
+type: functionality
+typescriptOnly: true
+requiresTypeInfo: true
+layout: rule
+title: 'Rule: no-inferred-empty-object-type'
+optionsJSON: 'null'
+---
diff --git a/rules/no-magic-numbers/index.html b/rules/no-magic-numbers/index.html
@@ -0,0 +1,32 @@
+---
+ruleName: no-magic-numbers
+description: |-
+
+  Disallows the use constant number values outside of variable assignments.
+  When no list of allowed values is specified, -1, 0 and 1 are allowed by default.
+rationale: |-
+
+  Magic numbers should be avoided as they often lack documentation, forcing
+  them to be stored in variables gives them implicit documentation.
+optionsDescription: A list of allowed numbers.
+options:
+  type: array
+  items:
+    type: number
+  minLength: 1
+optionExamples:
+  - 'true'
+  - '[true, 1, 2, 3]'
+type: typescript
+typescriptOnly: false
+layout: rule
+title: 'Rule: no-magic-numbers'
+optionsJSON: |-
+  {
+    "type": "array",
+    "items": {
+      "type": "number"
+    },
+    "minLength": 1
+  }
+---
diff --git a/rules/object-literal-key-quotes/index.html b/rules/object-literal-key-quotes/index.html
@@ -26,7 +26,7 @@
   * `"always"`: Property names should always be quoted. (This is the default.)
   * `"as-needed"`: Only property names which require quotes may be quoted (e.g. those with spaces in them).
   * `"consistent"`: Property names should either all be quoted or unquoted.
-  * `"consistent-as-needed"`: If any property name requires quotes, then all properties must be quoted. Otherwise, no 
+  * `"consistent-as-needed"`: If any property name requires quotes, then all properties must be quoted. Otherwise, no
   property names may be quoted.
 
   For ES6, computed property names (`{[name]: value}`) and methods (`{foo() {}}`) never need