update documentation example
This commit is contained in:
parent
4e8c8f6310
commit
ed6a76ae24
1 changed files with 155 additions and 92 deletions
|
@ -1,36 +1,53 @@
|
||||||
|
'use strict';
|
||||||
/*
|
/*
|
||||||
An Ox.doc comment looks like this `//@ foo` or
|
An OxDoc comment is an inline or multi-line comment that starts with `@`:
|
||||||
```
|
```
|
||||||
|
//@ ...
|
||||||
/*@
|
/*@
|
||||||
foo
|
...
|
||||||
bar
|
*/
|
||||||
baz
|
|
||||||
*\/
|
|
||||||
```
|
```
|
||||||
The syntax is simple: almost every line has the form `name <type> summary`. If
|
The syntax is simple: almost every line has the form `name <type> summary`. If
|
||||||
it doesn't, its meaning depends on its context.
|
it doesn't, its meaning depends on its context.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
this.My = {};
|
this.My = {};
|
||||||
|
|
||||||
/*
|
/*
|
||||||
If the first line of the comment doesn't match `name <type> summary`, it is a
|
If the first line of the comment doesn't match `name <type> summary`, it is a
|
||||||
section definition. Here, we mark a section named 'Primitives'.
|
section definition. Here, it marks a section named 'Primitives'.
|
||||||
*/
|
*/
|
||||||
//@ Primitives
|
//@ Primitives
|
||||||
|
|
||||||
|
/*
|
||||||
|
This inline comment documents an item by providing its name, type and one-line
|
||||||
|
summary.
|
||||||
|
*/
|
||||||
//@ My.REQUEST_TIMEOUT <number> Request timeout, in milliseconds
|
//@ My.REQUEST_TIMEOUT <number> Request timeout, in milliseconds
|
||||||
My.REQUEST_TIMEOUT = 60000;
|
My.REQUEST_TIMEOUT = 60000;
|
||||||
|
|
||||||
|
/*
|
||||||
|
In a multiline comment, lines that follow the inital definition are indented, as
|
||||||
|
they refer to the item defined in the line above. Lines that don't match `name
|
||||||
|
<type> summary` are parsed as a description. Like the summary, the description
|
||||||
|
can contain `markdown`.
|
||||||
|
*/
|
||||||
/*@
|
/*@
|
||||||
My.MAGIC_CONSTANT <number> Magic constant, needed for HTTP requests
|
My.MAGIC_CONSTANT <number> Magic constant, needed for HTTP requests
|
||||||
Please note that the value for `MAGIC_CONSTANT` is browser-dependent.
|
Please note that the value of `My.MAGIC_CONSTANT` (either `23` or `42`) is
|
||||||
|
browser-dependent.
|
||||||
*/
|
*/
|
||||||
My.MAGIC_CONSTANT = navigator.userAgent.length % 2 == 0 ? 23 : 42;
|
My.MAGIC_CONSTANT = navigator.userAgent.length % 2 ? 23 : 42;
|
||||||
|
|
||||||
Ox.load(function() {
|
|
||||||
//@ Objects
|
|
||||||
/*
|
/*
|
||||||
|
This defines a new section named 'Objects'.
|
||||||
|
*/
|
||||||
|
//@ Objects
|
||||||
|
|
||||||
|
/*
|
||||||
|
Lines that start with `#` are inline comments. The follwing lines document
|
||||||
|
properties of the `My.favorites` object. This example shows all possible values
|
||||||
|
for `type`. These values can be shortened, it's sufficient to specify their
|
||||||
|
first character.
|
||||||
*/
|
*/
|
||||||
/*@
|
/*@
|
||||||
My.favorites <object> ...
|
My.favorites <object> ...
|
||||||
|
@ -75,32 +92,43 @@ My.favorites = (function() {
|
||||||
other: document
|
other: document
|
||||||
},
|
},
|
||||||
keys = Object.keys(favorites);
|
keys = Object.keys(favorites);
|
||||||
return Ox.extend(favorites, {any: favorites[keys[Ox.random(keys.length)]]});
|
favorites.any = favorites[keys[Math.floor(Math.random() * keys.length)]];
|
||||||
|
return favorites;
|
||||||
}());
|
}());
|
||||||
|
|
||||||
|
/*
|
||||||
|
Documentation can be nested. In other words, one can document the properties of
|
||||||
|
a property (of a property...). Also, if all elements of an array are of a known
|
||||||
|
type (in this case `string`), one can mark the type as `<[s]>` instead of just
|
||||||
|
`<array>`.
|
||||||
|
*/
|
||||||
/*@
|
/*@
|
||||||
My.HTMLUtils <object> ...
|
My.HTMLUtils <o> HTML Utilities
|
||||||
replace <array> ...
|
namedEntities <[s]> Named HTML entities
|
||||||
0 <regexp> ...
|
replace <o> Entity decoding utilities
|
||||||
1 <string> replace
|
namedEntities <a> Can be passed to `String.prototype.replace`
|
||||||
|
0 <r> Matches named entities
|
||||||
|
1 <f> Decodes named entities
|
||||||
|
numericEntities <a> Can be passed to `String.prototype.replace`
|
||||||
|
0 <r> Matches numeric entities
|
||||||
|
1 <f> Decodes numeric entities
|
||||||
*/
|
*/
|
||||||
My.HTMLUtils = (function() {
|
My.HTMLUtils = (function() {
|
||||||
var entities = {
|
var chars = '"&\'<>',
|
||||||
'"': '"', '&': '&', "'": ''', '<': '<', '>': '>'
|
entities = ['"', '&', ''', '<', '>'];
|
||||||
};
|
|
||||||
return {
|
return {
|
||||||
entities: entities,
|
namedEntities: entities,
|
||||||
replace: {
|
replace: {
|
||||||
namedEntity: [
|
namedEntities: [
|
||||||
new RegExp('(' + Ox.values(entities).join('|') + ')', 'g'),
|
new RegExp('(' + entities.join('|') + ')', 'g'),
|
||||||
function(match) {
|
function(match) {
|
||||||
return Ox.keyOf(entities, match);
|
return chars[entities.indexOf(match)];
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
numericEntity: [
|
numericEntities: [
|
||||||
/&#([0-9A-FX]+);/gi,
|
/&#([0-9A-FX]+);/gi,
|
||||||
function(match, code) {
|
function(match, code) {
|
||||||
return Ox.char(
|
return String.fromCharCode(
|
||||||
/^X/i.test(code)
|
/^X/i.test(code)
|
||||||
? parseInt(code.slice(1), 16)
|
? parseInt(code.slice(1), 16)
|
||||||
: parseInt(code, 10)
|
: parseInt(code, 10)
|
||||||
|
@ -111,83 +139,63 @@ My.HTMLUtils = (function() {
|
||||||
};
|
};
|
||||||
}());
|
}());
|
||||||
|
|
||||||
/*@
|
/*
|
||||||
My.defaultPlace <o> Default place object
|
The beginning of another section, named 'Functions'.
|
||||||
geometry <o>
|
*/
|
||||||
bounds <o> ..
|
|
||||||
northEast <o>
|
|
||||||
lat <n>
|
|
||||||
lng <n>
|
|
||||||
southWest <o>
|
|
||||||
lat <n>
|
|
||||||
lng <n>
|
|
||||||
types <[s]>
|
|
||||||
name <o> Localized place names
|
|
||||||
short <o> Short place name
|
|
||||||
de <s> Short German name
|
|
||||||
en <s> Short English name
|
|
||||||
fr <s> Short French name
|
|
||||||
long <o> Long place name
|
|
||||||
de <s> Long German name
|
|
||||||
en <s> Long English name
|
|
||||||
fr <s> Long French name
|
|
||||||
points <[o]> Points of interest
|
|
||||||
lat <n> Latitude
|
|
||||||
lng <n> Longitude
|
|
||||||
@*/
|
|
||||||
My.place = {
|
|
||||||
bounds: {
|
|
||||||
northEast: {lat: 0, lng: 0},
|
|
||||||
southWest: {lat: 0, lng: 0}
|
|
||||||
},
|
|
||||||
name: {
|
|
||||||
short: {
|
|
||||||
de: 'Brüssel',
|
|
||||||
en: 'Brussels',
|
|
||||||
fr: 'Bruxelles'
|
|
||||||
},
|
|
||||||
long: {
|
|
||||||
de: 'Brüssel, Belgien',
|
|
||||||
en: 'Brussels, Belgium',
|
|
||||||
fr: 'Bruxelles, Belgique'
|
|
||||||
}
|
|
||||||
},
|
|
||||||
points: [
|
|
||||||
{lat: 0, lng: 0},
|
|
||||||
{lat: 45, lng: 90}
|
|
||||||
]
|
|
||||||
};
|
|
||||||
|
|
||||||
//@ Functions
|
//@ Functions
|
||||||
|
|
||||||
|
/*
|
||||||
|
In the case of a function, the indented lines don't document properties, but the
|
||||||
|
function's signature, return value and arguments. Signature and return value are
|
||||||
|
just a special case of `name <type> summary`, where `name` has the form
|
||||||
|
`(arguments) ->`. If an item can be of more than one type (in this case `string`
|
||||||
|
or `function`), this is documented as `<s|f>`. If it has a default value (in
|
||||||
|
this case the string `'GET'`), this is documented as `<s|'GET'>`. In the case of
|
||||||
|
a `function`-type argument (usually a callback function), there is no return
|
||||||
|
value to document, only the arguments it gets passed.
|
||||||
|
*/
|
||||||
/*@
|
/*@
|
||||||
|
My.readURL <f> Asynchronously reads a remote resource
|
||||||
(url[, method], callback) -> <u> undefined
|
(url[, method], callback) -> <u> undefined
|
||||||
url <s> URL
|
Please note that the return value of `My.readURL` may change in the
|
||||||
method <s|'GET'> Request method ('GET', 'POST', 'PUT' or 'DELETE')
|
future.
|
||||||
callback <f> Callback function
|
url <s|f> Remote URL, or function that returns one
|
||||||
|
method <s|'GET'> Request method ('GET', 'POST', 'PUT' or 'DELETE')
|
||||||
|
callback <f> Callback function
|
||||||
|
result <s|null> Response text, or `null` in case of an error
|
||||||
|
error <o|null> Error object, or `null` in case of success
|
||||||
|
code <n> Error code
|
||||||
|
text <s> Error text
|
||||||
*/
|
*/
|
||||||
My.readURL = function(url, method, callback) {
|
My.readURL = function(url, method, callback) {
|
||||||
var request = new XMLHttpRequest();
|
var request = new XMLHttpRequest();
|
||||||
|
if (Ox.isFunction(url)) {
|
||||||
|
url = url();
|
||||||
|
}
|
||||||
if (arguments.length == 2) {
|
if (arguments.length == 2) {
|
||||||
callback = method;
|
callback = method;
|
||||||
method = 'GET';
|
method = 'GET';
|
||||||
}
|
}
|
||||||
request.open(method, url, true);
|
request.open(method, url, true);
|
||||||
req.onreadystatechange = function() {
|
request.onreadystatechange = function() {
|
||||||
if (request.readyState == 4) {
|
if (request.readyState == 4) {
|
||||||
if (request.status == 200) {
|
if (request.status == 200) {
|
||||||
callback(request.responseText);
|
callback(request.responseText, null);
|
||||||
} else {
|
} else {
|
||||||
throw new Error(
|
callback(null, {
|
||||||
'Cannot get URL "' + url
|
code: request.status,
|
||||||
+ '" (Status: ' + request.status + ')'
|
text: request.statusText
|
||||||
);
|
});
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
};
|
};
|
||||||
request.send();
|
request.send();
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/*
|
||||||
|
If a function's return value depends on the absence or presence of optional
|
||||||
|
arguments, there can be multiple `(arguments) -> <type> summary` lines.
|
||||||
|
*/
|
||||||
/*@
|
/*@
|
||||||
My.isOdd <f> Synchronously or asynchronously computes if a given number is odd
|
My.isOdd <f> Synchronously or asynchronously computes if a given number is odd
|
||||||
(number) -> <b> True if the number is odd
|
(number) -> <b> True if the number is odd
|
||||||
|
@ -207,10 +215,11 @@ My.isOdd = function(number, callback) {
|
||||||
};
|
};
|
||||||
|
|
||||||
/*
|
/*
|
||||||
Occasionally, you may write a function whose signature cannot be represented in
|
Another case for multiple `(arguments) -> <type> summary` lines are functions
|
||||||
`(required[, optional])` notation. For a range function — `(stop)` or `(start,
|
whose signature cannot be represented in `(required[, optional])` notation. For
|
||||||
stop)` or `(start, stop, step)` — the notation `([start, ]stop[, step])` would
|
a range function — `(stop)` or `(start, stop)` or `(start, stop, step)` — the
|
||||||
be ambigious, since you cannot call it with `(stop, step)`.
|
notation `([start, ]stop[, step])` would be ambigious, since you cannot call it
|
||||||
|
with `(stop, step)`.
|
||||||
*/
|
*/
|
||||||
/*@
|
/*@
|
||||||
My.range <f> Returns a python-style range
|
My.range <f> Returns a python-style range
|
||||||
|
@ -226,6 +235,10 @@ My.range = function() {
|
||||||
return a;
|
return a;
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/*
|
||||||
|
In case a function has a property or method one wants to document, it gets
|
||||||
|
prefixed with `.`, in order to differentiate it from an argument.
|
||||||
|
*/
|
||||||
/*@
|
/*@
|
||||||
My.localStorage <f> Returns a localStorage handler for a given namespace
|
My.localStorage <f> Returns a localStorage handler for a given namespace
|
||||||
(ns) -> storage <f> localStorage handler
|
(ns) -> storage <f> localStorage handler
|
||||||
|
@ -278,13 +291,63 @@ My.localStorage = (function() {
|
||||||
};
|
};
|
||||||
}());
|
}());
|
||||||
|
|
||||||
});
|
/*
|
||||||
|
And one more section, named 'UI Elements'.
|
||||||
|
*/
|
||||||
|
//@ UI Element
|
||||||
|
|
||||||
|
/*@
|
||||||
|
My.Box <f> A very simple colored box
|
||||||
|
options <o> Options
|
||||||
|
color <[n]> RGB value
|
||||||
|
self <o> Shared private object
|
||||||
|
([options[, self]]) -> <o> Box object
|
||||||
|
grayscale <!> Fires when changing the color of the box to grayscale
|
||||||
|
color <n> Value between `0` and `255`
|
||||||
|
*/
|
||||||
|
My.Box = function(options, self) {
|
||||||
|
self = self || {};
|
||||||
|
var that = Ox.Element({}, self)
|
||||||
|
.defaults({color: [255, 0, 0]})
|
||||||
|
.options(options || {})
|
||||||
|
.update(setColor)
|
||||||
|
.css({width: '256px', height: '256px'});
|
||||||
|
function setColor() {
|
||||||
|
that.css({background: 'rgb(' + self.options.color.join(', ') + ')'});
|
||||||
|
}
|
||||||
|
/*@
|
||||||
|
.toGrayscale <f> Changes the color of the box to grayscale.
|
||||||
|
() -> <o> The box object
|
||||||
|
*/
|
||||||
|
that.toGrayscale = function() {
|
||||||
|
return that.options({
|
||||||
|
color: Ox.repeat([Ox.avg(self.options.color)], 3)
|
||||||
|
}).triggerEvent('grayscale', {color: self.options.color[0]});
|
||||||
|
};
|
||||||
|
return that;
|
||||||
|
};
|
||||||
|
|
||||||
//@
|
//@
|
||||||
Ox.load('UI', function() {
|
Ox.load('UI', function() {
|
||||||
var path = Ox.PATH + '../examples/documentation/js/';
|
var file = 'example.js',
|
||||||
Ox.print(path, '??')
|
path = Ox.PATH + '../examples/documentation/oxdoc/js/';
|
||||||
Ox.DocPanel({
|
Ox.get(path + file, function(source) {
|
||||||
files: 'example.js',
|
var doc = Ox.doc(source);
|
||||||
path: path
|
Ox.TabPanel({
|
||||||
}).appendTo(Ox.$body);
|
content: {
|
||||||
|
source: Ox.SyntaxHighlighter({source: path + file}),
|
||||||
|
doc: Ox.TreeList({data: doc}),
|
||||||
|
docpanel: Ox.DocPanel({
|
||||||
|
expanded: true,
|
||||||
|
files: 'example.js',
|
||||||
|
path: path
|
||||||
|
})
|
||||||
|
},
|
||||||
|
tabs: [
|
||||||
|
{id: 'source', title: 'source'},
|
||||||
|
{id: 'doc', title: 'doc = Ox.doc(source)'},
|
||||||
|
{id: 'docpanel', title: 'Ox.DocPanel({items: doc})'}
|
||||||
|
]
|
||||||
|
}).appendTo(Ox.$body);
|
||||||
|
});
|
||||||
});
|
});
|
||||||
|
|
Loading…
Reference in a new issue