Add terminal tag docblock and code comments

tags/terminal.tag

@@ -1,12 +1,64 @@
+/**
+ * # Terminal Riot Tag
+ *
+ * Provides a pretend commandline interface, capable of displaying output from a
+ * "Shell" javascript object.
+ *
+ * ## 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.
+ *
+ * ## Usage
+ *
+ *     <terminal shell='jsobject' welcome='text' prompt='text'></terminal>
+ *
+ *     <script src='riot+compiler.min.js'></script>
+ *     <script src='he.js'></script>
+ *     <script src='shell.js'></script>
+ *     <script src='terminal.tag' type='riot/tag'></script>
+ *     <script>riot.mount('terminal')</script>
+ *
+ * ## Dependencies
+ *
+ * - riot.js (http://riotjs.com/)
+ * - he.js (https://github.com/mathiasbynens/he) for HTML Entity conversion.
+ *
+ * ## Making a Shell javascript object
+ *
+ * Shell objects 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:
+ *
+ *     // Contents of shell.js
+ *     function() shell() {
+ *        this.prompt = ''
+ *        this.welcome = ''
+ *        this.process = function(input) {
+ *          return ''
+ *        }
+ *     }
+ *     var myshell = new shell()
+ *
+ *     // Shell object used by Terminal Riot Tag
+ *     <terminal shell='myshell'></terminal>
+ */
 <terminal>
   <history welcome={ welcome } />
   <commandline prompt={ prompt } />
 
+  // Take defaults from shell, otherwise take from `<terminal>` options.
   var shell = { 'process': function() { return ''; } }
   this.shell = window[opts.shell] ? window[opts.shell] : shell
   this.welcome = this.shell.welcome ? this.shell.welcome : opts.welcome
   this.prompt = this.shell.prompt ? this.shell.prompt : opts.prompt
 
+  /**
+   * How to process a command:
+   * - Make the input safe by transforming html entities.
+   * - Keep the last command in history as we go to the next line.
+   * - Append the shell output, and update the prompt as required.
+   */
   process(prompt, input) {
     var input = he.encode(input)
     var output = prompt + ' ' + input + '\n'
@@ -35,6 +87,14 @@
     document.getElementsByName('command')[0].focus()
   })
 
+  /**
+   * 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.
+   */
   setprompt(value) {
     if (value) {
       if (typeof this.tags.lhs.write != 'undefined') {
@@ -57,6 +117,11 @@
     <raw content={ content } />
   </div>
 
+  /**
+   * Append any truthy value to command history
+   *
+   * Replaces all newline characters with HTML breaks.
+   */
   add(output) {
     if (output) {
       output = output.replace(/(?:\r\n|\r|\n)/g, '<br />');
@@ -72,6 +137,7 @@
 <raw>
   <span></span>
 
+  // Initialise contents from tag options, but expose `write()` for updating.
   write(value) {
     this.root.innerHTML = value
   }