0x2620/oxjs
2
0
Fork 1
Code Issues 172 Pull requests Releases Wiki Activity

update documentation example

Browse source
This commit is contained in:
rolux 2012-06-23 16:47:08 +02:00
parent 4e8c8f6310
commit ed6a76ae24
1 changed files with 155 additions and 92 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

247
examples/documentation/oxdoc/js/example.js
View file

@ -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
it doesn't, its meaning depends on its context.
*/
this.My = {};
/*
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
/*
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 = 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
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> ...
@ -75,32 +92,43 @@ My.favorites = (function() {
other: document
},
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> ...
replace <array> ...
0 <regexp> ...
1 <string> replace
My.HTMLUtils <o> HTML Utilities
namedEntities <[s]> Named HTML entities
replace <o> Entity decoding utilities
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() {
var entities = {
'"': '&quot;', '&': '&amp;', "'": '&apos;', '<': '&lt;', '>': '&gt;'
};
var chars = '"&\'<>',
entities = ['&quot;', '&amp;', '&apos;', '&lt;', '&gt;'];
return {
entities: entities,
namedEntities: entities,
replace: {
namedEntity: [
new RegExp('(' + Ox.values(entities).join('|') + ')', 'g'),
namedEntities: [
new RegExp('(' + entities.join('|') + ')', 'g'),
function(match) {
return Ox.keyOf(entities, match);
return chars[entities.indexOf(match)];
}
],
numericEntity: [
numericEntities: [
/&#([0-9A-FX]+);/gi,
function(match, code) {
return Ox.char(
return String.fromCharCode(
/^X/i.test(code)
? parseInt(code.slice(1), 16)
: parseInt(code, 10)
@ -111,83 +139,63 @@ My.HTMLUtils = (function() {
};
}());
/*@
My.defaultPlace <o> Default place object
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}
]
};
/*
The beginning of another section, named '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 <s> URL
method <s|'GET'> Request method ('GET', 'POST', 'PUT' or 'DELETE')
callback <f> Callback function
Please note that the return value of `My.readURL` may change in the
future.
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) {
var request = new XMLHttpRequest();
if (Ox.isFunction(url)) {
url = url();
}
if (arguments.length == 2) {
callback = method;
method = 'GET';
}
request.open(method, url, true);
req.onreadystatechange = function() {
request.onreadystatechange = function() {
if (request.readyState == 4) {
if (request.status == 200) {
callback(request.responseText);
callback(request.responseText, null);
} else {
throw new Error(
'Cannot get URL "' + url
+ '" (Status: ' + request.status + ')'
);
callback(null, {
code: request.status,
text: request.statusText
});
}
}
};
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
(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
`(required[, optional])` notation. For a range function — `(stop)` or `(start,
stop)` or `(start, stop, step)` — the notation `([start, ]stop[, step])` would
be ambigious, since you cannot call it with `(stop, step)`.
Another case for multiple `(arguments) -> <type> summary` lines are functions
whose signature cannot be represented in `(required[, optional])` notation. For
a range function — `(stop)` or `(start, stop)` or `(start, stop, step)` — the
notation `([start, ]stop[, step])` would be ambigious, since you cannot call it
with `(stop, step)`.
*/
/*@
My.range <f> Returns a python-style range
@ -226,6 +235,10 @@ My.range = function() {
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
(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() {
var path = Ox.PATH + '../examples/documentation/js/';
Ox.print(path, '??')
Ox.DocPanel({
files: 'example.js',
path: path
}).appendTo(Ox.$body);
var file = 'example.js',
path = Ox.PATH + '../examples/documentation/oxdoc/js/';
Ox.get(path + file, function(source) {
var doc = Ox.doc(source);
Ox.TabPanel({
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);
});
});