make Ox.doc accept multiple files

This commit is contained in:
rolux 2012-04-09 10:39:02 +02:00
parent 4f63e29082
commit 1651b3f565

View file

@ -2,40 +2,41 @@
/*@ /*@
Ox.doc <f> Generates documentation for annotated JavaScript 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 (file, callback) -> <u> undefined
(files, callback) -> <u> undefined
source <s> JavaScript source code
file <s> JavaScript file file <s> JavaScript file
files <[s]> Array of javascript files
callback <f> Callback function callback <f> Callback function
doc <[o]> Array of doc objects 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() { Ox.doc = (function() {
@ -135,8 +136,9 @@ Ox.doc = (function() {
Ox.tokenize(source).forEach(function(token) { Ox.tokenize(source).forEach(function(token) {
var match; var match;
token.source = source.substr(token.offset, token.length); 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]); blocks.push(match[1]);
tokens.push([]); tokens.push([]);
@ -144,18 +146,6 @@ Ox.doc = (function() {
tokens[tokens.length - 1].push(token); 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) { blocks.forEach(function(block, i) {
var item, lastItem, var item, lastItem,
lines = block lines = block
@ -263,7 +253,7 @@ Ox.doc = (function() {
function parseType(str) { function parseType(str) {
// returns {types: [""]} // returns {types: [""]}
// or {types: [""], default: ""} // or {types: [""], default: ""}
// or {types: [""], parent: ""} // or {types: [""], super: ""}
var isArray, var isArray,
ret = {types: []}, ret = {types: []},
split, split,
@ -273,7 +263,7 @@ Ox.doc = (function() {
split = str.split(':'); split = str.split(':');
str = split[0]; str = split[0];
if (split.length == 2) { if (split.length == 2) {
ret.parent = split[1]; ret.super = split[1];
} }
} }
str.split('|').forEach(function(str) { str.split('|').forEach(function(str) {
@ -298,19 +288,18 @@ Ox.doc = (function() {
} }
return ret; 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) { 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> or <code>"whitespace"</code>
source <s> JavaScript source 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() { Ox.tokenize = (function() {
// see https://github.com/mozilla/narcissus/blob/master/lib/jslex.js // see https://github.com/mozilla/narcissus/blob/master/lib/jslex.js