Documentation update

README.md

@@ -5,25 +5,26 @@
 [![install size](https://packagephobia.now.sh/badge?p=observable-process)](https://packagephobia.now.sh/result?p=observable-process)
 [![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/kevgo/observable-process.svg)](https://lgtm.com/projects/g/kevgo/observable-process/context:javascript)
 
-ObservableProcess decorates the low-level
+ObservableProcess enhances the slightly too low-level
 [Node.JS ChildProcess](https://nodejs.org/api/child_process.html) model with
 functionality to observe the behavior of processes more conveniently. In
 particular:
 
-- easier access to the complete textual content of the
+- easier access to the textual content of the
   [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)
   streams
-- augments `stdout` and `stderr` with methods to search for textual content
+- augments `stdout` and `stderr` with methods to wait for textual content
 - create a new `output` stream that combines `stdout` and `stderr`
-- await the process end
+- ability to `await` the process end
 - easier access to the process exit code
 - signals whether the process ended naturally or was manually terminated
 
-This is useful for example when testing the terminal output of applications.
-Executing long-running processes through ObservableProcess will cause high
-memory consumption because it stores all the terminal output in RAM.
+This is useful for example when testing the terminal output of applications or
+waiting until a server has fully booted up. Executing long-running processes
+that produce lots of output through ObservableProcess will cause high memory
+consumption because it stores all the terminal output in RAM.
 
 ## Setup
 
@@ -39,7 +40,7 @@ Load this library into your JavaScript code:
 const { start } = require("observable-process")
 ```
 
-– or –
+or
 
 ```ts
 import { start } from "observable-process"
@@ -80,16 +81,17 @@ const observable = start("node server.js", {
 Without a custom `env` parameter, ObservableProcess uses the environment
 variables from the parent process.
 
-## Reading output from the process
+## Reading output
 
 The `stdout` and `stderr` variables of an ObservableProcess behave like normal
 [readable streams](https://nodejs.org/api/stream.html#stream_readable_streams)
-and provide extra functionality to access and search their content.
+and provide extra functionality to access and search their content while the
+process runs.
 
 ```js
 // normal access to STDOUT
 observable.stdout.on("data", function () {
-  // do something here
+  // ...
 })
 
 // get all content from STDOUT as a string
@@ -108,13 +110,27 @@ a new `output` stream with the combined content of STDOUT and STDERR:
 
 ```js
 observable.output.on("data", function (data) {
-  // do something here
+  // ...
 })
 const text = observable.output.fullText()
 await observable.output.waitForText("server is online")
 const port = await observable.output.waitForRegex(/running at port \d+./)
 ```
 
+The [Result](src/result.ts) instance you get when the process ends also contains
+the full content of the output streams:
+
+```js
+const result = observable.waitForEnd()
+assert.equal(result, {
+  exitCode: 0,
+  killed: false,
+  stdOutput: "... content from STDOUT ...",
+  errOutput: "... content from STDERR ...",
+  combinedOutput: "... content from both STDOUT and STDERR ...",
+})
+```
+
 ## Sending input to the process
 
 ObservableProcess exposes the
@@ -135,19 +151,10 @@ observable.pid()
 
 ## Stop the process
 
-You can manually stop a running process via:
-
-```js
-await observable.kill()
-```
-
-This sets the `killed` property on the ObservableProcess instance, which allows
-to distinguish manually terminated processes from naturally ended ones.
-
 To let ObservableProcess notify you when a process ended:
 
 ```js
-const exitCode = await observable.waitForEnd()
+const result = await observable.waitForEnd()
 ```
 
 You can also listen to this in the background:
@@ -164,6 +171,12 @@ The exit code is available via an attribute:
 observable.exitCode
 ```
 
+You can also manually stop a running process via:
+
+```js
+const result = await observable.kill()
+```
+
 ## Related libraries
 
 - [nexpect](https://github.com/nodejitsu/nexpect): Allows to define expectations