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

This commit is contained in:
rolux 2012-05-29 13:48:54 +02:00
parent c5fdc1ab39
commit 38016aa06b

View file

@ -3,32 +3,6 @@
/*@
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.sanitizeHTML 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)
column <n> Column
line <n> Line
type <s> Type (see Ox.tokenize for a list of types)
value <s> Value
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>.
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
@ -36,14 +10,65 @@ Ox.doc <f> Generates documentation for annotated JavaScript
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"}]
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.sanitizeHTML 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)
column <n> Column
line <n> Line
type <s> Type (see Ox.tokenize for a list of types)
value <s> Value
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>.
tests <[o]> Tests (array of test objects)
type <s> Type of the item
<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\()/;