Update terminal documentation

tags/terminal.tag

@@ -2,13 +2,15 @@
  * # 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,
- * acting independently of one another.
+ * "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.
  *
  * ## Defaults
  *
- * The default prompt is `'$'`. There is no default the welcome message. Until a
- * shell is added, pressing enter will simply move to the next prompt.
+ * The default prompt is `'$'`. There is no default the welcome message. The
+ * default shell performs no actions: pressing enter will simply move the cursor
+ * to the next prompt line.
  *
  * ## Usage
  *
@@ -25,11 +27,11 @@
  * - riot.js (http://riotjs.com/)
  * - he.js (https://github.com/mathiasbynens/he) for HTML Entity conversion.
  *
- * ## Making a Shell javascript class
+ * ## Making A Shell Class
  *
- * Shell class must be defined before the tag is mounted. Shells can keep
- * prompt character and welcome message settings, and must define a `process()`
- * function. Here is the structure of a minimumal shell that does nothing:
+ * The shell class must be defined before the tag is mounted. Shells can keep
+ * prompt and welcome message settings, and must define a `process()` function.
+ * Here is the structure of a minimal shell that does nothing:
  *
  *     // Contents of myshell.js
  *     function() myshell() {
@@ -40,22 +42,22 @@
  *        }
  *     }
  *
- *     // Shell class used by Terminal Riot Tag in index.html
+ *     // shell class used by Terminal Riot Tag in index.html
  *     <terminal shell='myshell'></terminal>
  *
- * ## Special Return Values
+ * ## Special Shell Return Values
  *
- * The Terminal tag can recognise particular return values from the Shell, and
- * can perform actions other than printing output:
+ * The terminal tag recognises some predefined shell return values and upon
+ * receiving them, can perform actions other than printing output:
  *
- * - `'clear'`. Causes the Terminal to clear the history.
+ * - `'clear'`. Terminal will clear its output history.
  *
  */
 <terminal>
   <history welcome={ welcome } />
   <commandline prompt={ prompt } />
 
-  // Take defaults from shell, otherwise take from `<terminal>` options.
+  // Take defaults from shell, otherwise take from terminal tag options.
   var shell = { 'process': function() { return ''; } }
   this.shell = window[opts.shell] ? new window[opts.shell] : shell
   this.welcome = this.shell.welcome ? this.shell.welcome : opts.welcome
@@ -111,9 +113,9 @@
    * Set the prompt to any truthy value.
    *
    * Note about `lhs.write()` check:
-   * `setPrompt()` fires at `<terminal>` setup, before `lhs.write()` exists.
-   * At that point, `lhs` is just initialised with its `content` option.
-   * After that, `lhs.write()` is called for all subsequent prompt changes.
+   * Terminal tag setup fires `setPrompt()` before `lhs.write()` exists.
+   * At that point, `lhs` is initialised with just its `content` attribute.
+   * After that, `lhs.write()` is called to make all subsequent prompt changes.
    */
   setPrompt(value) {
     if (value) {