diff --git a/source/Ox/js/JavaScript.js b/source/Ox/js/JavaScript.js index f383b7cd..557b1ce5 100644 --- a/source/Ox/js/JavaScript.js +++ b/source/Ox/js/JavaScript.js @@ -2,40 +2,41 @@ /*@ Ox.doc Generates documentation for annotated JavaScript + (source) -> <[o]> Array of doc objects + arguments <[o]|u> Arguments (array of doc objects) + Present if the type of the item is + "function". + description 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 File name + line Line number + name Name of the item + properties <[o]|u> Properties (array of doc objects) + Present if the type of the item is + "event", "function" + or "object". + section Section in the file + source <[o]> Source code (array of tokens) + length Length of the token + offset Offset of the token + type Type of the token + See Ox.tokenize for list of types + summary One-line summary + usage <[o]> Usage (array of doc objects) + Present if the type of the item is + "function". + type Type of the item (file, callback) -> undefined + (files, callback) -> undefined + source JavaScript source code file JavaScript file + files <[s]> Array of javascript files callback Callback function doc <[o]> Array of doc objects - arguments <[o]|u> Arguments (array of doc objects) - Present if the type of the item is - "function". - description 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 File name - line Line number - name Name of the item - properties <[o]|u> Properties (array of doc objects) - Present if the type of the item is - "event", "function" - or "object". - section Section in the file - source <[o]> Source code (array of tokens) - length Length of the token - offset Offset of the token - type Type of the token - See Ox.tokenize for list of types - summary One-line summary - usage <[o]> Usage (array of doc objects) - Present if the type of the item is - "function". - type Type of the item - - (source) Array of documentation objects - source JavaScript source code - > Ox.doc("//@ My.FOO Magic constant\nMy.FOO = 23;") - [{"name": "Ox.foo", "summary": "just some string", "type": "string"}] + # > Ox.doc("//@ My.FOO 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 = - re.multiline.exec(token.source)|| re.singleline.exec(token.source) + if (token.type == 'comment' && ( + 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*/) { - var callback, file, ret, source - if (arguments.length == 1) { - source = arguments[0] - ret = parseSource(source); - } else { - file = arguments[0]; - callback = arguments[1]; + return function(/* source | file, callback | files, callback*/) { + var source = arguments.length == 1 ? arguments[0] : void 0, + files = arguments.length == 2 ? Ox.toArray(arguments[0]) : void 0, + callback = arguments[1], + counter = 0, items = []; + files && files.forEach(function(file) { Ox.get(file, function(source) { - callback(parseSource(source, file)); - }); - } - return ret; + items = Ox.merge(items, parseSource(source, file)); + ++counter == files.length && callback(items); + }); + }); + return source ? parseSource(source) : void 0; } }()); @@ -450,6 +439,8 @@ Ox.tokenize Tokenizes JavaScript or "whitespace" source 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