Update docs for 5.1.0-dev

_data/rules.json

@@ -1072,6 +1072,17 @@
     "type": "typescript",
     "typescriptOnly": true
   },
+  {
+    "ruleName": "no-invalid-template-strings",
+    "description": "Warns on use of `${` in non-template strings.",
+    "optionsDescription": "Not configurable.",
+    "options": null,
+    "optionExamples": [
+      "true"
+    ],
+    "type": "functionality",
+    "typescriptOnly": false
+  },
   {
     "ruleName": "no-invalid-this",
     "description": "Disallows using the `this` keyword outside of classes.",
@@ -1240,6 +1251,18 @@
     "type": "functionality",
     "typescriptOnly": false
   },
+  {
+    "ruleName": "no-sparse-arrays",
+    "description": "Forbids array literals to contain missing elements.",
+    "rationale": "Missing elements are probably an accidentally duplicated comma.",
+    "optionsDescription": "Not configurable.",
+    "options": null,
+    "optionExamples": [
+      "true"
+    ],
+    "type": "functionality",
+    "typescriptOnly": false
+  },
   {
     "ruleName": "no-string-literal",
     "description": "Disallows object access via string literals.",
@@ -1408,8 +1431,7 @@
           {
             "type": "string",
             "enum": [
-              "check-parameters",
-              "react"
+              "check-parameters"
             ]
           },
           {
@@ -1427,7 +1449,7 @@
       "maxLength": 3
     },
     "optionExamples": [
-      "[true, \"react\"]",
+      "[true]",
       "[true, {\"ignore-pattern\": \"^_\"}]"
     ],
     "type": "functionality",
@@ -1473,8 +1495,18 @@
   {
     "ruleName": "no-void-expression",
     "description": "Requires expressions of type `void` to appear in statement position.",
-    "optionsDescription": "Not configurable.",
-    "options": null,
+    "optionsDescription": "\nIf `ignore-arrow-function-shorthand` is provided, `() => returnsVoid()` will be allowed.\nOtherwise, it must be written as `() => { returnsVoid(); }`.",
+    "options": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "ignore-arrow-function-shorthand"
+        ]
+      },
+      "minLength": 0,
+      "maxLength": 1
+    },
     "requiresTypeInfo": true,
     "type": "functionality",
     "typescriptOnly": false
@@ -1883,7 +1915,7 @@
   {
     "ruleName": "strict-boolean-expressions",
     "description": "\nRestricts the types allowed in boolean expressions. By default only booleans are allowed.\n\nThe following nodes are checked:\n\n* Arguments to the `!`, `&&`, and `||` operators\n* The condition in a conditional expression (`cond ? x : y`)\n* Conditions for `if`, `for`, `while`, and `do-while` statements.",
-    "optionsDescription": "\nThese options may be provided:\n\n* `allow-null-union` allows union types containing `null`.\n  - It does *not* allow `null` itself.\n* `allow-undefined-union` allows union types containing `undefined`.\n  - It does *not* allow `undefined` itself.\n* `allow-string` allows strings.\n  - It does *not* allow unions containing `string`.\n  - It does *not* allow string literal types.\n* `allow-number` allows numbers.\n  - It does *not* allow unions containing `number`.\n  - It does *not* allow enums or number literal types.\n* `allow-mix` allow multiple of the above to appear together.\n  - For example, `string | number` or `RegExp | null | undefined` would normally not be allowed.\n  - A type like `\"foo\" | \"bar\" | undefined` is always allowed, because it has only one way to be false.",
+    "optionsDescription": "\nThese options may be provided:\n\n* `allow-null-union` allows union types containing `null`.\n  - It does *not* allow `null` itself.\n  - Without the '--strictNullChecks' compiler option, this will allow anything other than a string, number, or enum.\n* `allow-undefined-union` allows union types containing `undefined`.\n  - It does *not* allow `undefined` itself.\n  - Without the '--strictNullChecks' compiler option, this will allow anything other than a string, number, or enum.\n* `allow-string` allows strings.\n  - It does *not* allow unions containing `string`.\n  - It does *not* allow string literal types.\n* `allow-number` allows numbers.\n  - It does *not* allow unions containing `number`.\n  - It does *not* allow enums or number literal types.\n* `allow-mix` allow multiple of the above to appear together.\n  - For example, `string | number` or `RegExp | null | undefined` would normally not be allowed.\n  - A type like `\"foo\" | \"bar\" | undefined` is always allowed, because it has only one way to be false.",
     "options": {
       "type": "array",
       "items": {

_data/usage_sidebar.json

@@ -10,21 +10,25 @@
          "title": "Library",
          "url": "/library/"
       },
-      {
-         "title": "Third-Party Tools",
-         "url": "/third-party-tools/"
-      },
       {
          "title": "tslint.json",
          "url": "/tslint-json/"
       },
+      {
+         "title": "Rule Flags",
+         "url": "/rule-flags/"
+      },
+      {
+          "title": "Type Checking",
+          "url": "/type-checking/"
+      },
       {
          "title": "Custom Rules",
          "url": "/custom-rules/"
       },
       {
-         "title": "Rule Flags",
-         "url": "/rule-flags/"
+         "title": "Third-Party Tools",
+         "url": "/third-party-tools/"
       }
    ]
 }

_includes/peer_dependencies.md

@@ -1,10 +1,6 @@
-##### Peer dependencies #####
+##### Peer dependencies
 
-The `typescript` module is a peer dependency of TSLint, which allows you to update the compiler independently from the
-linter. This also means that `tslint` will have to use the same version of `tsc` used to actually compile your sources.
+The `typescript` package is a peer dependency of TSLint. This allows you to update the compiler independently from the linter.
+This also means that `tslint` will have to use the same version of `tsc` which is used to actually compile your sources.
 
-Breaking changes in the latest dev release of `typescript@next` might break something in the linter if we haven't built against that release yet. If this happens to you, you can try:
-
-1. picking up `tslint@next`, which may have some bugfixes not released in `tslint@latest`
-   (see [release notes here](https://github.com/palantir/tslint/releases)).
-2. rolling back `typescript` to a known working version.
+Although the peer dependency allows installing the latest nightly releases of `typescript@next`, be aware that these might include breaking changes that cause the linter to malfunction.

develop/custom-formatters/index.md

@@ -20,4 +20,4 @@ export class Formatter extends Lint.Formatters.AbstractFormatter {
 
 Such custom formatters can also be written in Javascript. Additionally, formatter files are always named with the suffix `Formatter`, and referenced from TSLint without its suffix.
 
-[0]: {{site.baseurl | append: "/develop/custom-rules"}}
+[0]: {{site.baseurl | append: "/develop/custom-rules"}}

develop/custom-rules/index.md

@@ -3,6 +3,7 @@ title: Custom Rules
 layout: page
 permalink: "/develop/custom-rules/"
 ---
+
 TSLint ships with a set of core rules that can be configured. However, users are also allowed to write their own rules, which allows them to enforce specific behavior not covered by the core of TSLint. TSLint's internal rules are itself written to be pluggable, so adding a new rule is as simple as creating a new rule file named by convention. New rules can be written in either TypeScript or JavaScript; if written in TypeScript, the code must be compiled to JavaScript before invoking TSLint.
 
 Let us take the example of how to write a new rule to forbid all import statements (you know, *for science*). Let us name the rule file `noImportsRule.ts`. Rules are referenced in `tslint.json` with their kebab-cased identifer, so `"no-imports": true` would configure the rule.
@@ -44,8 +45,8 @@ Given a walker, TypeScript's parser visits the AST using the visitor pattern. So
 
 We still need to hook up this new rule to TSLint. First make sure to compile `noImportsRule.ts`:
 
-```bash
-tsc --noImplicitAny noImportsRule.ts
+```sh
+tsc noImportsRule.ts
 ```
 
 Then, if using the CLI, provide the directory that contains this rule as an option to `--rules-dir`. If using TSLint as a library or via `grunt-tslint`, the `options` hash must contain `"rulesDirectory": "..."`. If you run the linter, you'll see that we have now successfully banned all import statements via TSLint!
@@ -60,8 +61,7 @@ Instantiate a `Fix` object and pass it in as an argument to `addFailure`. This s
 
 ```typescript
 // create a fixer for this failure
-const replacement = new Lint.Replacement(node.getStart(), node.getWidth(), "");
-const fix = new Lint.Fix("no-imports", [replacement]);
+const fix = new Lint.Replacement(node.getStart(), node.getWidth(), "");
 
 // create a failure at the current position
 this.addFailure(this.createFailure(node.getStart(), node.getWidth(), Rule.FAILURE_STRING, fix));

formatters/index.md

@@ -0,0 +1,16 @@
+---
+layout: page
+title: Formatters
+permalink: /formatters/
+menu: main
+order: 2
+---
+
+_Formatters_ allow for transformation of lint results into various forms before outputting to stdout or a file.
+
+### Built-in formatters
+
+{% assign formatters = site.data.formatters | sort: "name" %}
+{% for formatter in formatters %}
+* [{{formatter.formatterName}}]({{formatter.formatterName}})</a> - {{formatter.description | markdownify | remove:"<p>" | remove: "</p>"}}
+{% endfor %}

index.md

@@ -3,36 +3,23 @@ title: TSLint
 layout: default
 subtitle: An extensible linter for the TypeScript language.
 ---
-TSLint checks your [TypeScript][0] code for readability, maintainability, and functionality errors.
 
-## Getting Started
+TSLint is a static analysis tool that checks your [TypeScript][0] code for readability, maintainability, and functionality errors. It is widely supported across modern editors & build systems and can be customized with your own lint rules, configurations, and formatters.
 
-#### Local installation
+## Quick start
 
 ```sh
-$ npm install tslint typescript --save-dev
-```
-
-#### Global installation
-
-```sh
-$ npm install tslint typescript -g
-```
-
-#### Configuration
+# Install the global CLI and its peer dependency
+yarn global add tslint typescript
 
-Generate a skeleton `tslint.json` config file with the `--init` CLI flag:
-
-```sh
+# Navigate to to your sources folder
 cd path/to/project
-tslint --init
-```
 
-Lint your TypeScript files!
+# Generate a basic configuration file
+tslint --init
 
-```
-// provide globs as strings
-tslint -c path/to/tslint.json 'path/to/project/**/*.ts'
+# Lint TypeScript source globs
+tslint -c tslint.json 'src/**/*.ts'
 ```
 
 Check out [the full usage guide][1] to learn more.

rules/index.md

@@ -0,0 +1,33 @@
+---
+layout: page
+title: Rules
+permalink: /rules/
+menu: main
+order: 2
+---
+
+_Rules_ encode logic for syntactic & semantic checks of TypeScript source code.
+
+### TypeScript Specific
+
+_These rules find errors related to TypeScript features_:
+
+{% include rule_list.html ruleType="typescript" %}
+
+### Functionality
+
+_These rules catch common errors in JS programming or otherwise confusing constructs that are prone to producing bugs_:
+
+{% include rule_list.html ruleType="functionality" %}
+
+### Maintainability
+
+_These rules make code maintenance easier_:
+
+{% include rule_list.html ruleType="maintainability" %}
+
+### Style
+
+_These rules enforce consistent style across your codebase_:
+
+{% include rule_list.html ruleType="style" %}

rules/no-invalid-template-strings/index.html

@@ -0,0 +1,13 @@
+---
+ruleName: no-invalid-template-strings
+description: 'Warns on use of `${` in non-template strings.'
+optionsDescription: Not configurable.
+options: null
+optionExamples:
+  - 'true'
+type: functionality
+typescriptOnly: false
+layout: rule
+title: 'Rule: no-invalid-template-strings'
+optionsJSON: 'null'
+---

rules/no-sparse-arrays/index.html

@@ -0,0 +1,14 @@
+---
+ruleName: no-sparse-arrays
+description: Forbids array literals to contain missing elements.
+rationale: Missing elements are probably an accidentally duplicated comma.
+optionsDescription: Not configurable.
+options: null
+optionExamples:
+  - 'true'
+type: functionality
+typescriptOnly: false
+layout: rule
+title: 'Rule: no-sparse-arrays'
+optionsJSON: 'null'
+---

rules/no-unused-variable/index.html

@@ -21,7 +21,6 @@
       - type: string
         enum:
           - check-parameters
-          - react
       - type: object
         properties:
           ignore-pattern:
@@ -30,7 +29,7 @@
   minLength: 0
   maxLength: 3
 optionExamples:
-  - '[true, "react"]'
+  - '[true]'
   - '[true, {"ignore-pattern": "^_"}]'
 type: functionality
 typescriptOnly: true
@@ -44,8 +43,7 @@
         {
           "type": "string",
           "enum": [
-            "check-parameters",
-            "react"
+            "check-parameters"
           ]
         },
         {

rules/no-void-expression/index.html

@@ -1,12 +1,33 @@
 ---
 ruleName: no-void-expression
 description: Requires expressions of type `void` to appear in statement position.
-optionsDescription: Not configurable.
-options: null
+optionsDescription: |-
+
+  If `ignore-arrow-function-shorthand` is provided, `() => returnsVoid()` will be allowed.
+  Otherwise, it must be written as `() => { returnsVoid(); }`.
+options:
+  type: array
+  items:
+    type: string
+    enum:
+      - ignore-arrow-function-shorthand
+  minLength: 0
+  maxLength: 1
 requiresTypeInfo: true
 type: functionality
 typescriptOnly: false
 layout: rule
 title: 'Rule: no-void-expression'
-optionsJSON: 'null'
+optionsJSON: |-
+  {
+    "type": "array",
+    "items": {
+      "type": "string",
+      "enum": [
+        "ignore-arrow-function-shorthand"
+      ]
+    },
+    "minLength": 0,
+    "maxLength": 1
+  }
 ---

rules/strict-boolean-expressions/index.html

@@ -15,8 +15,10 @@
 
   * `allow-null-union` allows union types containing `null`.
     - It does *not* allow `null` itself.
+    - Without the '--strictNullChecks' compiler option, this will allow anything other than a string, number, or enum.
   * `allow-undefined-union` allows union types containing `undefined`.
     - It does *not* allow `undefined` itself.
+    - Without the '--strictNullChecks' compiler option, this will allow anything other than a string, number, or enum.
   * `allow-string` allows strings.
     - It does *not* allow unions containing `string`.
     - It does *not* allow string literal types.