Docs: improve?

Author: mysticatea

docs/rules/exports-style.md

@@ -42,7 +42,9 @@ This rule has a string option.
 - `"exports"` requires `exports` and disallows `module.exports`.
 - `allowBatchAssign` (default is `false`) allows `module.exports = exports = obj` if this is `true`.
 
-Examples of **incorrect** code for the `"module.exports"` option:
+### module.exports
+
+Examples of :-1: **incorrect** code for the `"module.exports"` option:
 
 ```js
 /*eslint exports-style: ["error", "module.exports"]*/
@@ -51,7 +53,7 @@ exports.foo = 1
 exports.bar = 2
 ```
 
-Examples of **correct** code for the `"module.exports"` option:
+Examples of :+1: **correct** code for the `"module.exports"` option:
 
 ```js
 /*eslint exports-style: ["error", "module.exports"]*/
@@ -64,7 +66,9 @@ module.exports = {
 module.exports.baz = 3
 ```
 
-Examples of **incorrect** code for the `"exports"` option:
+### exports
+
+Examples of :-1: **incorrect** code for the `"exports"` option:
 
 ```js
 /*eslint exports-style: ["error", "exports"]*/
@@ -77,7 +81,7 @@ module.exports = {
 module.exports.baz = 3
 ```
 
-Examples of **correct** code for the `"exports"` option:
+Examples of :+1: **correct** code for the `"exports"` option:
 
 ```js
 /*eslint exports-style: ["error", "exports"]*/
@@ -86,7 +90,9 @@ exports.foo = 1
 exports.bar = 2
 ```
 
-Examples of **correct** code for the `"exports"` and `{"allowBatchAssign": true}` option:
+### allowBatchAssign
+
+Examples of :+1: **correct** code for the `"exports"` and `{"allowBatchAssign": true}` option:
 
 ```js
 /*eslint exports-style: ["error", "exports", {"allowBatchAssign": true}]*/

docs/rules/no-deprecated-api.md

@@ -5,17 +5,17 @@ The community is going to remove those API from Node in future, so we should not
 
 ## Rule Details
 
-The following patterns are considered problems:
+Examples of :-1: **incorrect** code for this rule:
 
 ```js
-/*eslint no-deprecated-api: 2*/
+/*eslint node/no-deprecated-api: "error" */
 
 var fs = require("fs");
 fs.exists("./foo.js", function() {}); /*ERROR: 'fs.exists' was deprecated since v4. Use 'fs.stat()' or 'fs.access()' instead.*/
 
 // Also, it can report the following patterns.
-var exists = require("fs").exists; /*ERROR: 'fs.exists' was deprecated since v4. Use 'fs.stat()' or 'fs.access()' instead.*/
-const {exists} = require("fs"); /*ERROR: 'fs.exists' was deprecated since v4. Use 'fs.stat()' or 'fs.access()' instead.*/
+var exists = require("fs").exists;    /*ERROR: 'fs.exists' was deprecated since v4. Use 'fs.stat()' or 'fs.access()' instead.*/
+const {exists} = require("fs");       /*ERROR: 'fs.exists' was deprecated since v4. Use 'fs.stat()' or 'fs.access()' instead.*/
 
 
 // And other deprecated API below.
@@ -24,7 +24,7 @@ const {exists} = require("fs"); /*ERROR: 'fs.exists' was deprecated since v4. Us
 This rule reports the following deprecated API.
 
 - buffer
-    - [Buffer constructors](https://nodejs.org/dist/v6.0.0/docs/api/buffer.html#buffer_class_buffer)
+    - [Buffer constructors](https://nodejs.org/dist/v6.0.0/docs/api/buffer.html#buffer_class_buffer) (You can use [safe-buffer](https://www.npmjs.com/package/safe-buffer) module for `Node@<6.0.0`)
     - [SlowBuffer class](https://nodejs.org/dist/v6.0.0/docs/api/buffer.html#buffer_class_slowbuffer)
 - crypto
     - [createCredentials](https://nodejs.org/dist/v0.12.0/docs/api/crypto.html#crypto_crypto_createcredentials_details)
@@ -33,7 +33,6 @@ This rule reports the following deprecated API.
     - [EventEmitter.listenerCount](https://nodejs.org/dist/v4.0.0/docs/api/events.html#events_class_method_eventemitter_listenercount_emitter_event)
 - fs
     - [exists](https://nodejs.org/dist/v4.0.0/docs/api/fs.html#fs_fs_exists_path_callback)
-    - [existsSync](https://nodejs.org/dist/v4.0.0/docs/api/fs.html#fs_fs_existssync_path)
 - globals
     - [require.extensions](https://nodejs.org/dist/v0.12.0/docs/api/globals.html#globals_require_extensions)
 - http
@@ -74,7 +73,9 @@ This rule reports the following deprecated API.
 
 ## Known Limitations
 
-### Cannot report non-static properties:
+This rule cannot report the following cases:
+
+### non-static properties
 
 - cluster
     - [worker.suicide](https://nodejs.org/dist/v6.0.0/docs/api/cluster.html#cluster_worker_suicide)
@@ -83,14 +84,14 @@ This rule reports the following deprecated API.
 - net
     - [server.connections](https://nodejs.org/dist/v0.10.0/docs/api/net.html#net_server_connections)
 
-### Cannot report dynamic things:
+### dynamic things
 
 ```js
 require(foo).aDeprecatedProperty;
 require("http")[A_DEPRECATED_PROPERTY]();
 ```
 
-### Cannot understand assignments to properties:
+### assignments
 
 ```js
 var obj = {
@@ -105,22 +106,16 @@ obj.Buffer = require("buffer").Buffer
 new obj.Buffer(); /* missing. */
 ```
 
-### Cannot understand assignments to arguments:
-
 ```js
 (function(Buffer) {
     new Buffer(); /* missing. */
 })(require("buffer").Buffer);
 ```
 
-### Cannot understand reassignments:
+### reassignments
 
 ```js
 var Buffer = require("buffer").Buffer;
 Buffer = require("another-buffer");
 new Buffer(); /*ERROR: 'buffer.Buffer' constructor was deprecated.*/
 ```
-
-## When Not To Use It
-
-If you don't want to be warned on deprecated API, then it's safe to disable this rule.

docs/rules/no-missing-import.md

@@ -2,45 +2,45 @@
 
 This is similar to [no-missing-require](no-missing-require.md), but this rule handles `import` and `export` declarations.
 
-**⚠ NOTE:** ECMAScript 2015 (ES6) does not define the lookup logic and Node does not support modules yet. So this rule spec might be changed in future.
+:warning: ECMAScript "error"015 (ES6) does not define the lookup logic and Node does not support modules yet. So this rule spec might be changed in future.
 
 ## Rule Details
 
 This rule checks the file paths of `import` and `export` declarations.
 If the file paths don't exist, this reports these.
 
-The following patterns are considered problems:
+Examples of :-1: **incorrect** code for this rule:
 
 ```js
-/*eslint node/no-missing-import: 2*/
+/*eslint node/no-missing-import: "error" */
 
-import typoFile from "./typo-file";   /*error "./typo-file" is not found.*/
-import typoModule from "typo-module"; /*error "typo-module" is not found.*/
+import typoFile from "./typo-file";   /*ERROR: "./typo-file" is not found.*/
+import typoModule from "typo-module"; /*ERROR: "typo-module" is not found.*/
 ```
 
-The following patterns are not considered problems:
+Examples of :+1: **correct** code for this rule:
 
 ```js
-/*eslint node/no-missing-import: 2*/
+/*eslint node/no-missing-import: "error" */
 
 import existingFile from "./existing-file";
 import existingModule from "existing-module";
 ```
 
-### Options
+## Options
 
 ```json
 {
     "rules": {
-        "node/no-missing-import": [2, {
+        "node/no-missing-import": ["error", {
             "allowModules": [],
             "tryExtensions": [".js", ".json", ".node"]
         }]
     }
 }
 ```
 
-#### `allowModules`
+### allowModules
 
 Some platforms have additional embedded modules.
 For example, Electron has `electron` module.
@@ -51,21 +51,21 @@ This option is an array of strings as module names.
 ```json
 {
     "rules": {
-        "node/no-missing-import": [2, {
+        "node/no-missing-import": ["error", {
             "allowModules": ["electron"]
         }]
     }
 }
 ```
 
-#### `tryExtensions`
+### tryExtensions
 
 When an import path does not exist, this rule checks whether or not any of `path.js`, `path.json`, and `path.node` exists.
 `tryExtensions` option is the extension list this rule uses at the time.
 
 Default is `[".js", ".json", ".node"]`.
 
-### Shared Settings
+## Shared Settings
 
 The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings).
 Several rules have the same option, but we can set this option at once.
@@ -82,13 +82,7 @@ Several rules have the same option, but we can set this option at once.
         }
     },
     "rules": {
-        "node/no-missing-import": 2
+        "node/no-missing-import": "error"
     }
 }
 ```
-
-## When Not To Use It
-
-This rule should not be used in ES3/5 environments.
-
-If you don't want to be notified about usage of `import` and `export` declarations, then it's safe to disable this rule.

docs/rules/no-missing-require.md

@@ -9,22 +9,21 @@ const foo = require("./foo");
 
 ## Rule Details
 
-This rule checks the file paths of `require()`s.
-If the file paths don't exist, this reports these.
+This rule checks the file paths of `require()`s, then reports the path of files which don't exist.
 
-The following patterns are considered problems:
+Examples of :-1: **incorrect** code for this rule:
 
 ```js
-/*eslint node/no-missing-require: 2*/
+/*eslint node/no-missing-require: "error" */
 
 var typoFile = require("./typo-file");   /*error "./typo-file" is not found.*/
 var typoModule = require("typo-module"); /*error "typo-module" is not found.*/
 ```
 
-The following patterns are not considered problems:
+Examples of :+1: **correct** code for this rule:
 
 ```js
-/*eslint node/no-missing-require: 2*/
+/*eslint node/no-missing-require: "error" */
 
 var existingFile = require("./existing-file");
 var existingModule = require("existing-module");
@@ -33,20 +32,20 @@ var existingModule = require("existing-module");
 var foo = require(FOO_NAME);
 ```
 
-### Options
+## Options
 
 ```json
 {
     "rules": {
-        "node/no-missing-require": [2, {
+        "node/no-missing-require": ["error", {
             "allowModules": [],
             "tryExtensions": [".js", ".json", ".node"]
         }]
     }
 }
 ```
 
-#### `allowModules`
+### allowModules
 
 Some platforms have additional embedded modules.
 For example, Electron has `electron` module.
@@ -57,21 +56,21 @@ This option is an array of strings as module names.
 ```json
 {
     "rules": {
-        "node/no-missing-require": [2, {
+        "node/no-missing-require": ["error", {
             "allowModules": ["electron"]
         }]
     }
 }
 ```
 
-#### `tryExtensions`
+### tryExtensions
 
 When an import path does not exist, this rule checks whether or not any of `path.js`, `path.json`, and `path.node` exists.
 `tryExtensions` option is the extension list this rule uses at the time.
 
 Default is `[".js", ".json", ".node"]`.
 
-### Shared Settings
+## Shared Settings
 
 The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings).
 Several rules have the same option, but we can set this option at once.
@@ -88,11 +87,7 @@ Several rules have the same option, but we can set this option at once.
         }
     },
     "rules": {
-        "node/no-missing-require": 2
+        "node/no-missing-require": "error"
     }
 }
 ```
-
-## When Not To Use It
-
-If you don't want to be notified about usage of `require()`, then it's safe to disable this rule.

docs/rules/no-unpublished-bin.md

@@ -30,7 +30,7 @@ If `npm` ignores the files in `bin` field, this rule warns the files.
 }
 ```
 
-### `convertPath`
+### convertPath
 
 If we use transpilers (e.g. Babel), perhaps the file path to a source code is never published.
 `convertPath` option tells to the rule, it needs to convert file paths.