Skip to content

Commit

Permalink
docs: cleanup docs, add markdownlint, tweak eslint-doc-generator opti…
Browse files Browse the repository at this point in the history
…ons (#64)
  • Loading branch information
@bmish
bmish committed Nov 10, 2022
1 parent 54c5e52 commit bdfd61a
Show file tree
Hide file tree
Showing 36 changed files with 150 additions and 138 deletions.
9 changes: 9 additions & 0 deletions .markdownlint.json
View file
@@ -0,0 +1,9 @@
{
"line-length": false,
"no-inline-html": {
"allowed_elements": ["details"]
},
"ul-style": {
"style": "dash"
}
}
3 changes: 3 additions & 0 deletions .markdownlintignore
View file
@@ -0,0 +1,3 @@
CHANGELOG.md
LICENSE
node_modules
66 changes: 33 additions & 33 deletions README.md
View file
Expand Up @@ -57,43 +57,41 @@ npm install --save-dev eslint eslint-plugin-n

<!-- begin auto-generated rules list -->

💼 Configurations enabled in.\
✅ Set in the `recommended` configuration.\
☑️ Set in the `recommended-module` configuration.\
✔️ Set in the `recommended-script` configuration.\
💼 [Configurations](https://github.com/eslint-community/eslint-plugin-n#-configs) enabled in.\
✅ Set in the `recommended` [configuration](https://github.com/eslint-community/eslint-plugin-n#-configs).\
🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\
❌ Deprecated.

### Best Practices

| Name | Description | 💼 | 🔧 | ❌ |
| :--------------------------------------------------- | :----------------------- | :------ | :- | :- |
| [no-deprecated-api](docs/rules/no-deprecated-api.md) | disallow deprecated APIs | ✅ ☑️ ✔️ | | |
| Name | Description | 💼 | 🔧 | ❌ |
| :--------------------------------------------------- | :----------------------- | :- | :- | :- |
| [no-deprecated-api](docs/rules/no-deprecated-api.md) | disallow deprecated APIs | ✅ | | |

### Possible Errors

| Name                                  | Description | 💼 | 🔧 | ❌ |
| :------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | :------ | :- | :- |
| [handle-callback-err](docs/rules/handle-callback-err.md) | require error handling in callbacks | | | |
| [no-callback-literal](docs/rules/no-callback-literal.md) | enforce Node.js-style error-first callback pattern is followed | | | |
| [no-exports-assign](docs/rules/no-exports-assign.md) | disallow the assignment to `exports` | ✅ ☑️ ✔️ | | |
| [no-extraneous-import](docs/rules/no-extraneous-import.md) | disallow `import` declarations which import extraneous modules | ✅ ☑️ ✔️ | | |
| [no-extraneous-require](docs/rules/no-extraneous-require.md) | disallow `require()` expressions which import extraneous modules | ✅ ☑️ ✔️ | | |
| [no-hide-core-modules](docs/rules/no-hide-core-modules.md) | disallow third-party modules which are hiding core modules | | | ❌ |
| [no-missing-import](docs/rules/no-missing-import.md) | disallow `import` declarations which import non-existence modules | ✅ ☑️ ✔️ | | |
| [no-missing-require](docs/rules/no-missing-require.md) | disallow `require()` expressions which import non-existence modules | ✅ ☑️ ✔️ | | |
| [no-new-require](docs/rules/no-new-require.md) | disallow `new` operators with calls to `require` | | | |
| [no-path-concat](docs/rules/no-path-concat.md) | disallow string concatenation with `__dirname` and `__filename` | | | |
| [no-process-exit](docs/rules/no-process-exit.md) | disallow the use of `process.exit()` | ✅ ☑️ ✔️ | | |
| [no-unpublished-bin](docs/rules/no-unpublished-bin.md) | disallow `bin` files that npm ignores | ✅ ☑️ ✔️ | | |
| [no-unpublished-import](docs/rules/no-unpublished-import.md) | disallow `import` declarations which import private modules | ✅ ☑️ ✔️ | | |
| [no-unpublished-require](docs/rules/no-unpublished-require.md) | disallow `require()` expressions which import private modules | ✅ ☑️ ✔️ | | |
| [no-unsupported-features](docs/rules/no-unsupported-features.md) | disallow unsupported ECMAScript features on the specified version | | | ❌ |
| [no-unsupported-features/es-builtins](docs/rules/no-unsupported-features/es-builtins.md) | disallow unsupported ECMAScript built-ins on the specified version | ✅ ☑️ ✔️ | | |
| [no-unsupported-features/es-syntax](docs/rules/no-unsupported-features/es-syntax.md) | disallow unsupported ECMAScript syntax on the specified version | ✅ ☑️ ✔️ | | |
| [no-unsupported-features/node-builtins](docs/rules/no-unsupported-features/node-builtins.md) | disallow unsupported Node.js built-in APIs on the specified version | ✅ ☑️ ✔️ | | |
| [process-exit-as-throw](docs/rules/process-exit-as-throw.md) | require that `process.exit()` expressions use the same code path as `throw` | ✅ ☑️ ✔️ | | |
| [shebang](docs/rules/shebang.md) | require correct usage of shebang | ✅ ☑️ ✔️ | 🔧 | |
| Name                                  | Description | 💼 | 🔧 | ❌ |
| :------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | :- | :- | :- |
| [handle-callback-err](docs/rules/handle-callback-err.md) | require error handling in callbacks | | | |
| [no-callback-literal](docs/rules/no-callback-literal.md) | enforce Node.js-style error-first callback pattern is followed | | | |
| [no-exports-assign](docs/rules/no-exports-assign.md) | disallow the assignment to `exports` | ✅ | | |
| [no-extraneous-import](docs/rules/no-extraneous-import.md) | disallow `import` declarations which import extraneous modules | ✅ | | |
| [no-extraneous-require](docs/rules/no-extraneous-require.md) | disallow `require()` expressions which import extraneous modules | ✅ | | |
| [no-hide-core-modules](docs/rules/no-hide-core-modules.md) | disallow third-party modules which are hiding core modules | | | ❌ |
| [no-missing-import](docs/rules/no-missing-import.md) | disallow `import` declarations which import non-existence modules | ✅ | | |
| [no-missing-require](docs/rules/no-missing-require.md) | disallow `require()` expressions which import non-existence modules | ✅ | | |
| [no-new-require](docs/rules/no-new-require.md) | disallow `new` operators with calls to `require` | | | |
| [no-path-concat](docs/rules/no-path-concat.md) | disallow string concatenation with `__dirname` and `__filename` | | | |
| [no-process-exit](docs/rules/no-process-exit.md) | disallow the use of `process.exit()` | ✅ | | |
| [no-unpublished-bin](docs/rules/no-unpublished-bin.md) | disallow `bin` files that npm ignores | ✅ | | |
| [no-unpublished-import](docs/rules/no-unpublished-import.md) | disallow `import` declarations which import private modules | ✅ | | |
| [no-unpublished-require](docs/rules/no-unpublished-require.md) | disallow `require()` expressions which import private modules | ✅ | | |
| [no-unsupported-features](docs/rules/no-unsupported-features.md) | disallow unsupported ECMAScript features on the specified version | | | ❌ |
| [no-unsupported-features/es-builtins](docs/rules/no-unsupported-features/es-builtins.md) | disallow unsupported ECMAScript built-ins on the specified version | ✅ | | |
| [no-unsupported-features/es-syntax](docs/rules/no-unsupported-features/es-syntax.md) | disallow unsupported ECMAScript syntax on the specified version | ✅ | | |
| [no-unsupported-features/node-builtins](docs/rules/no-unsupported-features/node-builtins.md) | disallow unsupported Node.js built-in APIs on the specified version | ✅ | | |
| [process-exit-as-throw](docs/rules/process-exit-as-throw.md) | require that `process.exit()` expressions use the same code path as `throw` | ✅ | | |
| [shebang](docs/rules/shebang.md) | require correct usage of shebang | ✅ | 🔧 | |

### Stylistic Issues

Expand Down Expand Up @@ -124,11 +122,13 @@ npm install --save-dev eslint eslint-plugin-n

This plugin provides three configs:

- `plugin:n/recommended` considers both CommonJS and ES Modules. If [`"type":"module"` field](https://medium.com/@nodejs/announcing-a-new-experimental-modules-1be8d2d6c2ff#b023) existed in package.json then it considers files as ES Modules. Otherwise it considers files as CommonJS. In addition, it considers `*.mjs` files as ES Modules and `*.cjs` files as CommonJS.
- `plugin:n/recommended-module` considers all files as ES Modules.
- `plugin:n/recommended-script` considers all files as CommonJS.
| Name | Description |
| :-- | :-- |
| `plugin:n/recommended` | Considers both CommonJS and ES Modules. If [`"type":"module"` field](https://medium.com/@nodejs/announcing-a-new-experimental-modules-1be8d2d6c2ff#b023) existed in package.json then it considers files as ES Modules. Otherwise it considers files as CommonJS. In addition, it considers `*.mjs` files as ES Modules and `*.cjs` files as CommonJS. |
| `plugin:n/recommended-module` | Considers all files as ES Modules. |
| `plugin:n/recommended-script` | Considers all files as CommonJS. |

Those preset config:
These preset configs:

- enable [no-process-exit](http://eslint.org/docs/rules/no-process-exit) rule because [the official document](https://nodejs.org/api/process.html#process_process_exit_code) does not recommend a use of `process.exit()`.
- enable plugin rules which are given ✅ in the above table.
Expand Down
4 changes: 2 additions & 2 deletions docs/rules/callback-return.md
View file
Expand Up @@ -102,8 +102,8 @@ function bar(err, send) {

Because it is difficult to understand the meaning of a program through static analysis, this rule has limitations:

* *false negatives* when this rule reports correct code, but the program calls the callback more than one time (which is incorrect behavior)
* *false positives* when this rule reports incorrect code, but the program calls the callback only one time (which is correct behavior)
- *false negatives* when this rule reports correct code, but the program calls the callback more than one time (which is incorrect behavior)
- *false positives* when this rule reports incorrect code, but the program calls the callback only one time (which is correct behavior)

#### Passing the callback by reference

Expand Down
12 changes: 6 additions & 6 deletions docs/rules/exports-style.md
View file
Expand Up @@ -21,7 +21,7 @@ In this case, `exports.bar` will be lost since only the instance of `module.expo

This rule enforces the export style.

If you use `module.exports`, this rule disallows `exports`.<br>
If you use `module.exports`, this rule disallows `exports`.\
If you use `exports`, this rule disallows `module.exports`.

You can select it by an option.
Expand All @@ -48,7 +48,7 @@ This rule has a string option.

#### module.exports

Examples of :-1: **incorrect** code for the `"module.exports"` option:
Examples of 👎 **incorrect** code for the `"module.exports"` option:

```js
/*eslint n/exports-style: ["error", "module.exports"]*/
Expand All @@ -57,7 +57,7 @@ exports.foo = 1
exports.bar = 2
```

Examples of :+1: **correct** code for the `"module.exports"` option:
Examples of 👍 **correct** code for the `"module.exports"` option:

```js
/*eslint n/exports-style: ["error", "module.exports"]*/
Expand All @@ -72,7 +72,7 @@ module.exports.baz = 3

#### exports

Examples of :-1: **incorrect** code for the `"exports"` option:
Examples of 👎 **incorrect** code for the `"exports"` option:

```js
/*eslint n/exports-style: ["error", "exports"]*/
Expand All @@ -85,7 +85,7 @@ module.exports = {
module.exports.baz = 3
```

Examples of :+1: **correct** code for the `"exports"` option:
Examples of 👍 **correct** code for the `"exports"` option:

```js
/*eslint n/exports-style: ["error", "exports"]*/
Expand All @@ -96,7 +96,7 @@ exports.bar = 2

#### allowBatchAssign

Examples of :+1: **correct** code for the `"exports"` and `{"allowBatchAssign": true}` option:
Examples of 👍 **correct** code for the `"exports"` and `{"allowBatchAssign": true}` option:

```js
/*eslint n/exports-style: ["error", "exports", {"allowBatchAssign": true}]*/
Expand Down
10 changes: 5 additions & 5 deletions docs/rules/file-extension-in-import.md
View file
Expand Up @@ -41,15 +41,15 @@ This rule has a string option and an object option.

#### always

Examples of :-1: **incorrect** code for the `"always"` option:
Examples of 👎 **incorrect** code for the `"always"` option:

```js
/*eslint n/file-extension-in-import: ["error", "always"]*/

import foo from "./path/to/a/file"
```

Examples of :+1: **correct** code for the `"always"` option:
Examples of 👍 **correct** code for the `"always"` option:

```js
/*eslint n/file-extension-in-import: ["error", "always"]*/
Expand All @@ -60,15 +60,15 @@ import foo from "./path/to/a/file.js"

#### never

Examples of :-1: **incorrect** code for the `"never"` option:
Examples of 👎 **incorrect** code for the `"never"` option:

```js
/*eslint n/file-extension-in-import: ["error", "never"]*/

import foo from "./path/to/a/file.js"
```

Examples of :+1: **correct** code for the `"never"` option:
Examples of 👍 **correct** code for the `"never"` option:

```js
/*eslint n/file-extension-in-import: ["error", "never"]*/
Expand All @@ -79,7 +79,7 @@ import foo from "./path/to/a/file"

#### .xxx

Examples of :+1: **correct** code for the `["always", { ".js": "never" }]` option:
Examples of 👍 **correct** code for the `["always", { ".js": "never" }]` option:

```js
/*eslint n/file-extension-in-import: ["error", "always", { ".js": "never" }]*/
Expand Down
6 changes: 3 additions & 3 deletions docs/rules/handle-callback-err.md
View file
Expand Up @@ -68,9 +68,9 @@ so you need a more flexible configuration to ensure that the rule reports all un

If the configured name of the error variable begins with a `^` it is considered to be a regexp pattern.

* If the option is `"^(err|error|anySpecificError)$"`, the rule reports unhandled errors where the parameter name can be `err`, `error` or `anySpecificError`.
* If the option is `"^.+Error$"`, the rule reports unhandled errors where the parameter name ends with `Error` (for example, `connectionError` or `validationError` will match).
* If the option is `"^.*(e|E)rr"`, the rule reports unhandled errors where the parameter name matches any string that contains `err` or `Err` (for example, `err`, `error`, `anyError`, `some_err` will match).
- If the option is `"^(err|error|anySpecificError)$"`, the rule reports unhandled errors where the parameter name can be `err`, `error` or `anySpecificError`.
- If the option is `"^.+Error$"`, the rule reports unhandled errors where the parameter name ends with `Error` (for example, `connectionError` or `validationError` will match).
- If the option is `"^.*(e|E)rr"`, the rule reports unhandled errors where the parameter name matches any string that contains `err` or `Err` (for example, `err`, `error`, `anyError`, `some_err` will match).

## 🔎 Implementation

Expand Down
4 changes: 2 additions & 2 deletions docs/rules/no-callback-literal.md
View file
Expand Up @@ -8,7 +8,7 @@ When invoking a callback function which uses the Node.js error-first callback pa

When a function is named `cb` or `callback`, then it must be invoked with a first argument that is `undefined`, `null`, an `Error` class, or a subclass or `Error`.

Examples of :-1: **incorrect** code for this rule:
Examples of 👎 **incorrect** code for this rule:

```js
/*eslint n/no-callback-literal: "error" */
Expand All @@ -18,7 +18,7 @@ cb({ a: 1 });
callback(0);
```

Examples of :+1: **correct** code for this rule:
Examples of 👍 **correct** code for this rule:

```js
/*eslint n/no-callback-literal: "error" */
Expand Down
8 changes: 4 additions & 4 deletions docs/rules/no-deprecated-api.md
View file
@@ -1,6 +1,6 @@
# Disallow deprecated APIs (`n/no-deprecated-api`)

💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/eslint-community/eslint-plugin-n#-configs).

<!-- end auto-generated rule header -->

Expand All @@ -9,7 +9,7 @@ The community is going to remove those API from Node in future, so we should not

## 📖 Rule Details

Examples of :-1: **incorrect** code for this rule:
Examples of 👎 **incorrect** code for this rule:

```js
/*eslint n/no-deprecated-api: "error" */
Expand Down Expand Up @@ -272,7 +272,7 @@ This option can include the following values:
- `util._extend`
- `vm.runInDebugContext`

Examples of :+1: **correct** code for the `{"ignoreModuleItems": ["new buffer.Buffer()"]}`:
Examples of 👍 **correct** code for the `{"ignoreModuleItems": ["new buffer.Buffer()"]}`:

```js
/*eslint n/no-deprecated-api: [error, {ignoreModuleItems: ["new buffer.Buffer()"]}] */
Expand Down Expand Up @@ -304,7 +304,7 @@ This option can include the following values:
- `process.binding`
- `process.env.NODE_REPL_HISTORY_FILE`

Examples of :+1: **correct** code for the `{"ignoreGlobalItems": ["new Buffer()"]}`:
Examples of 👍 **correct** code for the `{"ignoreGlobalItems": ["new Buffer()"]}`:

```js
/*eslint n/no-deprecated-api: [error, {ignoreGlobalItems: ["new Buffer()"]}] */
Expand Down
2 changes: 1 addition & 1 deletion docs/rules/no-exports-assign.md
View file
@@ -1,6 +1,6 @@
# Disallow the assignment to `exports` (`n/no-exports-assign`)

💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/eslint-community/eslint-plugin-n#-configs).

<!-- end auto-generated rule header -->

Expand Down
2 changes: 1 addition & 1 deletion docs/rules/no-extraneous-import.md
View file
@@ -1,6 +1,6 @@
# Disallow `import` declarations which import extraneous modules (`n/no-extraneous-import`)

💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/eslint-community/eslint-plugin-n#-configs).

<!-- end auto-generated rule header -->

Expand Down
2 changes: 1 addition & 1 deletion docs/rules/no-extraneous-require.md
View file
@@ -1,6 +1,6 @@
# Disallow `require()` expressions which import extraneous modules (`n/no-extraneous-require`)

💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/eslint-community/eslint-plugin-n#-configs).

<!-- end auto-generated rule header -->

Expand Down

0 comments on commit bdfd61a

Please sign in to comment.