misc. minor changes and documentation updates

readme/html/OxDoc.html

@@ -38,6 +38,64 @@
 </script>
 <h1>Ox.doc - A JavaScript Documentation Language</h1>
 
+<p>At its core, Ox.doc is list of lines like this:</p>
+<pre class="code">//@ name &lt;type&gt; summary</pre>
+<p>...</p>
+<pre class="code">/*@
+name &lt;type&gt; summary
+    Longer description
+    that may contain HTML.
+@*/
+</pre>
+
+<p>If you are documenting an object with properties, these lines can be nested:</p>
+<pre class="code">/*@
+My.team &lt;object&gt; Some sports team
+    name &lt;string&gt; The team's name
+    lastMatch &lt;object&gt; The most recent result
+        for &lt;number&gt; Goals for
+        against &lt;number&gt; Goals against
+    won &lt;boolean&gt; If true, last match was a win
+@*/</pre>
+
+<p>The same goes for functions and events:</p>
+<pre class="code">/*@
+My.readURL &lt;function&gt; Reads data from a remote URL
+    (url, callback) -&gt; &lt;o&gt; Request handler
+        cancel &lt;function&gt; The handler's only property. Takes no arguments. Cancels the request.
+    url &lt;string&gt; Remote URL
+    callback &lt;function&gt; Callback function
+        result &lt;object&gt; Result object
+            status &lt;number&gt; HTTP status code
+            data &lt;string&gt; Data read from URL, or empty string
+    stalled &lt;event&gt; Fires when the connection is stalled
+        reason &lt;string&gt; Potential cause of the network problem
+@*/</pre>
+
+
+<p></p>
+
+<pre class="code">/*@
+foo &lt;o&gt; Demo object
+    array     &lt;a&gt; An array (and we don't care about the type of its elements)
+    boolean   &lt;b&gt; True or false
+    date      &lt;d&gt; Date object
+    element   &lt;e&gt; DOM element
+    function  &lt;f&gt; A function
+    number    &lt;n&gt; A number
+    object    &lt;o&gt; An object
+    regexp    &lt;r&gt; Regular Expression
+    string    &lt;s&gt; A string
+    undefined &lt;u&gt; undefined
+        Makes most sense for the result of a function that doesn't return,
+        or as the last of multiple types, to indicate a property may be missing
+    any_value &lt;*&gt; anything
+    event     &lt;!&gt; A custom event
+    example1  &lt;[n]|u&gt; An array of numbers, or undefined
+    example2  &lt;s|'foo'&gt; A string, default 'foo'
+@*/
+</pre>
+
 <p>foo bar</p>
 
 <pre class="code" id="foo">//@ My.TYPES &lt;number&gt; Request timeout, in seconds
@@ -68,7 +126,7 @@ My.readURL &lt;f&gt; Reads data from a remote URL
         timeout &lt;n|60&gt; Timeout in seconds
         type &lt;s|'GET'&gt; Request type ('GET', 'POST', 'PUT' or 'DELETE')
     callback &lt;f&gt; Callback function
-        result &lt;o> Result object
+        result &lt;o&gt; Result object
             status &lt;n&gt; HTTP status code
             data &lt;s&gt; Data read from URL, or empty string
 @*/