add rule results to documentation

Author: Cache Hamm

docs/engine.md

@@ -130,20 +130,22 @@ engine.stop()
 
 There are two generic event emissions that trigger automatically:
 
-#### ```engine.on('success', cb)```
+#### ```engine.on('success', Function(Object event, Almanac almanac, RuleResult ruleResult))```
 
-Fires when a rule passes. In this case the callback will receive the entire event object.
+Fires when a rule passes. The callback will receive the event object, the current [Almanac](./almanac.md), and the [Rule Result](./rules.md#rule-results).
 
 ```js
 engine.on('success', function(event, almanac, ruleResult) {
+  console.log(event) // { type: 'my-event', params: { id: 1 }
 })
 ```
 
-#### ```engine.on('failure', cb)```
+#### ```engine.on('failure', Function(Object event, Almanac almanac, RuleResult ruleResult))```
 
-Companion to 'success', except fires when a rule fails.
+Companion to 'success', except fires when a rule fails.  The callback will receive the event object, the current [Almanac](./almanac.md), and the [Rule Result](./rules.md#rule-results).
 
 ```js
 engine.on('failure', function(event, almanac, ruleResult) {
+  console.log(event) // { type: 'my-event', params: { id: 1 }
 })
 ```

docs/rules.md

@@ -1,7 +1,18 @@
+
 # Rules
 
 Rules contain a set of _conditions_ and a single _event_.  When the engine is run, each rule condition is evaluated.  If the results are truthy, the rule's _event_ is triggered.
 
+[Methods](#Methods)
+
+[Conditions](#Conditions)
+
+[Events](#Events)
+
+[Operators](#Operators)
+
+[Results](#Results)
+
 ## Methods
 
 ### constructor([Object options|String json])
@@ -223,6 +234,8 @@ Listen for `success` and `failure` events emitted when rule is evaluated.
 
 #### ```rule.on('success', Function(Object event, Almanac almanac, RuleResult ruleResult))```
 
+The callback will receive the event object, the current [Almanac](./almanac.md), and the [Rule Result](./rules.md#rule-results).
+
 ```js
 // whenever rule is evaluated and the conditions pass, 'success' will trigger
 rule.on('success', function(event, almanac, ruleResult) {
@@ -232,7 +245,7 @@ rule.on('success', function(event, almanac, ruleResult) {
 
 #### ```rule.on('failure', Function(Object event, Almanac almanac, RuleResult ruleResult))```
 
-Companion to `success`, except fires when the rule fails.
+Companion to `success`, except fires when the rule fails.  The callback will receive the event object, the current [Almanac](./almanac.md), and the [Rule Result](./rules.md#rule-results).
 
 ```js
 engine.on('failure', function(event, almanac, ruleResult) {
@@ -273,3 +286,34 @@ The ```operator``` compares the value returned by the ```fact``` to what is stor
   ```contains```  - _fact_ (an array) must include _value_
 
   ```doesNotContain```  - _fact_ (an array) must not include _value_
+
+## Rule Results
+
+After a rule is evaluated, a `rule result` object is provided to the `success` and `failure` events.  This argument is similar to a regular rule, and contains additional metadata about how the rule was evaluated.  Rule results can be used to extract the results of individual conditions, computed fact values, and boolean logic results.
+
+Rule results are structured similar to rules, with two additional pieces of metadata sprinkled throughout: `result` and `factResult`
+```js
+{
+  result: false,                    // denotes whether rule computed truthy or falsey
+  conditions: {
+    all: [
+      {
+        fact: 'my-fact',
+        operator: 'equal',
+        value: 'some-value',
+        result: false,             // denotes whether condition computed truthy or falsey
+        factResult: 'other-value'  // denotes what 'my-fact' was computed to be
+      }
+    ]
+  },
+  event: {
+    type: 'my-event',
+    params: {
+      customProperty: 'customValue'
+    }
+  },
+  priority: 1,
+}
+```
+
+A demonstration can be found in the [rule-results](../examples/09-rule-results.js) example.