add section titles to oxdoc tutorial
This commit is contained in:
rolux
parent
a299d2f6b1
commit
3636a3fe98
1 changed files with 53 additions and 6 deletions
|
|
@ -1,3 +1,8 @@
|
|||
/*
|
||||
<br>
|
||||
**OxDoc Tutorial**
|
||||
*/
|
||||
|
||||
/*
|
||||
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 = {};
|
||||
|
||||
/*
|
||||
**Sections**
|
||||
*/
|
||||
/*
|
||||
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'.
|
||||
*/
|
||||
//@ Primitives
|
||||
|
||||
/*
|
||||
**Name, Type, Summary**
|
||||
*/
|
||||
/*
|
||||
This inline comment documents an item by providing its name, type and one-line
|
||||
summary.
|
||||
|
|
@ -26,6 +37,9 @@ summary.
|
|||
//@ My.REQUEST_TIMEOUT <number> Request timeout, in milliseconds
|
||||
My.REQUEST_TIMEOUT = 60000;
|
||||
|
||||
/*
|
||||
**Descriptions**
|
||||
*/
|
||||
/*
|
||||
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
|
||||
|
|
@ -45,15 +59,22 @@ This defines a new section named 'Objects'.
|
|||
//@ Objects
|
||||
|
||||
/*
|
||||
A line that starts with `#` is an inline comment that will be ignored by the
|
||||
parser.
|
||||
**Comments, Properties, Events, Tests**
|
||||
*/
|
||||
/*
|
||||
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
|
||||
example shows all possible values for `type`. These values can be shortened —
|
||||
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
|
||||
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
|
||||
|
|
@ -113,6 +134,9 @@ My.favorite = (function() {
|
|||
return favorite;
|
||||
}());
|
||||
|
||||
/*
|
||||
**Nesting, Arrays**
|
||||
*/
|
||||
/*
|
||||
Documentation can be nested. In other words, one can document the properties of
|
||||
a property (of a property...).
|
||||
|
|
@ -166,6 +190,9 @@ The beginning of another section, named '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
|
||||
function's signature, return value and arguments. Signature and return value are
|
||||
|
|
@ -216,6 +243,9 @@ My.readURL = function(url, method, callback) {
|
|||
request.send();
|
||||
};
|
||||
|
||||
/*
|
||||
**Multiple Signatures, Asynchronous Tests**
|
||||
*/
|
||||
/*
|
||||
If a function's return value depends on the absence or presence of optional
|
||||
arguments, there can be multiple `(arguments) -> <type> summary` lines.
|
||||
|
|
@ -272,6 +302,9 @@ My.range = function() {
|
|||
return a;
|
||||
};
|
||||
|
||||
/*
|
||||
**Function Properties**
|
||||
*/
|
||||
/*
|
||||
As functions are objects in JavaScript, they may have their own properties or
|
||||
methods that need documentation. These get prefixed with `.`, in order to
|
||||
|
|
@ -339,6 +372,9 @@ And another section, named 'UI Elements'.
|
|||
*/
|
||||
//@ UI Elements
|
||||
|
||||
/*
|
||||
**Constructors, Event Properties, Separate Documentation of Properties**
|
||||
*/
|
||||
/*
|
||||
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
|
||||
|
|
@ -411,6 +447,9 @@ My.Box = function(options, self) {
|
|||
return that;
|
||||
};
|
||||
|
||||
/*
|
||||
**Inheritance**
|
||||
*/
|
||||
/*
|
||||
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,
|
||||
|
|
@ -473,9 +512,13 @@ The next item will get added to the 'Objects' section.
|
|||
//@ Objects
|
||||
|
||||
/*
|
||||
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.
|
||||
Extended Tests
|
||||
*/
|
||||
/*
|
||||
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
|
||||
|
|
@ -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
|
||||
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
|
||||
Ox.SyntaxHighlighter and Ox.DocPanel, and they'll do the rest.
|
||||
<br>
|
||||
*/
|
||||
Ox.load('UI', function() {
|
||||
var file = 'example.js',
|
||||
|
|
|
|||
Loading…
Reference in a new issue