update oxdoc example
This commit is contained in:
parent
050a348061
commit
1fb1cf2727
2 changed files with 45 additions and 37 deletions
|
@ -1,7 +1,7 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>OxDoc</title>
|
||||
<title>OxDoc Tutorial</title>
|
||||
<meta http-equiv="Keywords" content="Documentation"/>
|
||||
<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"/>
|
|
@ -1,9 +1,5 @@
|
|||
/*
|
||||
**OxDoc Tutorial**
|
||||
*/
|
||||
'use strict';
|
||||
/*
|
||||
An OxDoc comment is an inline or multi-line comment that starts with `@`:
|
||||
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
|
||||
it doesn't, its meaning depends on its context.
|
||||
*/
|
||||
'use strict';
|
||||
|
||||
this.My = {};
|
||||
|
||||
/*
|
||||
|
@ -32,7 +30,7 @@ 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`.
|
||||
can contain some `markdown` (see Ox.parseMarkdown).
|
||||
*/
|
||||
/*@
|
||||
My.MAGIC_CONSTANT <number> Magic constant, needed for HTTP requests
|
||||
|
@ -47,15 +45,19 @@ 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. A line that starts with `>` is an inline test statement,
|
||||
followed by its expected result.
|
||||
A line that starts with `#` is an inline comment that will be ignored by the
|
||||
parser.
|
||||
|
||||
The following 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.
|
||||
|
||||
A line that starts with `>` is an inline test statement, followed by the
|
||||
expected result. (Yes, it's that simple!)
|
||||
*/
|
||||
/*@
|
||||
My.favorite <object> ...
|
||||
# Properties --------------------------------------------------------------
|
||||
My.favorite <object> Collection of favorites
|
||||
# Properties ---------------------------------------------------------------
|
||||
array <a> My favorite array
|
||||
boolean <b> My favorite boolean value
|
||||
date <d> My favorite date
|
||||
|
@ -74,6 +76,7 @@ My.favorite <object> ...
|
|||
any <*> Favorite of the day
|
||||
# Events -------------------------------------------------------------------
|
||||
event <!> Fires when My.favorite['function'] is called
|
||||
# Tests --------------------------------------------------------------------
|
||||
> My.favorite.array.length + My.favorite.string.length
|
||||
0
|
||||
> 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
|
||||
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
|
||||
`<a>`.
|
||||
a property (of a property...).
|
||||
|
||||
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
|
||||
|
@ -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
|
||||
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'>`. For a
|
||||
`function`-type argument (usually a callback function), there is no return value
|
||||
to document, only the arguments it gets passed.
|
||||
`(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'>`. 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
|
||||
|
@ -212,8 +218,9 @@ My.readURL = function(url, method, callback) {
|
|||
|
||||
/*
|
||||
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
|
||||
test asynchronous functions, call `Ox.test(actual, expected)` in the
|
||||
arguments, there can be multiple `(arguments) -> <type> summary` lines.
|
||||
|
||||
To test asynchronous functions, just call `Ox.test(actual, expected)` in the
|
||||
callback.
|
||||
*/
|
||||
/*@
|
||||
|
@ -336,9 +343,10 @@ And another section, named 'UI Elements'.
|
|||
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
|
||||
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
|
||||
event data, i.e. passes an object to its handlers, the properties of that object
|
||||
are documented as properties of the event.
|
||||
follwed by the documentation of the returned object
|
||||
|
||||
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
|
||||
|
@ -370,10 +378,10 @@ My.Box = function(options, self) {
|
|||
}
|
||||
}
|
||||
/*
|
||||
It can be more convenient to document properties at the place where they are
|
||||
defined. A name prefixed with a `.` signals that what follows is not a
|
||||
standalone item, but a property of the previous one (or, in case the
|
||||
previous item is a function that returns an object, a property of the
|
||||
Sometimes, it can be more convenient to document properties at the place
|
||||
where they are defined. A name prefixed with a `.` signals that what follows
|
||||
is not a standalone item, but a property of the previous one (or, in case
|
||||
the previous item is a function that returns an object, a property of the
|
||||
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"
|
||||
(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,
|
||||
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
|
||||
|
@ -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
|
||||
|
||||
/*
|
||||
Whenever code is hard to test with just a series of one-liners, a `<script>` tag
|
||||
can be added before the tests. Note that the script will be evaluated in the
|
||||
global context, so it's a good idea not to create or leave any clutter.
|
||||
Whenever code cannot be tested with just a series of one-liners, a `<script>`
|
||||
tag can be added before the tests. Since the script will be evaluated in the
|
||||
global context, it's a good idea not to create or leave any clutter.
|
||||
*/
|
||||
/*@
|
||||
My.Event <o> Provides basic event handling
|
Loading…
Reference in a new issue