diff --git a/examples/documentation/oxdoc/index.html b/examples/documentation/oxdoc_tutorial/index.html similarity index 94% rename from examples/documentation/oxdoc/index.html rename to examples/documentation/oxdoc_tutorial/index.html index 7a1806f5..74f1737a 100644 --- a/examples/documentation/oxdoc/index.html +++ b/examples/documentation/oxdoc_tutorial/index.html @@ -1,7 +1,7 @@ - OxDoc + OxDoc Tutorial diff --git a/examples/documentation/oxdoc/js/example.js b/examples/documentation/oxdoc_tutorial/js/example.js similarity index 89% rename from examples/documentation/oxdoc/js/example.js rename to examples/documentation/oxdoc_tutorial/js/example.js index 2b98a8f2..31c67cb8 100644 --- a/examples/documentation/oxdoc/js/example.js +++ b/examples/documentation/oxdoc_tutorial/js/example.js @@ -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 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 summary` are parsed as a description. Like the summary, the description -can contain `markdown`. +can contain some `markdown` (see Ox.parseMarkdown). */ /*@ My.MAGIC_CONSTANT 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 ... - # Properties -------------------------------------------------------------- +My.favorite Collection of favorites + # Properties --------------------------------------------------------------- array My favorite array boolean My favorite boolean value date My favorite date @@ -74,6 +76,7 @@ My.favorite ... 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 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 ``. */ /*@ My.HTMLUtils 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 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 ``. If it has a default value (in -this case the string `'GET'`), this is documented as ``. 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 ``. If it has a default value (in this case the +string `'GET'`), this is documented as ``. For a `function`-type +argument (usually a callback function), there is no return value to document, +only the arguments it gets passed. */ /*@ My.readURL 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) -> summary` lines. And to -test asynchronous functions, call `Ox.test(actual, expected)` in the +arguments, there can be multiple `(arguments) -> 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 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 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 `