Improve the API section of the readme

readme.md

@@ -15,7 +15,7 @@
 - Higher max buffer. 10 MB instead of 200 KB.
 - [Executes locally installed binaries by name.](#preferlocal)
 - [Cleans up spawned processes when the parent process dies.](#cleanup)
-- [Get interleaved output](#execafile-arguments-options) from `stdout` and `stderr` similar to what is printed on the terminal. [*(Async only)*](#execasyncfile-arguments-options)
+- [Get interleaved output](#all) from `stdout` and `stderr` similar to what is printed on the terminal. [*(Async only)*](#execasyncfile-arguments-options)
 - [Can specify command and arguments as a single string without a shell](#execafile-arguments-options)
 - More descriptive errors.
 
@@ -112,36 +112,106 @@ try {
 ### execa(file, [arguments], [options])
 ### execa(command, [options])
 
-Execute a file.
+Execute a file. Think of this as a mix of [`child_process.execFile()`](https://nodejs.org/api/child_process.html#child_process_child_process_execfile_file_args_options_callback) and [`child_process.spawn()`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options).
 
 Arguments can be specified in either:
   - `arguments`: `execa('echo', ['unicorns'])`.
   - `command`: `execa('echo unicorns')`.
 
-Arguments should not be escaped nor quoted. Exception: inside `command`, spaces can be escaped with a backslash.
-
-Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
+Arguments should not be escaped nor quoted, except inside `command` where spaces can be escaped with a backslash.
 
 Unless the [`shell`](#shell) option is used, no shell interpreter (Bash, `cmd.exe`, etc.) is used, so shell features such as variables substitution (`echo $PATH`) are not allowed.
 
-Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) which is enhanced to be a `Promise`.
+Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) which:
+  - is also a `Promise` resolving or rejecting with a [`childProcessResult`](#childProcessResult).
+  - exposes the following additional methods and properties.
+
+#### cancel()
 
-It exposes an additional `.all` stream, with `stdout` and `stderr` interleaved.
+Same as [`childProcess.kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal) but with a different error message and with [`childProcessResult.isCanceled`](#iscanceled) set to `true`.
 
-The spawned process can be canceled with the `.cancel()` method on the promise, which causes the promise to reject an error with a `.isCanceled = true` property, provided the process gets canceled. The process will not be canceled if it has already exited.
+#### all
 
-The promise result is an `Object` with `stdout`, `stderr` and `all` properties.
+Stream combining/interleaving [`stdout`](https://nodejs.org/api/child_process.html#child_process_subprocess_stdout) and [`stderr`](https://nodejs.org/api/child_process.html#child_process_subprocess_stderr).
 
 ### execa.sync(file, [arguments], [options])
 ### execa.sync(command, [options])
 
 Execute a file synchronously.
 
-Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
+Returns or throws a [`childProcessResult`](#childProcessResult).
+
+### childProcessResult
+
+Type: `object|Error`
+
+Result of a child process execution. On success this is a plain object. On failure this is also an `Error` instance.
+
+#### exitCode
+
+Type: `number`
+
+The numeric exit code of the process that was run.
+
+#### exitCodeName
+
+Type: `string`
+
+The textual exit code of the process that was run.
+
+#### stdout
+
+Type: `string|Buffer`
+
+The output of the process on stdout.
+
+#### stderr
+
+Type: `string|Buffer`
+
+The output of the process on stderr.
+
+#### all
+
+Type: `string|Buffer`
+
+The output of the process on both stdout and stderr. `undefined` if `execa.sync()` was used.
+
+#### command
+
+Type: `string`
+
+The command that was run.
+
+#### failed
+
+Type: `boolean`
+
+Whether the process failed to run.
+
+#### timedOut
+
+Type: `boolean`
+
+Whether the process timed out.
+
+#### killed
+
+Type: `boolean`
+
+Whether the process was killed.
+
+#### isCanceled
+
+Type: `boolean`
+
+Whether the process was canceled.
+
+#### signal
 
-It does not have the `.all` property that `execa()` has because the [underlying synchronous implementation](https://nodejs.org/api/child_process.html#child_process_child_process_execfilesync_file_args_options) only returns `stdout` and `stderr` at the end of the execution, so they cannot be interleaved.
+Type: `string|undefined`
 
-This method throws an `Error` if the command fails.
+The signal that was used to terminate the process.
 
 ### options