Ox.doc: add tests; Ox.test: add documentation

source/Ox/js/JavaScript.js

@@ -3,6 +3,13 @@
 /*@
 Ox.doc <f> Generates documentation for annotated JavaScript
     (source) -> <[o]> Array of doc objects
+    (file, callback) -> <u> undefined
+    (files, callback) -> <u> undefined
+    source <s> JavaScript source code
+    file <s> JavaScript file
+    files <[s]> Array of javascript files
+    callback <f> Callback function
+        doc <[o]> Array of doc objects
             arguments <[o]|u> Arguments (array of doc objects)
                 Present if the <code>type</code> of the item is
                 <code>"function"</code>.
@@ -29,21 +36,39 @@ Ox.doc <f> Generates documentation for annotated JavaScript
                 <code>"function"</code>.
             tests <[o]> Tests (array of test objects)
             type <s> Type of the item
-    (file, callback) -> <u> undefined
-    (files, callback) -> <u> undefined
-    source <s> JavaScript source code
-    file <s> JavaScript file
-    files <[s]> Array of javascript files
-    callback <f> Callback function
-        doc <[o]> Array of doc objects
-    # > Ox.doc("//@ My.FOO <n> Magic constant\nMy.FOO = 23;")
-    # [{"name": "Ox.foo", "summary": "Magic constant", "type": "number"}]
+    <script>
+        Ox.test.doc = Ox.doc(
+            '//@ My.FOO <n> Magic constant\n' +
+            'My.FOO = 23;\n' +
+            '\n' +
+            '/*@\n'+
+            'My.foo <f> Returns an items\'s bar per baz\n' +
+            '    Bar per baz is a good indicator of an item\'s foo-ness.\n' +
+            '    (item) -> <n> Bar per baz, or NaN\n' +
+            '    item <o> Any item\n' +
+            '@*' + '/\n' +
+            'My.foo = function(item) {\n' +
+            '    return item.bar / item.baz;\n' +
+            '}'
+        );
+    </script>
+    > Ox.test.doc[0].name
+    'My.FOO'
+    > Ox.test.doc[0].types
+    ['number']
+    > Ox.test.doc[0].summary
+    'Magic constant'
+    > Ox.test.doc[1].description
+    'Bar per baz is a good indicator of an item\'s foo-ness.'
+    > Ox.test.doc[1].usage[0].types
+    ['number']
+    > Ox.test.doc[1].usage[0].summary
+    'Bar per baz, or NaN'
 @*/
 Ox.doc = (function() {
-    // fixme: dont require the trailing '@'
     var re = {
             item: /^(.+?) <(.+?)> (.+?)$/,
-            multiline: /^\/\*\@.*?\n([\w\W]+)\n.*?\@\*\/$/,
+            multiline: /^\/\*\@.*?\n([\w\W]+)\n.*?\@?\*\/$/,
             script: /\n(\s*<script>s*\n[\w\W]+\n\s*<\/script>s*)/g,
             singleline: /^\/\/@\s*(.*?)\s*$/,
             test: /\n(\s*> .+\n.+?)/g,
@@ -542,6 +567,18 @@ Ox.minify = function() {
 
 /*@
 Ox.test <f> Takes JavaScript, runs inline tests, returns results
+    (file, callback) -> <u> undefined
+    (files, callback) -> <u> undefines
+    file <s> Path to JavaScript file
+    files <[s]> List of paths to J
+    callback <f> Callback function
+        results [<o>] Array of results
+            actual <s> Actual result
+            expected <s> Expected result
+            name <s> Item name
+            section <s> Section in the file
+            statement <s> Test statement
+            passed <b> True if actual result and expected result are equal
 @*/
 Ox.test = function(file, callback) {
     var regexp = /(Ox\.test\()/;