From dee933d61a6f8d09291069b86dfba7437c15b2c1 Mon Sep 17 00:00:00 2001
From: Elliot Nelson <nelson.work@gmail.com>
Date: Mon, 25 May 2020 07:58:13 -0400
Subject: [PATCH] docs: document user-defined state

---
 source/docs/async-parsing.md | 12 ++++++++--
 source/docs/context.md       | 43 +++++++++++++++++++++++++++++++++---
 2 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/source/docs/async-parsing.md b/source/docs/async-parsing.md
index b0a5bc3..897812c 100644
--- a/source/docs/async-parsing.md
+++ b/source/docs/async-parsing.md
@@ -10,7 +10,7 @@ The API of sywac can be logically separated into two stages of an app’s lifecy
 This page covers the two `Api` methods designed for the execution stage.
 
 <a name="parse"></a>
-## `.parse(args)`
+## `.parse(args, state)`
 
 <sup>Since 1.0.0</sup>
 
@@ -24,6 +24,10 @@ Note that this method is safe to use concurrently, meaning it is suitable for se
 
   The arguments or message to parse, validate, and execute.
 
+- &nbsp;`state`: optional user-defined state object
+
+  Rarely used, helpful for passing per-request data to concurrent parse requests. Any state you pass here will be attached to the [context](/docs/context.html).
+
 Returns a `Promise` that resolves to a result object, containing the following properties:
 
 - &nbsp;`code`: number/integer
@@ -95,7 +99,7 @@ sywac.parse(msg).then(result => {
 ```
 
 <a name="parseAndExit"></a>
-## `.parseAndExit(args)`
+## `.parseAndExit(args, state)`
 
 <sup>Since 1.0.0</sup>
 
@@ -111,6 +115,10 @@ Note that in a command-driven app, it may be perfectly reasonable to call this m
 
   The arguments or message to parse, validate, and execute.
 
+- &nbsp;`state`: optional user-defined state object
+
+  Rarely used, included for feature parity with `parse`. Any state you pass here will be attached to the [context](/docs/context.html).
+
 Returns a `Promise` that resolves to the `argv` object (subproperty of detailed results) representing the parsed arguments and options as key-value pairs, where each key is a configured alias of an argument/option and each value is the parsed/coerced value for that argument/option. See further description in the [parse method](#parse).
 
 Example:
diff --git a/source/docs/context.md b/source/docs/context.md
index 9e3e192..3bf3274 100644
--- a/source/docs/context.md
+++ b/source/docs/context.md
@@ -5,6 +5,43 @@ next: /docs/advanced-customizations.html
 ---
 # Context
 
-> No content yet
->
-> Sorry! This site is still under construction. Please bear with us until we can fill out more documentation. Thank you!
+The context is a short-lived object that tracks state during asynchronous parsing, validation, and execution. It is created when the user initiates a [parse](/docs/async-parsing.html#parse) or [parseAndExit](/docs/async-parsing.html#parseAndExit) request, and is discarded when the request finishes.
+
+The user usually interacts with the context by defining callbacks:
+
+- The [check](/docs/sync-config.html#check) handler receives the context as a parameter.
+- A [command](/docs/sync-config.html#command)'s run handler receives the context as a parameter.
+
+<a name="cliMessage"></a>
+## `.cliMessage(msg)`
+
+<sup>Since 1.0.0</sup
+
+Add a message to the parsing context. Once parsing finishes, these messages will be added to the help output as error messages (along with any other error messages automatically generated during parsing).
+
+Example:
+
+```js
+sywac.check((argv, context) => {
+  context.cliMessage('Oops, you forgot to enter your name.')
+})
+```
+
+<a name="state"></a>
+## `.state`
+
+<sup>Since FUTURE</sup>
+
+A user-defined state object. This object exists only if passed as a second argument to [parse](/docs/async-parsing.html#parse).
+
+Example:
+
+```js
+sywac.command('login', {
+  run: (argv, context) => {
+    console.log(`Thank you for logging in, ${context.state.user.name}!`)
+  }
+})
+
+sywac.parse('login', { user: { name: 'jan.jansen' } })
+```