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

add section titles to oxdoc tutorial

Browse source
This commit is contained in:
rolux 2012-06-26 11:08:00 +02:00
parent a299d2f6b1
commit 3636a3fe98
1 changed files with 53 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

59
examples/documentation/oxdoc_tutorial/js/example.js
View file

@ -1,3 +1,8 @@
/*
<br>
**OxDoc Tutorial**
*/
/* /*
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,12 +18,18 @@ it doesn't, its meaning depends on its context.
this.My = {}; this.My = {};
/*
**Sections**
*/
/* /*
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, it marks a section named 'Primitives'. section definition. Here, it marks a section named 'Primitives'.
*/ */
//@ Primitives //@ Primitives
/*
**Name, Type, Summary**
*/
/* /*
This inline comment documents an item by providing its name, type and one-line This inline comment documents an item by providing its name, type and one-line
summary. summary.
@ -26,6 +37,9 @@ 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;
/*
**Descriptions**
*/
/* /*
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
@ -45,15 +59,22 @@ This defines a new section named 'Objects'.
//@ Objects //@ Objects
/* /*
A line that starts with `#` is an inline comment that will be ignored by the **Comments, Properties, Events, Tests**
parser. */
/*
A line that starts with `#` is a comment, and will be ignored by the parser.
The following lines document properties of the `My.favorites` object. This The following lines document properties of the `My.favorites` object. This
example shows all possible values for `type`. These values can be shortened — example shows all possible values for `type`. These values can be shortened —
it's sufficient to specify their first character. it's sufficient to specify their first character.
If an object fires events, they can be documented as well.
A line that starts with `>` is an inline test statement, followed by the A line that starts with `>` is an inline test statement, followed by the
expected result. (Yes, it's that simple!) expected result. (Yes, it's that simple!) A benefit of inline tests is the fact
that they're not just machine-, but also human-readable. As an illustration of a
function's behavior, they are often more compact and comprehensible than a long
description.
*/ */
/*@ /*@
My.favorite <object> Collection of favorites My.favorite <object> Collection of favorites
@ -113,6 +134,9 @@ My.favorite = (function() {
return favorite; return favorite;
}()); }());
/*
**Nesting, Arrays**
*/
/* /*
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...). a property (of a property...).
@ -166,6 +190,9 @@ The beginning of another section, named 'Functions'.
*/ */
//@ Functions //@ Functions
/*
**Functions, Arguments, Return Values, Multiple Types, Default Values**
*/
/* /*
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
@ -216,6 +243,9 @@ My.readURL = function(url, method, callback) {
request.send(); request.send();
}; };
/*
**Multiple Signatures, Asynchronous Tests**
*/
/* /*
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. arguments, there can be multiple `(arguments) -> <type> summary` lines.
@ -272,6 +302,9 @@ My.range = function() {
return a; return a;
}; };
/*
**Function Properties**
*/
/* /*
As functions are objects in JavaScript, they may have their own properties or As functions are objects in JavaScript, they may have their own properties or
methods that need documentation. These get prefixed with `.`, in order to methods that need documentation. These get prefixed with `.`, in order to
@ -339,6 +372,9 @@ And another section, named 'UI Elements'.
*/ */
//@ UI Elements //@ UI Elements
/*
**Constructors, Event Properties, Separate Documentation of Properties**
*/
/* /*
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
@ -411,6 +447,9 @@ My.Box = function(options, self) {
return that; return that;
}; };
/*
**Inheritance**
*/
/* /*
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"
(the name of the constuctor of the object it inherits from). Here, (the name of the constuctor of the object it inherits from). Here,
@ -473,9 +512,13 @@ The next item will get added to the 'Objects' section.
//@ Objects //@ Objects
/* /*
Whenever code cannot be tested with just a series of one-liners, a `<script>` Extended Tests
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. /*
Whenever an item requires some setup before it can 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 My.Event <o> Provides basic event handling
@ -563,6 +606,9 @@ My.Event = (function() {
}()); }());
//@ //@
/*
**Demo: Source, Parser, Browser**
*/
/* /*
And finally, this is how everything gets parsed and displayed, in less than 30 And finally, this is how everything gets parsed and displayed, in less than 30
lines of code. Note that it would be more efficient to parse the source once lines of code. Note that it would be more efficient to parse the source once
@ -595,6 +641,7 @@ Ox.DocPanel({
``` ```
— but the thing we want to demonstrate here is that we can just pass files to — but the thing we want to demonstrate here is that we can just pass files to
Ox.SyntaxHighlighter and Ox.DocPanel, and they'll do the rest. Ox.SyntaxHighlighter and Ox.DocPanel, and they'll do the rest.
<br>&nbsp;
*/ */
Ox.load('UI', function() { Ox.load('UI', function() {
var file = 'example.js', var file = 'example.js',