Update Configuration Documentation (#4258)

- Add section on array syntax
- Mark boolean syntax as legacy

docs/usage/configuration/index.md

@@ -11,29 +11,31 @@ configure which rules get run and each of their options.
 
 `tslint.json` or `tslint.yaml` files can have the following fields specified:
 
-* `extends?: string | string[]`:
-The name of a built-in configuration preset (see built-in presets below), or a path or
-array of paths to other configuration files which are extended by this configuration.
-This value is handled using node module resolution semantics.
-For example, a value of `"tslint-config"` would tell TSLint to try and load the main file of a module
-named "tslint-config" as a configuration file. Specific files inside node modules can also be
-specified, eg. `"tslint-config/path/to/submodule"`. Relative paths to JSON files or JS modules
-are also supported, e.g. `"./tslint-config"`.
-* `rulesDirectory?: string | string[]`:
-A path to a directory or an array of paths to directories of [custom rules][2]. These values are handled using node module resolution semantics, if an `index.js` is placed in your rules directory. We fallback to use relative or absolute paths, if the module can't be resolved. If you want to avoid module resolution you can directly use a relative or absolute path (e.g. with `./`).
-* `rules?: { [name: string]: RuleSetting }`: A map of rule names to their configuration settings.
-  - These rules are applied to `.ts` and `.tsx` files.
-  - Each rule is associated with an object containing:
-    - `options?: any`: An array of values that are specific to a rule.
-    - `severity?: "default" | "error" | "warning" | "off"`: Severity level. Level "error" will cause exit code 2.
-  - A boolean value may be specified instead of the above object, and is equivalent to setting no options with default severity.
-  - Any rules specified in this block will override those configured in any base configuration being extended.
-  - [Check out the full rules list here][3].
-* `jsRules?: any | boolean`: Same format as `rules` or explicit `true` to copy all valid active rules from rules. These rules are applied to `.js` and `.jsx` files.
-* `defaultSeverity?: "error" | "warning" | "off"`: The severity level that is applied to rules in this config file as well as rules in any inherited config files which have their severity set to "default". If undefined, "error" is used as the defaultSeverity.
-* `linterOptions?: { exclude?: string[] }`:
-  - `exclude: string[]`: An array of globs. Any file matching these globs will not be linted. All exclude patterns are relative to the configuration file they were specified in.
-  - `format: string`: Default [lint formatter][4]
+-   `extends?: string | string[]`:
+    The name of a built-in configuration preset (see built-in presets below), or a path or
+    array of paths to other configuration files which are extended by this configuration.
+    This value is handled using node module resolution semantics.
+    For example, a value of `"tslint-config"` would tell TSLint to try and load the main file of a module
+    named "tslint-config" as a configuration file. Specific files inside node modules can also be
+    specified, eg. `"tslint-config/path/to/submodule"`. Relative paths to JSON files or JS modules
+    are also supported, e.g. `"./tslint-config"`.
+-   `rulesDirectory?: string | string[]`:
+    A path to a directory or an array of paths to directories of [custom rules][2]. These values are handled using node module resolution semantics, if an `index.js` is placed in your rules directory. We fallback to use relative or absolute paths, if the module can't be resolved. If you want to avoid module resolution you can directly use a relative or absolute path (e.g. with `./`).
+-   `rules?: { [name: string]: RuleSetting }`: A map of rule names to their configuration settings.
+    -   These rules are applied to `.ts` and `.tsx` files.
+    -   Each rule is associated with an object containing:
+        -   `options?: any`: An array of values that are specific to a rule.
+        -   `severity?: "default" | "error" | "warning" | "off"`: Severity level. Level "error" will cause exit code 2.
+    -   Legacy: An array may be specified instead of the above object, and is equivalent to setting the rule with the default severity if the first value in the array is `true`, with configuration parameters in the remainder of the array.
+        -   `"no-empty": [true, "allow-empty-catch"]` is strictly equivalent to `"no-empty": { "options": ['allow-empty-catch'], "severity": 'default' }`
+    -   Legacy: A boolean value may be specified instead of the above object, and is equivalent to setting no options with default severity.
+    -   Any rules specified in this block will override those configured in any base configuration being extended.
+    -   [Check out the full rules list here][3].
+-   `jsRules?: any | boolean`: Same format as `rules` or explicit `true` to copy all valid active rules from rules. These rules are applied to `.js` and `.jsx` files.
+-   `defaultSeverity?: "error" | "warning" | "off"`: The severity level that is applied to rules in this config file as well as rules in any inherited config files which have their severity set to "default". If undefined, "error" is used as the defaultSeverity.
+-   `linterOptions?: { exclude?: string[] }`:
+    -   `exclude: string[]`: An array of globs. Any file matching these globs will not be linted. All exclude patterns are relative to the configuration file they were specified in.
+    -   `format: string`: Default [lint formatter][4]
 
 `tslint.json` configuration files may have JavaScript-style `// single-line` and `/* multi-line */` comments in them (even though this is technically invalid JSON). If this confuses your syntax highlighter, you may want to switch it to JavaScript format.
 
@@ -54,14 +56,7 @@ An example `tslint.json` file might look like this:
         "no-consecutive-blank-lines": false,
         "no-console": {
             "severity": "warning",
-            "options": [
-                "debug",
-                "info",
-                "log",
-                "time",
-                "timeEnd",
-                "trace"
-            ]
+            "options": ["debug", "info", "log", "time", "timeEnd", "trace"]
         }
     },
     "jsRules": {
@@ -111,11 +106,11 @@ The severity level of each rule can be configured to `default`, `error`, `warnin
 
 TSLint ships with a handful of built-in configurations presets. You may inspect their source [here](https://github.com/palantir/tslint/tree/master/src/configs).
 
-__`tslint:recommended`__ is a stable, somewhat opinionated set of rules which we encourage for general TypeScript programming. This configuration follows semver, so it will _not_ have breaking changes across minor or patch releases.
+**`tslint:recommended`** is a stable, somewhat opinionated set of rules which we encourage for general TypeScript programming. This configuration follows semver, so it will _not_ have breaking changes across minor or patch releases.
 
-__`tslint:latest`__ extends `tslint:recommended` and is continuously updated to include configuration for the latest rules in every TSLint release. Using this config may introduce breaking changes across minor releases as new rules are enabled which cause lint failures in your code. When TSLint reaches a major version bump, `tslint:recommended` will be updated to be identical to `tslint:latest`.
+**`tslint:latest`** extends `tslint:recommended` and is continuously updated to include configuration for the latest rules in every TSLint release. Using this config may introduce breaking changes across minor releases as new rules are enabled which cause lint failures in your code. When TSLint reaches a major version bump, `tslint:recommended` will be updated to be identical to `tslint:latest`.
 
-__`tslint:all`__ turns on all rules to their strictest settings. This will use type checking, so it must be combined with the `--project` option.
+**`tslint:all`** turns on all rules to their strictest settings. This will use type checking, so it must be combined with the `--project` option.
 (Exceptions include rules such as [`"ban"`][rule-ban], [`"import-blacklist"`][rule-import-blacklist], and [`"file-header"`][rule-file-header], which have no sensible defaults, and deprecated rules.)
 
 ### Custom rules