-
Notifications
You must be signed in to change notification settings - Fork 29.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc, tools: use eslint-plugin-markdown #12563
doc, tools: use eslint-plugin-markdown #12563
Conversation
In terms of keeping a clean git commit history, I think it might be better to fix style/syntax in the docs in one commit (without adding directives like |
@not-an-aardvark I've reverted |
@not-an-aardvark I've checked the whole |
doc/api/dns.md
Outdated
@@ -353,15 +353,15 @@ be an object with the following properties: | |||
* `minttl` | |||
|
|||
```js | |||
{ | |||
({ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ESLint parses this as a code block with statements and breaks with parsing errors. With ()
it is parsed as an expression with an object literal.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This doesn't feel right to me... If everybody else is okay with this, then fine.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In some places, I've added something like const defaults = { };
, but it seems to me this does not fit everywhere. Maybe, somebody can think up a better approach.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think readability should be our main concern in the docs. If a code block which isn't technically valid JS communicates more clearly than the valid-JS alternative, then we should keep using invalid JS and put a disable comment above it. In this case, I don't have a strong opinion on whether the parentheses increase readability.
@not-an-aardvark, @thefourtheye
ESLint utput after the second commit:
|
@not-an-aardvark What are the steps for the proceeding? Are these right?
|
Yes, I think those are the right steps. If |
@not-an-aardvark What should I add in build configs so that doc are checked in build and CI? |
We also should ignore |
cc @Trott: I'm not sure about the best place to put |
To add this to the build process, I think you would need to replace these lines with: $(NODE) tools/eslint/bin/eslint.js --cache --rulesdir=tools/eslint-rules --ext=.js,.md \
benchmark lib test tools docs In other words, add To ignore files like |
Dismissing my review for now because a few new commits have been added.
Hopefully, make all |
@not-an-aardvark I'm not sure either. If we were starting from scratch, I'd probably say put everything (including eslint itself) in As is, I'm OK with putting |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice work!
doc/api/cluster.md
Outdated
worker.process.pid, signal || code); | ||
cluster.fork(); | ||
} | ||
); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd prefer the older more concise style, if possible.
doc/api/console.md
Outdated
for (let i = 0; i < 100; i++) { | ||
; | ||
} | ||
for (let i = 0; i < 100; i++) ; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would
for (let i = 0; i < 100; i++) {}
work?
Some people may be unfamiliar with the syntax of an empty statement.
doc/api/crypto.md
Outdated
@@ -288,7 +288,8 @@ decipher.on('end', () => { | |||
// Prints: some clear text data | |||
}); | |||
|
|||
const encrypted = 'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504'; | |||
const encrypted = | |||
'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504'; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
4-space indent, and break the string into multiple lines using +
if needed.
doc/api/fs.md
Outdated
@@ -217,7 +217,7 @@ synchronous counterparts are of this type. | |||
For a regular file [`util.inspect(stats)`][] would return a string very | |||
similar to this: | |||
|
|||
```js | |||
```txt |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You can just remove the language.
doc/api/modules.md
Outdated
@@ -70,7 +70,7 @@ When a file is run directly from Node.js, `require.main` is set to its | |||
directly by testing | |||
|
|||
```js | |||
require.main === module | |||
require.main === module; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I feel in this case the code block should just be inlined, as
... directly by testing
require.main === module
.
doc/api/console.md
Outdated
@@ -139,7 +142,7 @@ the default behavior of `console` in Node.js. | |||
// new impl for assert without monkey-patching. | |||
const myConsole = Object.create(console, { | |||
assert: { | |||
value: function assert(assertion, message, ...args) { | |||
value(assertion, message, ...args) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This will result in myConsole.assert.name === 'value'
, which may not be desirable. I'd add an exclusion for func-name-matching
.
doc/api/process.md
Outdated
@@ -529,7 +528,7 @@ running the `./configure` script. | |||
|
|||
An example of the possible output looks like: | |||
|
|||
```js | |||
```txt |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ditto about txt
language. Or, disabling ESLint for this block and keep js
also works for me.
doc/api/readline.md
Outdated
@@ -414,7 +414,7 @@ For instance: `[[substr1, substr2, ...], originalsubstring]`. | |||
```js | |||
function completer(line) { | |||
const completions = '.help .error .exit .quit .q'.split(' '); | |||
const hits = completions.filter((c) => { return c.indexOf(line) === 0 }); | |||
const hits = completions.filter((c) => { return c.indexOf(line) === 0; }); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can this instead be:
const hits = completions.filter((c) => c.indexOf(line) === 0);
doc/api/zlib.md
Outdated
@@ -149,7 +152,7 @@ From `zlib/zconf.h`, modified to node.js's usage: | |||
The memory requirements for deflate are (in bytes): | |||
|
|||
```js | |||
(1 << (windowBits+2)) + (1 << (memLevel+9)) | |||
(1 << (windowBits + 2)) + (1 << (memLevel + 9)); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The semicolon looks out of place here as well.
doc/api/zlib.md
Outdated
``` | ||
|
||
This will, however, generally degrade compression. | ||
|
||
The memory requirements for inflate are (in bytes) | ||
|
||
```js | ||
1 << windowBits | ||
1 << windowBits; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ditto. This should be short enough to make it inlined.
|
doc/api/stream.md
Outdated
@@ -280,7 +280,7 @@ has been called, and all data has been flushed to the underlying system. | |||
|
|||
```js | |||
const writer = getWritableStreamSomehow(); | |||
for (var i = 0; i < 100; i ++) { | |||
for (var i = 0; i < 100; i++) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You can use let
.
@TimothyGu @abouthiroppy Thank you. Comments hopefully addressed. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM after one last nit.
doc/api/zlib.md
Outdated
```js | ||
1 << windowBits | ||
``` | ||
The memory requirements for inflate are (in bytes) `1 << windowBits`. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This empty line can now be removed.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.
So maybe no need to filter any more files: all Trying to settle build configs... |
LGTM. Great work! Thank you, @vsemozhetbyt 🍻 |
|
Let's start with Linter CI: https://ci.nodejs.org/job/node-test-linter/8451/ |
I think this should bake for another release first, but after the next v6.x release comes out @vsemozhetbyt would you be willing to backport to v6.x? Guide is here. If it shouldn't be landed let me know and we can add the |
In addition, I am not sure if we should wait for eslint/markdown#69 fixed. |
@vsemozhetbyt sounds good, I'll ask again in a month! |
Looks like eslint/markdown#69 is really close to landing. Once it does and you're comfortable with it (I guess we need to pull in the fix too) feel free to raise the backport PR. |
The 2 week wait doesn't normally apply to build tools, and I don't think updating the dependency is a particularly dangerous thing to do, so I'd say raise it now if you'd like. |
This is an initial step to eliminate most of parsing errors. Backport-PR-URL: #14067 PR-URL: #12563 Refs: #12557 (comment) Reviewed-By: Teddy Katz <teddy.katz@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com>
Backport-PR-URL: #14067 PR-URL: #12563 Refs: #12557 (comment) Reviewed-By: Teddy Katz <teddy.katz@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com>
* Install eslint-plugin-markdown@1.0.0-beta.7 * Add doc/.eslintrc.yaml * Add `plugins: [markdown]` to the main .eslintrc.yaml * .js files in doc folder added to .eslintignore * Update Makefile, vcbuild.bat, and tools/jslint.js Refs: #12563 Refs: #12640 Refs: #14047 PR-URL: #14067 Reviewed-By: James Snell <jasnell@gmail.com> Reviewed-By: Myles Borins <myles.borins@gmail.com>
This is an initial step to eliminate most of parsing errors. Backport-PR-URL: #14067 PR-URL: #12563 Refs: #12557 (comment) Reviewed-By: Teddy Katz <teddy.katz@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com>
Backport-PR-URL: #14067 PR-URL: #12563 Refs: #12557 (comment) Reviewed-By: Teddy Katz <teddy.katz@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com>
* Install eslint-plugin-markdown@1.0.0-beta.7 * Add doc/.eslintrc.yaml * Add `plugins: [markdown]` to the main .eslintrc.yaml * .js files in doc folder added to .eslintignore * Update Makefile, vcbuild.bat, and tools/jslint.js Refs: #12563 Refs: #12640 Refs: #14047 PR-URL: #14067 Reviewed-By: James Snell <jasnell@gmail.com> Reviewed-By: Myles Borins <myles.borins@gmail.com>
This is an initial step to eliminate most of parsing errors. Backport-PR-URL: #14067 PR-URL: #12563 Refs: #12557 (comment) Reviewed-By: Teddy Katz <teddy.katz@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com>
Backport-PR-URL: #14067 PR-URL: #12563 Refs: #12557 (comment) Reviewed-By: Teddy Katz <teddy.katz@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com>
* Install eslint-plugin-markdown@1.0.0-beta.7 * Add doc/.eslintrc.yaml * Add `plugins: [markdown]` to the main .eslintrc.yaml * .js files in doc folder added to .eslintignore * Update Makefile, vcbuild.bat, and tools/jslint.js Refs: #12563 Refs: #12640 Refs: #14047 PR-URL: #14067 Reviewed-By: James Snell <jasnell@gmail.com> Reviewed-By: Myles Borins <myles.borins@gmail.com>
Checklist
Affected core subsystem(s)
doc, tools
Refs: #12557 (comment)
Commit 1: an initial step to eliminate parsing errors. Fixing strategies:
const defaults =
orconst options =
wrap in(See doc, tools: use eslint-plugin-markdown #12563 (comment))()
repl.md
:add(see doc, tools: use eslint-plugin-markdown #12563 (comment))<!-- eslint-disable -->
to disable linting + preserve syntax highlighting.``` ```
instead of```js ```
.Commit 2: conform most of the problematic code to the rules.
Code is checked with this
doc/.eslintrc.yaml
(see https://gist.github.com/not-an-aardvark/f3cb021e854414128d197dde8d0f62b2)Commit 3: add eslint-plugin-markdown stuff
npm install eslint-plugin-markdown
.doc/.eslintrc.yaml
; addplugins: [markdown]
to the main.eslintrc.yaml
.<!-- eslint-disable rule -->
or<!-- eslint-disable -->
for the rest problematic code..js
files indoc
folder added to.eslintignore
.Makefile
andvcbuild.bat
.Commit 4: make doc linting a bit more specific (as we do for tests code)
no-var: 2
andprefer-const: 2
indoc/.eslintrc.yaml
.