Update terminal doc block

Have hopefully made it simpler to understand.

tags/terminal.tag

@@ -1,17 +1,13 @@
 /**
  * # Terminal Riot Tag
  *
- * Provides a pretend commandline interface, capable of displaying output from a
- * "shell" JavaScript class. Multiple terminal tags can be used on a page, using
- * the same shell class or different ones - each terminal will work
- * independently.
+ * A pretend commandline interface capable of displaying output from a "shell"
+ * Javascript class. Multiple tags can be used on a page, each will work
+ * completely independently.
  *
- * ## Defaults
+ * ## Dependencies
  *
- * The default prompt is `'$ '`.
- * The default welcome message is empty.
- * The default shell performs no actions: pressing enter will simply move the
- * cursor to the next prompt line.
+ * - riot.js (http://riotjs.com/)
  *
  * ## Usage
  *
@@ -22,29 +18,38 @@
  *     <script src='terminal.tag' type='riot/tag'></script>
  *     <script>riot.mount('terminal')</script>
  *
- * ## Dependencies
+ * ## Configuring
  *
- * - riot.js (http://riotjs.com/)
+ * The terminal tag accepts 3 optional parameters:
+ *
+ * - `shell` - Text specifying the shell class to interact with.
+ * - `welcome` - Text/HTML displayed when a terminal is first mounted.
+ * - `prompt` - Text/HTML before the commandline input. Defaults to `'$ '`.
+ *
+ * With no shell logic, the terminal tag will simply print commands entered.
+ *
+ * Note: `welcome` and `prompt` can also be specified in the shell. Shell values
+ * take priority over parameter values.
  *
  * ## Making A Shell Class
  *
- * A shell class must be defined before the tag is mounted. Shells can keep
- * prompt and welcome message settings, and should listen to the `'cmd_entered'`
- * event to process input from the `commandline` tag.
+ * A shell class should be defined before the tag is mounted by riot. It should
+ * expect a single parameter (the terminal tag itself) which will be an
+ * observable object.
  *
- * Here is the structure of a minimal shell that does nothing:
+ * This observable will emit `'cmd_entered'` events containing input for
+ * processing. Here is a minimal shell:
  *
  *     // Contents of myshell.js
  *     function myshellclass(events) {
  *        this.prompt = ''
  *        this.welcome = ''
  *        events.on('cmd_entered', function(input) {
- *          // Do nothing
+ *          // Do processing
  *        })
  *     }
  *
- * The shell can trigger events available on the `display` and `commandline`
- * tags to make things happen:
+ * The observable also provides events to make things happen:
  *
  *     events.trigger('disp_add', text)   // Append `text` to the display
  *     events.trigger('disp_set', text)   // Display only `text`
@@ -53,8 +58,7 @@
  *     events.trigger('disp_restore')     // Restore the saved display
  *     events.trigger('prompt_set', text) // Change the command prompt to `text`
  *     events.trigger('prompt_hide')      // Hide the command prompt
- *     events.trigger('prompt_show')      // Show the command prompt, if hidden
- *
+ *     events.trigger('prompt_show')      // Show the command prompt
  */
 <terminal>
   <display welcome={ welcome } events={ this } />