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

update oxdoc example

Browse source
This commit is contained in:
rolux 2012-06-24 17:32:45 +02:00
parent 050a348061
commit 1fb1cf2727
2 changed files with 45 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
examples/documentation/oxdoc/index.html → examples/documentation/oxdoc_tutorial/index.html
View file

@ -1,7 +1,7 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head> <head>
<title>OxDoc</title> <title>OxDoc Tutorial</title>
<meta http-equiv="Keywords" content="Documentation"/> <meta http-equiv="Keywords" content="Documentation"/>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link rel="shortcut icon" type="image/png" href="../../../source/Ox.UI/themes/classic/png/icon16.png"/> <link rel="shortcut icon" type="image/png" href="../../../source/Ox.UI/themes/classic/png/icon16.png"/>

80
examples/documentation/oxdoc/js/example.js → examples/documentation/oxdoc_tutorial/js/example.js
View file

@ -1,9 +1,5 @@
/* /*
**OxDoc Tutorial** An `OxDoc` comment is an inline or multi-line comment that starts with `@`:
*/
'use strict';
/*
An OxDoc comment is an inline or multi-line comment that starts with `@`:
``` ```
//@ ... //@ ...
/*@ /*@
@ -13,6 +9,8 @@ An OxDoc comment is an inline or multi-line comment that starts with `@`:
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.
*/ */
'use strict';
this.My = {}; this.My = {};
/* /*
@ -32,7 +30,7 @@ My.REQUEST_TIMEOUT = 60000;
In a multiline comment, lines that follow the inital definition are indented, as 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 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 <type> summary` are parsed as a description. Like the summary, the description
can contain `markdown`. can contain some `markdown` (see Ox.parseMarkdown).
*/ */
/*@ /*@
My.MAGIC_CONSTANT <number> Magic constant, needed for HTTP requests My.MAGIC_CONSTANT <number> Magic constant, needed for HTTP requests
@ -47,15 +45,19 @@ This defines a new section named 'Objects'.
//@ Objects //@ Objects
/* /*
Lines that start with `#` are inline comments. The follwing lines document A line that starts with `#` is an inline comment that will be ignored by the
properties of the `My.favorites` object. This example shows all possible values parser.
for `type`. These values can be shortened, it's sufficient to specify their
first character. A line that starts with `>` is an inline test statement, The following lines document properties of the `My.favorites` object. This
followed by its expected result. example shows all possible values for `type`. These values can be shortened —
it's sufficient to specify their first character.
A line that starts with `>` is an inline test statement, followed by the
expected result. (Yes, it's that simple!)
*/ */
/*@ /*@
My.favorite <object> ... My.favorite <object> Collection of favorites
# Properties -------------------------------------------------------------- # Properties ---------------------------------------------------------------
array <a> My favorite array array <a> My favorite array
boolean <b> My favorite boolean value boolean <b> My favorite boolean value
date <d> My favorite date date <d> My favorite date
@ -74,6 +76,7 @@ My.favorite <object> ...
any <*> Favorite of the day any <*> Favorite of the day
# Events ------------------------------------------------------------------- # Events -------------------------------------------------------------------
event <!> Fires when My.favorite['function'] is called event <!> Fires when My.favorite['function'] is called
# Tests --------------------------------------------------------------------
> My.favorite.array.length + My.favorite.string.length > My.favorite.array.length + My.favorite.string.length
0 0
> My.favorite['function'].length + My.favorite.arguments.length > My.favorite['function'].length + My.favorite.arguments.length
@ -112,9 +115,10 @@ My.favorite = (function() {
/* /*
Documentation can be nested. In other words, one can document the properties of 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 a property (of a property...).
type (in this case `string`), one can mark the type as `<[s]>` instead of just
`<a>`. 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 `<a>`.
*/ */
/*@ /*@
My.HTMLUtils <o> HTML Utilities My.HTMLUtils <o> HTML Utilities
@ -166,11 +170,13 @@ The beginning of another section, named 'Functions'.
In the case of a function, the indented lines don't document properties, but the 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 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 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` `(arguments) ->`.
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'>`. For a If an item can be of more than one type (in this case `string` or `function`),
`function`-type argument (usually a callback function), there is no return value this is documented as `<s|f>`. If it has a default value (in this case the
to document, only the arguments it gets passed. string `'GET'`), this is documented as `<s|'GET'>`. For 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 My.readURL <f> Asynchronously reads a remote resource
@ -212,8 +218,9 @@ My.readURL = function(url, method, callback) {
/* /*
If a function's return value depends on the absence or presence of optional If a function's return value depends on the absence or presence of optional
arguments, there can be multiple `(arguments) -> <type> summary` lines. And to arguments, there can be multiple `(arguments) -> <type> summary` lines.
test asynchronous functions, call `Ox.test(actual, expected)` in the
To test asynchronous functions, just call `Ox.test(actual, expected)` in the
callback. callback.
*/ */
/*@ /*@
@ -336,9 +343,10 @@ And another section, named 'UI Elements'.
When documenting a constructor function, the returned object may come with a lot When documenting a constructor function, the returned object may come with a lot
more documentation than the function itself. In this case, one may want to more documentation than the function itself. In this case, one may want to
document the contructor's arguments first, then the signature and return value, document the contructor's arguments first, then the signature and return value,
follwed by the documentation of the returned object. Further, if an event has follwed by the documentation of the returned object
event data, i.e. passes an object to its handlers, the properties of that object
are documented as properties of the event. If an event has properties (i.e. passes an object to its handler), these
properties can be documented as well, just like regular object properties.
*/ */
/*@ /*@
My.Box <f> A very simple colored box My.Box <f> A very simple colored box
@ -370,10 +378,10 @@ My.Box = function(options, self) {
} }
} }
/* /*
It can be more convenient to document properties at the place where they are Sometimes, it can be more convenient to document properties at the place
defined. A name prefixed with a `.` signals that what follows is not a where they are defined. A name prefixed with a `.` signals that what follows
standalone item, but a property of the previous one (or, in case the is not a standalone item, but a property of the previous one (or, in case
previous item is a function that returns an object, a property of the the previous item is a function that returns an object, a property of the
retuned object). retuned object).
*/ */
/*@ /*@
@ -405,9 +413,9 @@ My.Box = function(options, self) {
/* /*
If an object extends or inherits from another one, one can specify its "class" If an object extends or inherits from another one, one can specify its "class"
(i.e. the name of the constuctor of the object it inherits from). Here, (the name of the constuctor of the object it inherits from). Here,
`My.ExtendedBox` extends `My.Box`. All events and properties of the latter, `My.ExtendedBox` extends `My.Box`. All events and properties of the latter,
unless redefined will, be present on the former. unless redefined, will be present on the former.
*/ */
/*@ /*@
My.ExtendedBox <f> An extended box with random color My.ExtendedBox <f> An extended box with random color
@ -460,14 +468,14 @@ My.ExtendedBox = function(options, self) {
}; };
/* /*
The last item gets added to the 'Objects' section. The last item will get added to the 'Objects' section.
*/ */
//@ Objects //@ Objects
/* /*
Whenever code is hard to test with just a series of one-liners, a `<script>` tag Whenever code cannot be tested with just a series of one-liners, a `<script>`
can be added before the tests. Note that the script will be evaluated in the tag can be added before the tests. Since the script will be evaluated in the
global context, so it's a good idea not to create or leave any clutter. global context, it's a good idea not to create or leave any clutter.
*/ */
/*@ /*@
My.Event <o> Provides basic event handling My.Event <o> Provides basic event handling