in documentation use foo, not <code>foo</code>

This commit is contained in:
rolux 2012-06-02 13:06:44 +02:00
parent bd5a4b6318
commit 73fa856900
16 changed files with 89 additions and 105 deletions

View file

@ -6,8 +6,8 @@ Ox.load.Image = function(options, callback) {
/*@
Ox.Image <f> Generic image object
To render the image as an image element, use its <code>src()</code>
method, to render it as a canvas, use its <code>canvas</code> property.
To render the image as an image element, use its `src()` method, to
render it as a canvas, use its `canvas` property.
(src, callback) -> <u> undefined
(width, height, callback) -> <u> undefined
(width, height, background, callback) -> <u> undefined
@ -187,7 +187,7 @@ Ox.load.Image = function(options, callback) {
/*@
drawCircle <f> Draws a circle
(point, radius, options) -> <o> The image object
point <[n]> Center (<code>[x, y]</code>)
point <[n]> Center (`[x, y]`)
radius <n> Radius in px
options <o> Options
color <s|'rgb(0, 0, 0)'> CSS color
@ -206,7 +206,7 @@ Ox.load.Image = function(options, callback) {
/*@
drawLine <f> Draws a line
(points, options) -> <o> The image object
points <[a]> End points (<code>[[x1, y1], [x2, y2]]</code>)
points <[a]> End points (`[[x1, y1], [x2, y2]]`)
options <o> Options
color <s|'rgb(0, 0, 0)'> CSS color
width <n|1> Line width in px
@ -223,7 +223,7 @@ Ox.load.Image = function(options, callback) {
/*@
drawPath <f> Draws a path
(points, options) -> <o> The image object
points <[a]> Points (<code>[[x1, y2], [x2, y2], ...]</code>)
points <[a]> Points (`[[x1, y2], [x2, y2], ...]`)
options <o> Options
color <s|'rgb(0, 0, 0)'> CSS color
fill <s|'rgba(0, 0, 0, 0)'> CSS color
@ -245,8 +245,8 @@ Ox.load.Image = function(options, callback) {
/*@
drawRectangle <f> Draws a rectangle
(point, size, options) -> <o> The image object
point <[n]> Top left corner (<code>[x, y]</code>)
size <[n]> Width and height in px (<code>[w, h]</code>)
point <[n]> Top left corner (`[x, y]`)
size <[n]> Width and height in px (`[w, h]`)
options <o> Options
color <s|'rgb(0, 0, 0)'> CSS color
fill <s|'rgba(0, 0, 0, 0)'> CSS color
@ -263,7 +263,7 @@ Ox.load.Image = function(options, callback) {
drawText <f> Draws text
(text, point, options) -> <o> The image object
text <s> Text
point <[n]> Top left corner (<code>[x, y]</code>)
point <[n]> Top left corner (`[x, y]`)
options <o> Options
color <s|'rgb(0, 0, 0)'> CSS color
font <s|'10px sans-serif'> CSS font
@ -316,9 +316,9 @@ Ox.load.Image = function(options, callback) {
For most purposes, deflate and mode should be omitted, since the
defaults make the existence of the message harder to detect. A valid
use case for deflate and mode would be to first encode a more easily
detected decoy string, and only then the secret string: <code>
image.encode(decoy, false, 1, function(image) { image.encode(secret,
-1, callback); })</code>.
detected decoy string, and only then the secret string:
`image.encode(decoy, false, 1, function(image) {
image.encode(secret, -1, callback); })`.
(str, callback) -> <o> The image object (unmodified)
(str, deflate, callback) -> <o> The image object (unmodified)
(str, mode, callback) -> <o> The image object (unmodified)

View file

@ -296,7 +296,7 @@ Ox.Element = function(options, self) {
callback <f> Callback function
data <o> event data (key/value pairs)
event <s> Event name
Event names can be namespaced, like <code>'click.foo'</code>
Event names can be namespaced, like `'click.foo'`
@*/
that.bindEvent = function() {
if (Ox.typeOf(arguments[0]) == 'function') {
@ -316,7 +316,7 @@ Ox.Element = function(options, self) {
callback <f> Callback function
data <o> event data (key/value pairs)
event <s> Event name
Event names can be namespaced, like <code>'click.foo'</code>
Event names can be namespaced, like `'click.foo'`
@*/
that.bindEventOnce = function() {
Ox.forEach(Ox.makeObject(arguments), function(callback, event) {
@ -478,8 +478,7 @@ Ox.Element = function(options, self) {
/*@
unbindEvent <function> Unbinds all callbacks from an event
To unbind a specific handler, use namespaced events, like
<code>bindEvent('click.foo', callback)</code>, and then
<code>unbindEvent('click.foo')</code>.
`bindEvent('click.foo', callback)`, and then `unbindEvent('click.foo')`.
() -> <object> This element
Unbinds all callbacks from all events
(callback) -> <o> This element

View file

@ -4,6 +4,7 @@
Ox.Event <o> Basic event handler
@*/
// FIXME: unused
Ox.Event = (function() {
@ -18,7 +19,7 @@ Ox.Event = (function() {
callback <f> Callback function
data <*> Event data
event <s> Event name
Event names can be namespaced, like <code>'click.foo'</code>
Event names can be namespaced, like `'click.foo'`
@*/
that.bind = function() {
Ox.forEach(Ox.makeObject(arguments), function(callback, event) {
@ -38,7 +39,7 @@ Ox.Event = (function() {
callback <f> Callback function
data <*> Event data
event <s> Event name
Event names can be namespaced, like <code>'click.foo'</code>
Event names can be namespaced, like `'click.foo'`
@*/
that.bindOnce = function() {
Ox.forEach(Ox.makeObject(arguments), function(callback, event) {
@ -68,8 +69,7 @@ Ox.Event = (function() {
/*@
unbind <f> Unbinds all callbacks from an event
To unbind a specific handler, use namespaced events, like
<code>bind('click.foo', callback)</code>, and then
<code>unbind('click.foo')</code>.
`bind('click.foo', callback)`, and then `unbind('click.foo')`.
() -> <o> The event handler
Unbinds all events
(event) -> <o> The event handler

View file

@ -3,9 +3,8 @@
/*@
Ox.Map <f> Basic map object
# DESCRIPTION --------------------------------------------------------------
<code>Ox.Map</code> is a wrapper around the
<a href="http://code.google.com/apis/maps/documentation/javascript/">Google
Maps API</a>.
`Ox.Map` is a wrapper around the [Google Maps
API](http://code.google.com/apis/maps/documentation/javascript/).
# ARGUMENTS ----------------------------------------------------------------
options <o|{}> options
clickable <b|false> If true, clicking on the map finds a place

View file

@ -5,8 +5,8 @@ Ox.TabPanel <f> Tabbed panel
([options[, self]]) -> <o:Ox.SplitPanel> Panel
options <o> Options
content <o|f> Content per tab
Either <code>({id1: $element1, id2: $element2}}</code> or
<code>function(id) { return $element; })</code>
Either `({id1: $element1, id2: $element2}}` or `function(id) {
return $element; })`
size <n|24> Height of the tab bar
tabs [o] Tabs
id <s> Tab id

View file

@ -101,7 +101,7 @@ Ox.PATH = Ox.toArray(
).reverse().filter(function(element) {
return /Ox\.js$/.test(element.src);
})[0].src.replace(/Ox\.js$/, '');
//@ Ox.PREFIXES <[str]> <code>['', 'K', 'M', 'G', 'T', 'P']</code>
//@ Ox.PREFIXES <[str]> `['', 'K', 'M', 'G', 'T', 'P']`
Ox.PREFIXES = ['', 'K', 'M', 'G', 'T', 'P'];
//@ Ox.SEASONS <[str]> Names of the seasons of the year
Ox.SEASONS = ['Winter', 'Spring', 'Summer', 'Fall'];

View file

@ -76,8 +76,8 @@ Some conventions:
(function(global) {
/*@
Ox <f> The <code>Ox</code> object
See <code>Ox.wrap</code> for details.
Ox <f> The `Ox` object
See `Ox.wrap` for details.
(value) -> <o> wrapped value
value <*> Any value
@*/
@ -87,7 +87,7 @@ Some conventions:
})(this);
/*@
Ox.Break <f> Breaks from <code>Ox.forEach</code> and <code>Ox.loop</code>
Ox.Break <f> Breaks from `Ox.forEach` and `Ox.loop`
@*/
Ox.Break = function() {
throw Ox.BreakError;
@ -97,12 +97,11 @@ Ox.BreakError = new SyntaxError('Illegal Ox.Break() statement');
/*@
Ox.load <f> Loads a module
A module named "Foo" provides <code>Ox.Foo/Ox.Foo.js</code>, in which it
defines one method, <code>Ox.load.Foo</code>, that takes two arguments,
<code>options</code> and <code>callback</code>, and calls
<code>callback</code> with one argument, <code>true</code> for success or
<code>false</code> if an error occurred. Generally, the module should
define <code>Ox.Foo</code> and attach its own methods there.
A module named "Foo" provides `Ox.Foo/Ox.Foo.js`, in which it defines one
method, `Ox.load.Foo`, that takes two arguments, `options` and `callback`,
and calls `callback` with one argument, `true` for success or `false` if an
error occurred. Generally, the module should define `Ox.Foo` and attach its
own methods there.
(module, callback) -> <u> undefined
(module, options, callback) -> <u> undefined
(modules, callback) -> <u> undefined
@ -240,20 +239,19 @@ Ox.Log = (function() {
/*@
Ox.loop <f> For-loop, functional-style
Returning <code>false</code> from the iterator function acts like a
<code>break</code> statement. Unlike a <code>for</code> loop,
<code>Ox.loop</code> doesn't leak its counter variable to the outer scope,
but returns it.
Returning `false` from the iterator function acts like a `break` statement.
Unlike a `for` loop, `Ox.loop` doesn't leak its counter variable to the
outer scope, but returns it.
(stop, fn) -> <n> Next value
equivalent to <code>for (var i = 0; i < stop; i++) { fn(i); }</code>
equivalent to `for (var i = 0; i < stop; i++) { fn(i); }`
(start, stop, fn) -> <n> Next value
equivalent to <code>for (var i = start; i < stop; i++) { fn(i); }</code>
or, if <code>start</code> is larger than <code>stop</code>,
<code>for (var i = start; i > stop; i--) { fn(i); }</code>
equivalent to `for (var i = start; i < stop; i++) { fn(i); }` or, if
`start` is larger than `stop`, `for (var i = start; i > stop; i--) {
fn(i); }`
(start, stop, step, fn) -> <n> Next value
equivalent to <code>for (var i = start; i < stop; i += step) { fn(i);
}</code> or, if <code>step</code> is negative, <code>for (var i = start;
i > stop; i += step) { fn(i); }</code>
equivalent to `for (var i = start; i < stop; i += step) { fn(i); }` or,
if `step` is negative, `for (var i = start; i > stop; i += step) {
fn(i); }`
start <n> Start value
stop <n> Stop value (exclusive)
step <n> Step value
@ -321,10 +319,10 @@ Ox.uid = (function() {
/*@
Ox.wrap <f> Wraps a value so that one can directly call any Ox function on it
<code>Ox(value)</code> is a shorthand for <code>Ox.wrap(value)</code>.
`Ox(value)` is a shorthand for `Ox.wrap(value)`.
(value) -> <o> wrapped value
chain <f> Wrap return values to allow chaining
value <f> Unwrap the value wrapped by <code>chain()</chain>
value <f> Unwrap the value wrapped by `chain()`
value <*> Any value
> Ox("foobar").repeat(2)
"foobarfoobar"

View file

@ -289,8 +289,8 @@ Ox.$ = Ox.element = function(value) {
/*@
Ox.canvas <function> Generic canvas object
# Description --------------------------------------------------------------
Returns an object with the properties: <code>canvas</code>,
<code>context</code>, <code>data</code> and <code>imageData</code>.
Returns an object with the properties: `canvas`, `context`, `data` and
`imageData`.
# Usage --------------------------------------------------------------------
Ox.canvas(width, height) -> <object> canvas
Ox.canvas(image) -> <object> canvas

View file

@ -178,7 +178,7 @@ Ox.getISOYear = function(date, utc) {
//@ Ox.getSeconds <f> Get the seconds of a date
// see Ox.setSeconds for source code
//@ Ox.getTime <f> Alias for <code>+new Date()</code>
//@ Ox.getTime <f> Alias for `+new Date()`
Ox.getTime = function(utc) {
return +new Date() - (utc ? Ox.getTimezoneOffset() : 0);
};

View file

@ -140,11 +140,10 @@ Ox.decodeBase256 = function(string) {
/*@
Ox.encodeDeflate <f> Encodes a string, using deflate
Since PNGs are deflate-encoded, the <code>canvas</code> object's
<code>toDataURL</code> method provides an efficient implementation.
The string is encoded as UTF-8 and written to the RGB channels of a
canvas element, then the PNG dataURL is decoded from base64, and some
head, tail and chunk names are removed.
Since PNGs are deflate-encoded, the `canvas` object's `toDataURL` method
provides an efficient implementation. The string is encoded as UTF-8 and
written to the RGB channels of a canvas element, then the PNG dataURL is
decoded from base64, and some head, tail and chunk names are removed.
(str) -> <s> The encoded string
str <s> The string to be encoded
> Ox.decodeDeflate(Ox.encodeDeflate('foo'), function(str) { Ox.test(str, 'foo'); })
@ -189,11 +188,10 @@ Ox.encodeDeflate = function(string, callback) {
/*@
Ox.decodeDeflate <f> Decodes an deflate-encoded string
Since PNGs are deflate-encoded, the <code>canvas</code> object's
<code>drawImage</code> method provides an efficient implementation. The
string will be wrapped as a PNG dataURL, encoded as base64, and drawn
onto a canvas element, then the RGB channels will be read, and the
result will be decoded from UTF8.
Since PNGs are deflate-encoded, the `canvas` object's `drawImage` method
provides an efficient implementation. The string will be wrapped as a PNG
dataURL, encoded as base64, and drawn onto a canvas element, then the RGB
channels will be read, and the result will be decoded from UTF8.
(str) -> <u> undefined
str <s> The string to be decoded
callback <f> Callback function

View file

@ -200,9 +200,8 @@
(string[, decodeAll]) -> <s> String
string <s> String
decodeAll <b|false> If true, decode named entities for characters > 127
Note that <code>decodeAll</code> relies on
<code>Ox.normalizeHTML</code>, which uses the DOM and may transform
the string
Note that `decodeAll` relies on `Ox.normalizeHTML`, which uses the
DOM and may transform the string
> Ox.decodeHTMLEntities('&#x003C;&#x0027;&#x0026;&#x0022;&#x003E;')
'<\'&">'
> Ox.decodeHTMLEntities('&lt;&apos;&amp;&quot;&gt;')

View file

@ -11,8 +11,7 @@ Ox.doc <f> Generates documentation for annotated JavaScript
callback <f> Callback function
doc <[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>.
Present if the `type` of the item is `"function"`.
class <s|u> Class of the item
default <s|u> Default value of the item
description <s|u> Multi-line description with some Markdown
@ -28,9 +27,8 @@ Ox.doc <f> Generates documentation for annotated JavaScript
order <[s]> Order of returns, arguments, properties
Present if the type of the item is "function"
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>.
May be present if the `type` of the item is `"event"`,
`"function"` or `"object"`.
section <s|u> Section in the file
source <[o]> Source code (array of tokens)
column <n> Column
@ -38,8 +36,7 @@ Ox.doc <f> Generates documentation for annotated JavaScript
type <s> Type (see Ox.tokenize for a list of types)
value <s> Value
returns <[o]> Return values (array of doc objects)
Present if the <code>type</code> of the item is
<code>"function"</code>.
Present if the `type` of the item is `"function"`.
summary <s> One-line summary, with some Markdown
See Ox.parseMarkdown for details
tests <[o]> Tests (array of test objects)
@ -467,9 +464,8 @@ Ox.doc = (function() {
/*@
Ox.identify <f> Returns the type of a JavaScript identifier
(str) -> <s> Type
Type can be <code>constant</code>, <code>identifier</code>,
<code>keyword</code>, <code>method</code>, <code>object</code> or
<code>property</code>
Type can be `constant`, `identifier`, `keyword`, `method`, `object` or
`property`.
@*/
Ox.identify = (function() {
// see https://developer.mozilla.org/en/JavaScript/Reference
@ -852,11 +848,8 @@ Ox.tokenize <f> Tokenizes JavaScript
column <n> Column of the token
line <n> Line of the token
type <s> Type of the token
Type can be <code>"comment"</code>, <code>"error"</code>,
<code>"identifier"</code>, <code>"linebreak"</code>,
<code>"number"</code>, <code>"operator"</code>,
<code>"regexp"</code>, <code>"string"</code> or
<code>"whitespace"</code>
Type can be `"comment"`, `"error"`, `"identifier"`, `"linebreak"`,
`"number"`, `"operator"`, `"regexp"`, `"string"` or `"whitespace"`
value <s> Value of the token
source <s> JavaScript source code
> Ox.tokenize('// comment\nvar foo = bar / baz;').length

View file

@ -2,7 +2,7 @@
/*@
Ox.asinh <f> Inverse hyperbolic sine
Missing from <code>Math</code>.
Missing from `Math`.
> Ox.asinh(0)
0
@*/
@ -12,7 +12,7 @@ Ox.asinh = function(x) {
/*@
Ox.deg <f> Takes radians, returns degrees
Missing from <code>Math</code>.
Missing from `Math`.
> Ox.deg(2 * Math.PI)
360
@*/
@ -22,10 +22,9 @@ Ox.deg = function(rad) {
/*@
Ox.divideInt <f> Divides a number by another and returns an array of integers
<code>Ox.divideInt(num, by)</code> returns a sorted array of integers that
has a sum of <code>num</code>, a length of <code>by</code>, a minimum of
<code>Math.floor(num / by)</code> and a maximum of
<code>Math.ceil(num / by)</code>.
`Ox.divideInt(num, by)` returns a sorted array of integers that has a sum of
`num`, a length of `by`, a minimum of `Math.floor(num / by)` and a maximum
of `Math.ceil(num / by)`.
> Ox.divideInt(100, 3)
[33, 33, 34]
> Ox.divideInt(100, 6)
@ -42,11 +41,11 @@ Ox.divideInt = function(number, by) {
/*@
Ox.limit <f> Limits a number by a given mininum and maximum
<code>Ox.limit(num, min, max)</code> is a shorthand for
<code>Math.min(Math.max(num, min), max)</code>
(num) -> <n> <code>num</code>
(num, max) -> <n> <code>Math.max(num, max)</code>
(num, min, max) -> <n> <code>Math.min(Math.max(num, min), max)</code>
`Ox.limit(num, min, max)` is a shorthand for `Math.min(Math.max(num, min),
max)`
(num) -> <n> `num`
(num, max) -> <n> `Math.max(num, max)`
(num, min, max) -> <n> `Math.min(Math.max(num, min), max)`
num <n> number
min <n> minimum
max <n> maximum
@ -68,7 +67,7 @@ Ox.limit = function(/*number[[, min], max]*/) {
/*@
Ox.log <f> Returns the logarithm of a given number to a given base
Missing from <code>Math</code>.
Missing from `Math`.
> Ox.log(100, 10)
2
> Ox.log(Math.E)
@ -80,8 +79,7 @@ Ox.log = function(number, base) {
/*@
Ox.mod <f> Modulo function
Unlike <code>-1 % 10</code>, which returns <code>-1</code>,
<code>Ox.mod(-1, 10)</code> returns <code>9</code>.
Unlike `-1 % 10`, which returns `-1`, `Ox.mod(-1, 10)` returns `9`.
> Ox.mod(11, 10)
1
> Ox.mod(-11, 10)
@ -93,7 +91,7 @@ Ox.mod = function(number, by) {
/*@
Ox.rad <f> Takes degrees, returns radians
Missing from <code>Math</code>.
Missing from `Math`.
> Ox.rad(360)
2 * Math.PI
@*/
@ -135,7 +133,7 @@ Ox.round = function(number, decimals) {
/*@
Ox.sinh <f> Hyperbolic sine
Missing from <code>Math</code>.
Missing from `Math`.
> Ox.sinh(0)
0
@*/

View file

@ -104,8 +104,8 @@ Ox.keyOf = function(object, value) {
/*@
Ox.makeObject <f> Takes an array and returns an object
<code>Ox.makeObject</code> is a helper for functions with two alternative
signatures like <code>('key', 'val')</code> and <code>({key: 'val'})</code>.
`Ox.makeObject` is a helper for functions with two alternative signatures
like `('key', 'val')` and `({key: 'val'})`.
> (function() { return Ox.makeObject(arguments); }({foo: 1, bar: 2}))
{foo: 1, bar: 2}
> (function() { return Ox.makeObject(arguments); }('foo', 1))

View file

@ -38,8 +38,8 @@ Ox.clean = function(string) {
/*@
Ox.endsWith <f> Checks if a string ends with a given substring
If the substring is a string literal (and not a variable),
<code>/sub$/.test(str)</code> or <code>!!/sub$/.exec(str)</code>
is shorter than <code>Ox.ends(str, sub)</code>.
`/sub$/.test(str)` or `!!/sub$/.exec(str)` is shorter than `Ox.ends(str,
sub)`.
> Ox.endsWith('foobar', 'bar')
true
@*/
@ -381,7 +381,7 @@ Ox.repeat = function(value, times) {
};
/*@
Ox.splice <f> <code>[].splice</code> for strings, returns a new string
Ox.splice <f> `[].splice` for strings, returns a new string
> Ox.splice('12xxxxx89', 2, 5, 3, 4, 5, 6, 7)
'123456789'
@*/
@ -394,8 +394,8 @@ Ox.splice = function(string, index, remove) {
/*@
Ox.startsWith <f> Checks if a string starts with a given substring
If the substring is a string literal (and not a variable),
<code>/^sub/.test(str)</code> or <code>!!/^sub/.exec(str)</code>
is shorter than <code>Ox.starts(str, sub)</code>.
`/^sub/.test(str)` or `!!/^sub/.exec(str)` is shorter than `Ox.starts(str,
sub)`.
> Ox.startsWith('foobar', 'foo')
true
@*/

View file

@ -210,8 +210,8 @@ Ox.isInt = function(value) {
};
/*@
Ox.isNaN <f> Tests if a value is NaN
(value) -> <b> True if the value is NaN
Ox.isNaN <f> Tests if a value is `NaN`
(value) -> <b> True if the value is `NaN`
value <*> Any value
> Ox.isNaN(NaN)
true
@ -221,8 +221,8 @@ Ox.isNaN = function(value) {
}
/*@
Ox.isNull <f> Tests if a value is <code>null</code>
(value) -> <b> True if the value is <code>null</null>
Ox.isNull <f> Tests if a value is `null`
(value) -> <b> True if the value is `null`
value <*> Any value
> Ox.isNull(null)
true