make Ox.doc accept multiple files

source/Ox/js/JavaScript.js

@@ -2,40 +2,41 @@
 
 /*@
 Ox.doc <f> Generates documentation for annotated JavaScript
+    (source) -> <[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>.
+        description <s|u> Multi-line description with optional markup
+            See Ox.parseHTML for details
+        events <[o]|u> Events (array of doc objects)
+            Present if the item fires any events
+        file <s> File name
+        line <n> Line number
+        name <s> Name of the item
+        properties <[o]|u> Properties (array of doc objects)
+            Present if the <code>type</code> of the item is
+            <code>"event"</code>, <code>"function"</code>
+            or <code>"object"</code>.
+        section <s|u> Section in the file
+        source <[o]> Source code (array of tokens)
+            length <n> Length of the token
+            offset <n> Offset of the token
+            type <s> Type of the token
+                See Ox.tokenize for list of types
+        summary <s> One-line summary
+        usage <[o]> Usage (array of doc objects)
+            Present if the <code>type</code> of the item is
+            <code>"function"</code>.
+        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
-            arguments <[o]|u> Arguments (array of doc objects)
+    # > Ox.doc("//@ My.FOO <n> Magic constant\nMy.FOO = 23;")
-                Present if the <code>type</code> of the item is
+    # [{"name": "Ox.foo", "summary": "just some string", "type": "string"}]
-                <code>"function"</code>.
-            description <s|u> Multi-line description with optional markup
-                See Ox.parseHTML for details
-            events <[o]|u> Events (array of doc objects)
-                Present if the item fires any events
-            file <s> File name
-            line <n> Line number
-            name <s> Name of the item
-            properties <[o]|u> Properties (array of doc objects)
-                Present if the <code>type</code> of the item is
-                <code>"event"</code>, <code>"function"</code>
-                or <code>"object"</code>.
-            section <s|u> Section in the file
-            source <[o]> Source code (array of tokens)
-                length <n> Length of the token
-                offset <n> Offset of the token
-                type <s> Type of the token
-                    See Ox.tokenize for list of types
-            summary <s> One-line summary
-            usage <[o]> Usage (array of doc objects)
-                Present if the <code>type</code> of the item is
-                <code>"function"</code>.
-            type <s> Type of the item
-            
-    (source) <a> Array of documentation objects
-    source <s> JavaScript source code
-    > Ox.doc("//@ My.FOO <n> Magic constant\nMy.FOO = 23;")
-    [{"name": "Ox.foo", "summary": "just some string", "type": "string"}]
 @*/
 
 Ox.doc = (function() {
@@ -135,8 +136,9 @@ Ox.doc = (function() {
         Ox.tokenize(source).forEach(function(token) {
             var match;
             token.source = source.substr(token.offset, token.length);
-            if (token.type == 'comment' && (match =
+            if (token.type == 'comment' && (
-                re.multiline.exec(token.source)|| re.singleline.exec(token.source)
+                match = re.multiline.exec(token.source)
+                || re.singleline.exec(token.source)
             )) {
                 blocks.push(match[1]);
                 tokens.push([]);
@@ -144,18 +146,6 @@ Ox.doc = (function() {
                 tokens[tokens.length - 1].push(token);
             }
         });
-        /*
-        var blocks = Ox.map(Ox.tokenize(source), function(token) {
-                // filter out tokens that are not comments
-                // or don't match the doc comment pattern
-                var match;
-                token.source = source.substr(token.offset, token.length);
-                return token.type == 'comment' && (match = 
-                    re.multiline(token.source) || re.singleline(token.source)
-                ) ? match[1] : null;
-            }),
-            items = [];
-        */
         blocks.forEach(function(block, i) {
             var item, lastItem,
                 lines = block
@@ -263,7 +253,7 @@ Ox.doc = (function() {
     function parseType(str) {
         // returns {types: [""]}
         // or {types: [""], default: ""}
-        // or {types: [""], parent: ""}
+        // or {types: [""], super: ""}
         var isArray,
             ret = {types: []},
             split,
@@ -273,7 +263,7 @@ Ox.doc = (function() {
             split = str.split(':');
             str = split[0];
             if (split.length == 2) {
-                ret.parent = split[1];
+                ret.super = split[1];
             }
         }
         str.split('|').forEach(function(str) {
@@ -298,19 +288,18 @@ Ox.doc = (function() {
         }
         return ret;
     }
-    return function(/*source or file, callback*/) {
+    return function(/* source | file, callback | files, callback*/) {
-        var callback, file, ret, source
+        var source = arguments.length == 1 ? arguments[0] : void 0,
-        if (arguments.length == 1) {
+            files = arguments.length == 2 ? Ox.toArray(arguments[0]) : void 0,
-            source = arguments[0]
+            callback = arguments[1],
-            ret = parseSource(source);
+            counter = 0, items = [];
-        } else {
+        files && files.forEach(function(file) {
-            file = arguments[0];
-            callback = arguments[1];
             Ox.get(file, function(source) {
-                callback(parseSource(source, file));
+                items = Ox.merge(items, parseSource(source, file));
-            });
+                ++counter == files.length && callback(items);
-        }
+            });                
-        return ret;
+        });
+        return source ? parseSource(source) : void 0;
     }
 }());
 
@@ -450,6 +439,8 @@ Ox.tokenize <f> Tokenizes JavaScript
             or <code>"whitespace"</code>
     source <s> JavaScript source code
 @*/
+// FIXME: constant/method/object/property is of interest
+// for syntax highlighting, but may not belong here
 Ox.tokenize = (function() {
 
     // see https://github.com/mozilla/narcissus/blob/master/lib/jslex.js