make Ox.doc accept multiple files
This commit is contained in:
parent
4f63e29082
commit
1651b3f565
1 changed files with 49 additions and 58 deletions
|
@ -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
|
||||||
|
|
Loading…
Reference in a new issue