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.

Sign up for GitHub

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

Jump to bottom

doc: simplify readline/stdin text #41583

Merged
merged 1 commit into from
Jan 23, 2022
Merged

doc: simplify readline/stdin text #41583

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 3 additions & 10 deletions doc/api/readline.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1059,15 +1059,8 @@ a `'resize'` event on the `output` if or when the columns ever change
([`process.stdout`][] does this automatically when it is a TTY).

When creating a `readline.Interface` using `stdin` as input, the program
will not terminate until it receives `EOF` (<kbd>Ctrl</kbd>+<kbd>D</kbd> on
Linux/macOS, <kbd>Ctrl</kbd>+<kbd>Z</kbd> followed by <kbd>Return</kbd> on
Windows).
If you want your application to exit without waiting for user input, you can
[`unref()`][] the standard input stream:

```js
process.stdin.unref();
```
will not terminate until it receives an [EOF character][]. To exit without
waiting for user input, call `process.stdin.unref()`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is removing the reference to the unref() documentation intentional?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes although it wasn't an easy decision. The choices were:

  • Use wording that isn't straightforward simply so we can include unref() by itself and link that to the net docs. (This is what the existing text does.)
  • Use the simple/straightforward wording here but add a possibly-confusing link for process.stdin.unref() to the net doc description of unref().
  • Use the simple/straightforward wording here that tells the user what they need to know, and don't bother with a link to unref(). At a later date, address the fact that our docs can be non-intuitive. If I find process.stdin.unref() mentioned in code or a tutorial, good luck finding it in the docs. I'm not sure what the solution is, but I think we should solve it. We should not be relying on linking every mention to a surprising place.


#### Use of the `completer` function

Expand Down Expand Up @@ -1395,6 +1388,7 @@ const { createInterface } = require('readline');
</tr>
</table>

[EOF character]: https://en.wikipedia.org/wiki/End-of-file#EOF_character
[Readable]: stream.md#readable-streams
[TTY]: tty.md
[TTY keybindings]: #tty-keybindings
Expand All @@ -1406,5 +1400,4 @@ const { createInterface } = require('readline');
[`process.stdin`]: process.md#processstdin
[`process.stdout`]: process.md#processstdout
[`rl.close()`]: #rlclose
[`unref()`]: net.md#socketunref
[reading files]: #example-read-file-stream-line-by-line