add section titles to oxdoc tutorial

examples/documentation/oxdoc_tutorial/js/example.js

@@ -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
+**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
 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>`
+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
@@ -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>&nbsp;
 */
 Ox.load('UI', function() {
     var file = 'example.js',