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: make the style of notes consistent #13133

Closed
wants to merge 3 commits into
base: master
from

Conversation

@aqrln
Member

aqrln commented May 20, 2017

Make the style of "Note:" paragraphs consistent and document the guidelines in doc/STYLE_GUIDE.md.

Fixes: #13131

I picked the style that I find reasonable and which I had used once adding a note myself, but I don't have any strong opinions about the notes style except that it should be only one, so the formatting may be discussed in this PR.

Checklist
Affected core subsystem(s)

doc

@@ -115,7 +115,7 @@ if (cluster.isMaster) {
d.on('error', (er) => {
console.error(`error ${er.stack}`);
// Note: we're in dangerous territory!
// Note: We're in dangerous territory!

This comment has been minimized.

@aqrln

aqrln May 20, 2017

Member

Note: that falls outside the scope of this PR, but "we" shouldn't have been used here at all. I'll reword all of the comments in this example in another PR.

@aqrln

aqrln May 20, 2017

Member

Note: that falls outside the scope of this PR, but "we" shouldn't have been used here at all. I'll reword all of the comments in this example in another PR.

Show outdated Hide outdated doc/api/events.md
@@ -142,7 +142,7 @@ myEmitter.emit('error', new Error('whoops!'));
To guard against crashing the Node.js process, a listener can be registered
on the [`process` object's `uncaughtException` event][] or the [`domain`][] module
can be used. (_Note, however, that the `domain` module has been deprecated_)
can be used. _(Note, however, that the `domain` module has been deprecated.)_

This comment has been minimized.

@aqrln

aqrln May 20, 2017

Member

And what about this case, to my perception, this is not a note as in "Note:", but rather just a regular sentence. I fixed the stylistic mistakes while I was here, though.

@aqrln

aqrln May 20, 2017

Member

And what about this case, to my perception, this is not a note as in "Note:", but rather just a regular sentence. I fixed the stylistic mistakes while I was here, though.

This comment has been minimized.

@refack

refack May 20, 2017

Member

Agreed. AFAICT this is an editorial comment that happens to start with the word "note".
But it should be "Note however," no first comma.

@refack

refack May 20, 2017

Member

Agreed. AFAICT this is an editorial comment that happens to start with the word "note".
But it should be "Note however," no first comma.

This comment has been minimized.

@aqrln

aqrln May 20, 2017

Member

I am not a native speaker, but as for me, the punctuation around "however" is pretty valid here as is.

@aqrln

aqrln May 20, 2017

Member

I am not a native speaker, but as for me, the punctuation around "however" is pretty valid here as is.

This comment has been minimized.

@Trott

Trott May 20, 2017

Member

I agree that Note, however, that... is perfectly fine (and to my sense, preferable). I do think that note should probably _not* be italicized, though.

@Trott

Trott May 20, 2017

Member

I agree that Note, however, that... is perfectly fine (and to my sense, preferable). I do think that note should probably _not* be italicized, though.

This comment has been minimized.

@refack

refack May 20, 2017

Member

Ack.

@refack
@refack

refack approved these changes May 20, 2017

@refack

refack approved these changes May 20, 2017

LGTM.
Rubber stamp completeness...

Show outdated Hide outdated doc/STYLE_GUIDE.md
@@ -58,6 +58,11 @@
* References to constructor functions should use PascalCase
* References to constructor instances should be camelCased
* References to methods should be used with parentheses: `socket.end()` instead of `socket.end`
* In order to make a note that a reader should draw special attention to,

This comment has been minimized.

@Trott

Trott May 20, 2017

Member

I think this would be somewhat better as To draw special attention to a note,

@Trott

Trott May 20, 2017

Member

I think this would be somewhat better as To draw special attention to a note,

This comment has been minimized.

@aqrln

aqrln May 20, 2017

Member

Done, thanks.

@aqrln

aqrln May 20, 2017

Member

Done, thanks.

@lpinca

lpinca approved these changes May 21, 2017

Show outdated Hide outdated doc/api/net.md
* All [`net.Socket`][] are set to `SO_REUSEADDR` (See [socket(7)][] for

This comment has been minimized.

@lpinca

lpinca May 21, 2017

Member

Nit: I understand this goes against the style defined above but isn't it better to keep the bulleted list here instead of repeating Note: in two consecutive lines?

@lpinca

lpinca May 21, 2017

Member

Nit: I understand this goes against the style defined above but isn't it better to keep the bulleted list here instead of repeating Note: in two consecutive lines?

Show outdated Hide outdated doc/api/tls.md
generated from `process.argv`, other APIs that create secure contexts
have no default value.
**Note:** [`tls.createServer()`][] sets the default value of the

This comment has been minimized.

@lpinca

lpinca May 21, 2017

Member

Nit: it might makes sense to also use a bulleted list here.

@lpinca

lpinca May 21, 2017

Member

Nit: it might makes sense to also use a bulleted list here.

@aqrln

This comment has been minimized.

Show comment
Hide comment
@aqrln

aqrln May 22, 2017

Member

ping @nodejs/collaborators

Before we really start enforcing it, I think we need to make sure that others are acknowledged about this and I'd like to hear more opinions about the preferred style, specifically re: questions like bold vs italic, should we group consequent notes into unordered lists, etc.

Member

aqrln commented May 22, 2017

ping @nodejs/collaborators

Before we really start enforcing it, I think we need to make sure that others are acknowledged about this and I'd like to hear more opinions about the preferred style, specifically re: questions like bold vs italic, should we group consequent notes into unordered lists, etc.

@refack

This comment has been minimized.

Show comment
Hide comment
@refack

refack May 22, 2017

Member

Just a few refs that use **Note:**

Member

refack commented May 22, 2017

Just a few refs that use **Note:**

@watilde

This comment has been minimized.

Show comment
Hide comment
@watilde

watilde May 22, 2017

Member

+1 on this, and it would be nicer if we could have this addition as one of the actual link rules.

Member

watilde commented May 22, 2017

+1 on this, and it would be nicer if we could have this addition as one of the actual link rules.

Show outdated Hide outdated doc/STYLE_GUIDE.md
@@ -58,6 +58,10 @@
* References to constructor functions should use PascalCase
* References to constructor instances should be camelCased
* References to methods should be used with parentheses: `socket.end()` instead of `socket.end`
* To draw special attention to a note, adhere to the following guidelines:

This comment has been minimized.

@jasnell

jasnell May 22, 2017

Member

To be quite honest, I generally prefer the *Note*: style and have been incrementally working towards that for quite some time. I guess this is fine tho. Mildly -0

@jasnell

jasnell May 22, 2017

Member

To be quite honest, I generally prefer the *Note*: style and have been incrementally working towards that for quite some time. I guess this is fine tho. Mildly -0

This comment has been minimized.

@aqrln

aqrln May 22, 2017

Member

As I said,

I don't have any strong opinions about the notes style except that it should be only one, so the formatting may be discussed in this PR.

I am completely fine with changing the style to what you prefer, a Vim macro will chew it easily 😄

@aqrln

aqrln May 22, 2017

Member

As I said,

I don't have any strong opinions about the notes style except that it should be only one, so the formatting may be discussed in this PR.

I am completely fine with changing the style to what you prefer, a Vim macro will chew it easily 😄

@aqrln

This comment has been minimized.

Show comment
Hide comment
@aqrln

aqrln May 22, 2017

Member

@watilde yeah, I am really looking forward to see the markdown linter landed. Sure, we can make a rule for that. Aside from this PR, ensuring that we use 80-character wrapping (except changelogs) and em-dashes are on my to-do list.

Member

aqrln commented May 22, 2017

@watilde yeah, I am really looking forward to see the markdown linter landed. Sure, we can make a rule for that. Aside from this PR, ensuring that we use 80-character wrapping (except changelogs) and em-dashes are on my to-do list.

@mhdawson

LGTM

aqrln added some commits May 20, 2017

doc: make the style of notes consistent
Make the style of "Note:" paragraphs consistent and document the
guidelines in `doc/STYLE_GUIDE.md`.

Fixes: #13131
@aqrln

This comment has been minimized.

Show comment
Hide comment
@aqrln

aqrln May 24, 2017

Member

I've updated the PR. The first commit is the original commit rebased onto master with conflicts resolved and with a couple of notes that I missed before (or that weren't present before the rebase, idk) updated to conform to the general style. The second commit changes the style to what @jasnell prefers and the third commit follows the suggestion by @lpinca to use bulleted lists for consecutive notes.

@refack @lpinca @watilde @mhdawson can you please take another look and say whether this still LGTY? Thanks!

Member

aqrln commented May 24, 2017

I've updated the PR. The first commit is the original commit rebased onto master with conflicts resolved and with a couple of notes that I missed before (or that weren't present before the rebase, idk) updated to conform to the general style. The second commit changes the style to what @jasnell prefers and the third commit follows the suggestion by @lpinca to use bulleted lists for consecutive notes.

@refack @lpinca @watilde @mhdawson can you please take another look and say whether this still LGTY? Thanks!

@refack

This comment has been minimized.

Show comment
Hide comment
@refack

refack May 24, 2017

Member

-0.5 on *Note*:
+1 on **Note:**

Waiting for consensus on bullet lists for https://github.com/nodejs/node/pull/13173/files#diff-acabf706a8aa070a8796e3573f7e4678

Member

refack commented May 24, 2017

-0.5 on *Note*:
+1 on **Note:**

Waiting for consensus on bullet lists for https://github.com/nodejs/node/pull/13173/files#diff-acabf706a8aa070a8796e3573f7e4678

@refack refack referenced this pull request May 24, 2017

Merged

fs: expose Stats times as Numbers #13173

4 of 4 tasks complete
@sam-github

Nice, thanks.

@lpinca

This comment has been minimized.

Show comment
Hide comment
@lpinca

lpinca May 24, 2017

Member

Still LGTM.

Member

lpinca commented May 24, 2017

Still LGTM.

@addaleax

This comment has been minimized.

Show comment
Hide comment
@addaleax

addaleax May 24, 2017

Member

Landed in 04e9dcb3f392f66b3d1e5c006f7be227297f8b8c

Member

addaleax commented May 24, 2017

Landed in 04e9dcb3f392f66b3d1e5c006f7be227297f8b8c

@addaleax addaleax closed this May 24, 2017

@addaleax

This comment has been minimized.

Show comment
Hide comment
@addaleax

addaleax May 24, 2017

Member

Reopened, seems like I was too fast here.

Member

addaleax commented May 24, 2017

Reopened, seems like I was too fast here.

@addaleax addaleax reopened this May 24, 2017

@refack

This comment has been minimized.

Show comment
Hide comment
@refack

refack May 24, 2017

Member

@jasnell how strongly do you feel on the *Note* vs **Note** style? Seems to me like it's only the two of us that have a preference...

Member

refack commented May 24, 2017

@jasnell how strongly do you feel on the *Note* vs **Note** style? Seems to me like it's only the two of us that have a preference...

@addaleax

This comment has been minimized.

Show comment
Hide comment
@addaleax

addaleax May 24, 2017

Member

I’m +1 to *Note*.

Member

addaleax commented May 24, 2017

I’m +1 to *Note*.

@refack

This comment has been minimized.

Show comment
Hide comment
@refack

refack May 25, 2017

Member

I yield. I see two explicit +1 for *Note*: and there's @Trott's #13131 (comment)

Member

refack commented May 25, 2017

I yield. I see two explicit +1 for *Note*: and there's @Trott's #13131 (comment)

@refack

refack approved these changes May 25, 2017

👍 to *Note*: style.

@refack refack self-assigned this May 25, 2017

@refack

This comment has been minimized.

Show comment
Hide comment
@refack

refack May 25, 2017

Member

Landed in 2af49b6

Member

refack commented May 25, 2017

Landed in 2af49b6

refack added a commit to refack/node that referenced this pull request May 25, 2017

doc: make the style of notes consistent
Make the style of "Note:" paragraphs consistent and document the
guidelines in `doc/STYLE_GUIDE.md`.

PR-URL: nodejs#13133
Fixes: nodejs#13131
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
@refack

This comment has been minimized.

Show comment
Hide comment
@refack

refack May 25, 2017

Member

Landed in 2af49b6

Member

refack commented May 25, 2017

Landed in 2af49b6

@refack refack closed this May 25, 2017

@aqrln aqrln deleted the aqrln:doc-consistent-notes branch May 25, 2017

jasnell added a commit that referenced this pull request May 28, 2017

doc: make the style of notes consistent
Make the style of "Note:" paragraphs consistent and document the
guidelines in `doc/STYLE_GUIDE.md`.

PR-URL: #13133
Fixes: #13131
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

@jasnell jasnell referenced this pull request May 28, 2017

Closed

8.0.0 Release Proposal #12220

@MylesBorins

This comment has been minimized.

Show comment
Hide comment
@MylesBorins

MylesBorins Jul 17, 2017

Member

This does not land cleanly in LTS. Please feel free to manually backport. Please also feel free to replace do-not-land if it is being backported

Member

MylesBorins commented Jul 17, 2017

This does not land cleanly in LTS. Please feel free to manually backport. Please also feel free to replace do-not-land if it is being backported

gabrielschulhof added a commit to gabrielschulhof/node that referenced this pull request Mar 12, 2018

doc: make the style of notes consistent
Make the style of "Note:" paragraphs consistent and document the
guidelines in `doc/STYLE_GUIDE.md`.

This applies the parts of 2af49b6 that
are relevant to N-API.

PR-URL: nodejs#13133
Fixes: nodejs#13131
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

gabrielschulhof added a commit to gabrielschulhof/node that referenced this pull request Mar 15, 2018

doc: make the style of notes consistent
Make the style of "Note:" paragraphs consistent and document the
guidelines in `doc/STYLE_GUIDE.md`.

This applies the parts of 2af49b6 that
are relevant to N-API.

PR-URL: nodejs#13133
Fixes: nodejs#13131
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

gabrielschulhof added a commit to gabrielschulhof/node that referenced this pull request Mar 31, 2018

doc: make the style of notes consistent
Make the style of "Note:" paragraphs consistent and document the
guidelines in `doc/STYLE_GUIDE.md`.

PR-URL: nodejs#13133
Fixes: nodejs#13131
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

gabrielschulhof added a commit to gabrielschulhof/node that referenced this pull request Apr 6, 2018

doc: make the style of notes consistent
Make the style of "Note:" paragraphs consistent and document the
guidelines in `doc/STYLE_GUIDE.md`.

PR-URL: nodejs#13133
Fixes: nodejs#13131
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment