Document user-defined state

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:

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' } })
+```