Improve documentation of stdin, stdout, stderr and stdio
#626
Conversation
ehmicky
force-pushed
the
improve-docs-stdio
branch
2 times, most recently
from
7ad8ba3
to
bcfe734
Compare
|
|
||
| #### stdin | ||
|
|
||
| Type: `string | number | stream.Readable | ReadableStream | undefined | URL | Iterable<string | Uint8Array> | AsyncIterable<string | Uint8Array>`\ |
There was a problem hiding this comment.
Discourage using undefined: 'pipe' is clearer, and in most common cases is not needed since it is the default value.
index.d.ts
Outdated
| Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). | ||
|
|
||
| It can also be a file path, a file URL, a web stream ([`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)), an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol) or an [`AsyncIterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols), unless either [`execaSync()`](#execasyncfile-arguments-options), the [`input` option](#input) or the [`inputFile` option](#inputfile) is used. If the file path is relative, it must start with `.`. | ||
| [How to setup](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio) the child process' standard input. This can be: |
There was a problem hiding this comment.
| [How to setup](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio) the child process' standard input. This can be: | |
| [How to setup](https://nodejs.org/docs/latest-v18.x/api/child_process.html#child_process_options_stdio) the child process' standard input. This can be: |
Should this link point to the LTS docs? (Referencing pkg.engines.node)
There was a problem hiding this comment.
Thanks for pointing this out! Fixed.
index.d.ts
Outdated
| @@ -435,7 +474,8 @@ export type ExecaReturnValue<StdoutStderrType extends StdoutStderrAll = string> | |||
|
|
|||
| This is `undefined` if either: | |||
| - the `all` option is `false` (default value) | |||
| - `execaSync()` was used | |||
| - the synchronous methods are used | |||
| - both `stdout` and `stderr` options are set to [`'inherit'`, `'ipc'`, `'ignore'`, `Stream` or `integer`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio) | |||
There was a problem hiding this comment.
| - both `stdout` and `stderr` options are set to [`'inherit'`, `'ipc'`, `'ignore'`, `Stream` or `integer`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio) | |
| - both `stdout` and `stderr` options are set to [`'inherit'`, `'ipc'`, `'ignore'`, `Stream` or `integer`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio) |
There was a problem hiding this comment.
It appears that no using indentation shows like this with VSCode:
But using indentation shows like this:
However, we were being inconsistent with both the types and the readme.md, so I fixed it all to make it consistent.
index.d.ts
Outdated
| */ | ||
| shortMessage: string; | ||
|
|
||
| /** | ||
| Original error message. This is the same as the `message` property except it includes neither the child process stdout/stderr nor some additional information added by Execa. | ||
| Original error message. This is the same as the `message` property except it includes neither the child process `stdout`/`stderr` nor some additional information added by Execa. |
There was a problem hiding this comment.
Understanding this diff is a formatting update, the sentence reads a little confusing to me (particularly from except it includes neither [...]).
Light suggestion, but perhaps this is more clear:
This is the same as the
messageproperty excluding the child processstdout/stderrand additional information added by Execa.
There was a problem hiding this comment.
Much better! Thanks.
Done.
|
Ready for review again. |
Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>
ehmicky
force-pushed
the
improve-docs-stdio
branch
from
4ca4dda
to
bdf8bf4
Compare
|
Fixed the merge conflict. |
This PR improves the documentation of the
std*options.