Rebased from master

1 files changed, 38 insertions, 18 deletions

diff --git a/docs/Ruby-API.md b/docs/Ruby-API.md
index 2dbc10e..a9963b3 100644
--- a/docs/Ruby-API.md
+++ b/docs/Ruby-API.md
@@ -3,33 +3,39 @@
 The following objects exist in Oxidized.
 
 ## Input
- * gets config from nodes
- * must implement 'connect', 'get', 'cmd'
- * 'ssh', 'telnet, ftp, and tftp' implemented
+
+* gets config from nodes
+* must implement 'connect', 'get', 'cmd'
+* 'ssh', 'telnet', 'ftp', and 'tftp' implemented
 
 ## Output
- * stores config
- * must implement 'store' (may implement 'fetch')
- * 'git' and 'file' (store as flat ascii) implemented
+
+* stores config
+* must implement 'store' (may implement 'fetch')
+* 'git' and 'file' (store as flat ascii) implemented
 
 ## Source
- * gets list of nodes to poll
- * must implement 'load'
- * source can have 'name', 'model', 'group', 'username', 'password', 'input', 'output', 'prompt'
-   * name - name of the devices
-   * model - model to use ios/junos/xyz, model is loaded dynamically when needed (Also default in config file)
-   * input - method to acquire config, loaded dynamically as needed (Also default in config file)
-   * output - method to store config, loaded dynamically as needed (Also default in config file)
-   * prompt - prompt used for node (Also default in config file, can be specified in model too)
- * 'sql', 'csv' and 'http' (supports any format with single entry per line, like router.db)
+
+* gets list of nodes to poll
+* must implement 'load'
+* source can have 'name', 'model', 'group', 'username', 'password', 'input', 'output', 'prompt' for each device.
+  * `name` - name of the device
+  * `model` - model to use ('ios', 'junos', etc).The model is loaded dynamically by the first node of that model type. (Also default in config file)
+  * `input` - method to acquire config, loaded dynamically as needed (Also default in config file)
+  * `output` - method to store config, loaded dynamically as needed (Also default in config file)
+  * `prompt` - prompt used for node (Also default in config file, can be specified in model too)
+* 'sql', 'csv' and 'http' (supports any format with single entry per line, like router.db)
 
 ## Model
+
 ### At the top level
+
 A model may use several methods at the top level in the class. `cfg` is
 executed in input/output/source context. `cmd` is executed within an instance
 of the model.
 
 #### `cfg`
+
 `cfg` may be called with a list of methods (`:ssh`, `:telnet`) and a block with
 zero parameters.  Calling `cfg` registers the given access methods and calling
 it at least once is required for a model to work.
@@ -38,6 +44,7 @@ The block may contain commands to change some behaviour for the given methods
 (e.g. calling `post_login` to disable the pager).
 
 #### `cmd`
+
 Is used to specify commands that should be executed on a model in order to
 gather its configuration. It can be called with:
 
@@ -69,18 +76,21 @@ Execution order is `:all`, `:secret`, and lastly the command specific block, if
 given.
 
 #### `comment`
+
 Called with a single string containing the string to prepend for comments in
 emitted configuration for this model.
 
 If not specified the default of `'# '` will be used (note the trailing space).
 
 #### `prompt`
+
 Is called with a regular expression that is used to detect when command output
 ends after a command has been executed.
 
 If not specified, a default of `/^([\w.@-]+[#>]\s?)$/` is used.
 
 #### `expect`
+
 Called with a regular expression and a block. The block takes two parameters:
 the regular expression, and the data containing the match.
 
@@ -90,26 +100,36 @@ The passed data is replaced by the return value of the block.
 it's further processed.
 
 ### At the second level
+
 The following methods are available:
 
 #### `comment`
+
 Used inside `cmd` invocations. Comments out every line in the passed string and
 returns the result.
 
 #### `password`
+
 Used inside `cfg` invocations to specify the regular expression used to detect
 the password prompt. If not specified, the default of `/^Password/` is used.
 
 #### `post_login`
+
 Used inside `cfg` invocations to specify commands to run once Oxidized has
-logged in to the switch. Takes one argument that is either a block (taking zero
+logged in to the device. Takes one argument that is either a block (taking zero
 parameters) or a string containing a command to execute.
 
+This allows `post_login` to be used for any model-specific items prior to running the regular commands. This could include disabling the output pager or timestamp outputs that would cause constant differences.
+
 #### `pre_logout`
+
 Used to specify commands to run before Oxidized closes the connection to the
-switch. Takes one argument that is either a block (taking zero parameters) or a
+device. Takes one argument that is either a block (taking zero parameters) or a
 string containing a command to execute.
 
+This allows `pre_logout` to be used to 'undo' any changes that may have been needed via `post_login` (restore pager output, etc.)
+
 #### `send`
+
 Usually used inside `expect` or blocks passed to `post_login`/`pre_logout`.
-Takes a single parameter: a string to be sent to the switch.
+Takes a single parameter: a string to be sent to the device.