Skip to content
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

a couple doc improvements / fixes #17702

Merged
merged 4 commits into from Dec 18, 2017

Conversation

Projects
None yet
4 participants
@Fishrock123
Copy link
Member

commented Dec 15, 2017

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • documentation is changed or added
  • commit message follows commit guidelines
Affected core subsystem(s)

doc

Mostly an edit pass over documentation.md but also some fixes to tty.md, fs.md, and synopsis.md.

@Fishrock123 Fishrock123 added the doc label Dec 15, 2017

is not recommended in production environments. Experimental features are not
subject to the Node.js Semantic Versioning model.
is not recommended in production environments. **Experimental features are not
subject to the Node.js Semantic Versioning model.**

This comment has been minimized.

Copy link
@Trott

Trott Dec 15, 2017

Member

I'm generally opposed to adding bold text except in extremely compelling situations. We waaaaaaay overuse typographical emphasis to the point that it has become mostly meaningless.

I'm especially opposed to it here because this is jargon a lot of people won't understand. I know you didn't write this text here, but "are not subject to the Node.js Semantic Versioning model" is vague and kind of misleading. There's nothing Node.js-specific about semantic versioning, and it's not clear that it could correctly be called a model or what that means/implies.

This text is redundant anyway. The very first sentence says things plainly: "subject to non-backwards compatible changes, or even removal, in any future release." Maybe dispense with this last jargon-y sentence and (if we must emphasize something) emphasize that text instead?

This comment has been minimized.

Copy link
@Trott

Trott Dec 15, 2017

Member

^^^^ non-blocking objection, by the way. Just comments.

```txt
Stability: 2 - Stable
The API has proven satisfactory. Compatibility with the npm ecosystem
is a high priority, and will not be broken unless absolutely necessary.
```

*Note*: Caution must be used when making use of `Experimental` features,

This comment has been minimized.

Copy link
@Trott

Trott Dec 15, 2017

Member

(Non-blocking) I'd remove *Note*: here and save it for things that really truly need it. Also remove the **Note**: (note different typography 🙄 ) later in this doc.

This comment has been minimized.

Copy link
@Fishrock123

Fishrock123 Dec 16, 2017

Author Member

I think it worth keeping on that one.


## Syscalls and man pages

System calls like open(2) and read(2) define the interface between user programs
and the underlying operating system. Node functions which simply wrap a syscall,
like `fs.open()`, will document that. The docs link to the corresponding man
like [`fs.open()`][], will document that. The docs link to the corresponding man
pages (short for manual pages) which describe how the syscalls work.

**Note:** some syscalls, like lchown(2), are BSD-specific. That means, for

This comment has been minimized.

Copy link
@Trott

Trott Dec 15, 2017

Member

While in here, some -> Some

@Trott

Trott approved these changes Dec 15, 2017

Copy link
Member

left a comment

I left some nits/opinions, but overall, seems like an improvement whether or not those nits/opinions are accepted. 😆

[`net.Socket`]: net.html#net_class_net_socket
[`process.stdin`]: process.html#process_process_stdin
[`process.stdout`]: process.html#process_process_stdout
[`process.stderr`]: process.html#process_process_stderr

This comment has been minimized.

Copy link
@vsemozhetbyt

vsemozhetbyt Dec 16, 2017

Contributor

A nit: out of ABC order.

This comment has been minimized.

Copy link
@Fishrock123

Fishrock123 Dec 16, 2017

Author Member

Have we actually been enforcing this? I'm kinda clueless - if we have been generally I'll change it, if not... maybe we should do that separately with linting?

This comment has been minimized.

Copy link
@vsemozhetbyt

vsemozhetbyt Dec 16, 2017

Contributor

Sorry, I thought it was enforced in doc linting or style guide, but it seems I am wrong, I cannot even find PRs that sort references explicitly (I recall there were some). So maybe it is OK as is.

This comment has been minimized.

Copy link
@Fishrock123

Fishrock123 Dec 16, 2017

Author Member

For posterity: these are ordered (pretty sure I got it right) in their order of references.

@Fishrock123 Fishrock123 force-pushed the Fishrock123:doc-fixes branch from 45740ca to e463ccd Dec 16, 2017

@Fishrock123

This comment has been minimized.

Copy link
Member Author

commented Dec 16, 2017

Fishrock123 added some commits Dec 15, 2017

doc: improve documentation.md
Reworded some parts, inter-doc links.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
doc: fix fs.existsSync description
Also works on directories.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
doc: adjust TTY wording & add inter-doc links
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
doc: not all example code can be run without 1:1
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

@Fishrock123 Fishrock123 force-pushed the Fishrock123:doc-fixes branch from e463ccd to ce38c49 Dec 18, 2017

@Fishrock123 Fishrock123 merged commit ce38c49 into nodejs:master Dec 18, 2017

@Fishrock123 Fishrock123 deleted the Fishrock123:doc-fixes branch Dec 18, 2017

MylesBorins added a commit that referenced this pull request Jan 8, 2018

doc: improve documentation.md
Reworded some parts, inter-doc links.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Jan 8, 2018

doc: fix fs.existsSync description
Also works on directories.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Jan 8, 2018

doc: adjust TTY wording & add inter-doc links
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Jan 8, 2018

doc: not all example code can be run without 1:1
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Jan 9, 2018

doc: improve documentation.md
Reworded some parts, inter-doc links.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Jan 9, 2018

doc: fix fs.existsSync description
Also works on directories.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Jan 9, 2018

doc: adjust TTY wording & add inter-doc links
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Jan 9, 2018

doc: not all example code can be run without 1:1
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

@MylesBorins MylesBorins referenced this pull request Jan 10, 2018

Merged

v9.4.0 proposal #18069

boingoing added a commit to nodejs/node-chakracore that referenced this pull request Jan 18, 2018

doc: improve documentation.md
Reworded some parts, inter-doc links.

PR-URL: nodejs/node#17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

boingoing added a commit to nodejs/node-chakracore that referenced this pull request Jan 18, 2018

doc: fix fs.existsSync description
Also works on directories.

PR-URL: nodejs/node#17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

boingoing added a commit to nodejs/node-chakracore that referenced this pull request Jan 18, 2018

doc: adjust TTY wording & add inter-doc links
PR-URL: nodejs/node#17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

boingoing added a commit to nodejs/node-chakracore that referenced this pull request Jan 18, 2018

doc: not all example code can be run without 1:1
PR-URL: nodejs/node#17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

gibfahn added a commit that referenced this pull request Jan 24, 2018

doc: not all example code can be run without 1:1
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

gibfahn added a commit that referenced this pull request Jan 24, 2018

doc: improve documentation.md
Reworded some parts, inter-doc links.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

gibfahn added a commit that referenced this pull request Jan 24, 2018

doc: fix fs.existsSync description
Also works on directories.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

gibfahn added a commit that referenced this pull request Jan 24, 2018

doc: adjust TTY wording & add inter-doc links
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

gibfahn added a commit that referenced this pull request Jan 24, 2018

doc: not all example code can be run without 1:1
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

@MylesBorins MylesBorins referenced this pull request Jan 24, 2018

Merged

v6.13.0 proposal #18342

msoechting added a commit to hpicgs/node that referenced this pull request Feb 5, 2018

doc: improve documentation.md
Reworded some parts, inter-doc links.

PR-URL: nodejs#17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

msoechting added a commit to hpicgs/node that referenced this pull request Feb 5, 2018

doc: fix fs.existsSync description
Also works on directories.

PR-URL: nodejs#17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

msoechting added a commit to hpicgs/node that referenced this pull request Feb 5, 2018

doc: adjust TTY wording & add inter-doc links
PR-URL: nodejs#17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

msoechting added a commit to hpicgs/node that referenced this pull request Feb 5, 2018

doc: not all example code can be run without 1:1
PR-URL: nodejs#17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

msoechting added a commit to hpicgs/node that referenced this pull request Feb 7, 2018

doc: improve documentation.md
Reworded some parts, inter-doc links.

PR-URL: nodejs#17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

msoechting added a commit to hpicgs/node that referenced this pull request Feb 7, 2018

doc: fix fs.existsSync description
Also works on directories.

PR-URL: nodejs#17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

msoechting added a commit to hpicgs/node that referenced this pull request Feb 7, 2018

doc: adjust TTY wording & add inter-doc links
PR-URL: nodejs#17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

msoechting added a commit to hpicgs/node that referenced this pull request Feb 7, 2018

doc: not all example code can be run without 1:1
PR-URL: nodejs#17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 11, 2018

doc: improve documentation.md
Reworded some parts, inter-doc links.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 11, 2018

doc: fix fs.existsSync description
Also works on directories.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 11, 2018

doc: adjust TTY wording & add inter-doc links
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 11, 2018

doc: not all example code can be run without 1:1
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 12, 2018

doc: improve documentation.md
Reworded some parts, inter-doc links.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 12, 2018

doc: fix fs.existsSync description
Also works on directories.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 12, 2018

doc: adjust TTY wording & add inter-doc links
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 12, 2018

doc: not all example code can be run without 1:1
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 12, 2018

doc: improve documentation.md
Reworded some parts, inter-doc links.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 12, 2018

doc: fix fs.existsSync description
Also works on directories.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 12, 2018

doc: adjust TTY wording & add inter-doc links
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 12, 2018

doc: not all example code can be run without 1:1
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 13, 2018

doc: improve documentation.md
Reworded some parts, inter-doc links.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 13, 2018

doc: fix fs.existsSync description
Also works on directories.

PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 13, 2018

doc: adjust TTY wording & add inter-doc links
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins added a commit that referenced this pull request Feb 13, 2018

doc: not all example code can be run without 1:1
PR-URL: #17702
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.