update documentation example

examples/documentation/oxdoc/js/example.js

@@ -1,36 +1,53 @@
+'use strict';
 /*
-An Ox.doc comment looks like this `//@ foo` or
+An OxDoc comment is an inline or  multi-line comment that starts with `@`:
 ```
+//@ ...
 /*@
-foo
+...
-bar
+*/
-baz
-*\/
 ```
 The syntax is simple: almost every line has the form `name <type> summary`. If
 it doesn't, its meaning depends on its context. 
 */
-
 this.My = {};
 
 /*
 If the first line of the comment doesn't match `name <type> summary`, it is a
-section definition. Here, we mark a section named 'Primitives'.
+section definition. Here, it marks a section named 'Primitives'.
 */
 //@ Primitives
 
+/*
+This inline comment documents an item by providing its name, type and one-line
+summary.
+*/
 //@ My.REQUEST_TIMEOUT <number> Request timeout, in milliseconds
 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`.
+*/
 /*@
 My.MAGIC_CONSTANT <number> Magic constant, needed for HTTP requests
-    Please note that the value for `MAGIC_CONSTANT` is browser-dependent.
+    Please note that the value of `My.MAGIC_CONSTANT` (either `23` or `42`) is
+    browser-dependent.
 */
-My.MAGIC_CONSTANT = navigator.userAgent.length % 2 == 0 ? 23 : 42;
+My.MAGIC_CONSTANT = navigator.userAgent.length % 2 ? 23 : 42;
 
-Ox.load(function() {
-//@ Objects
 /*
+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.
 */
 /*@
 My.favorites <object> ...
@@ -75,32 +92,43 @@ My.favorites = (function() {
             other: document
         },
         keys = Object.keys(favorites);
-    return Ox.extend(favorites, {any: favorites[keys[Ox.random(keys.length)]]});
+    favorites.any = favorites[keys[Math.floor(Math.random() * keys.length)]];
+    return favorites;
 }());
 
+/*
+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
+`<array>`.
+*/
 /*@
-My.HTMLUtils <object> ...
+My.HTMLUtils <o> HTML Utilities
-        replace <array> ...
+    namedEntities <[s]> Named HTML entities
-            0 <regexp> ...
+    replace <o> Entity decoding utilities
-            1 <string> replace
+        namedEntities <a> Can be passed to `String.prototype.replace`
+            0 <r> Matches named entities
+            1 <f> Decodes named entities
+        numericEntities <a> Can be passed to `String.prototype.replace`
+            0 <r> Matches numeric entities
+            1 <f> Decodes numeric entities
 */
 My.HTMLUtils = (function() {
-    var entities = {
+    var chars = '"&\'<>',
-        '"': '&quot;', '&': '&amp;', "'": '&apos;', '<': '&lt;', '>': '&gt;'
+        entities = ['&quot;', '&amp;', '&apos;', '&lt;', '&gt;'];
-    };
     return {
-        entities: entities,
+        namedEntities: entities,
         replace: {
-            namedEntity: [
+            namedEntities: [
-                new RegExp('(' + Ox.values(entities).join('|') + ')', 'g'),
+                new RegExp('(' + entities.join('|') + ')', 'g'),
                 function(match) {
-                    return Ox.keyOf(entities, match);
+                    return chars[entities.indexOf(match)];
                 }
             ],
-            numericEntity: [
+            numericEntities: [
                 /&#([0-9A-FX]+);/gi,
                 function(match, code) {
-                    return Ox.char(
+                    return String.fromCharCode(
                         /^X/i.test(code)
                             ? parseInt(code.slice(1), 16)
                             : parseInt(code, 10)
@@ -111,83 +139,63 @@ My.HTMLUtils = (function() {
     };
 }());
 
-/*@
+/*
-My.defaultPlace <o> Default place object
+The beginning of another section, named 'Functions'.
-    geometry <o>
+*/
-        bounds <o> ..
-            northEast <o>
-                lat <n>
-                lng <n>
-            southWest <o>
-                lat <n>
-                lng <n>
-    types <[s]>
-    name <o> Localized place names
-        short <o> Short place name
-            de <s> Short German name
-            en <s> Short English name
-            fr <s> Short French name
-        long <o> Long place name
-            de <s> Long German name
-            en <s> Long English name
-            fr <s> Long French name
-    points <[o]> Points of interest
-        lat <n> Latitude
-        lng <n> Longitude
-@*/
-My.place = {
-    bounds: {
-        northEast: {lat: 0, lng: 0},
-        southWest: {lat: 0, lng: 0}
-    },
-    name: {
-        short: {
-            de: 'Brüssel',
-            en: 'Brussels',
-            fr: 'Bruxelles'
-        },
-        long: {
-            de: 'Brüssel, Belgien',
-            en: 'Brussels, Belgium',
-            fr: 'Bruxelles, Belgique'
-        }
-    },
-    points: [
-        {lat: 0, lng: 0},
-        {lat: 45, lng: 90}
-    ]
-};
-
 //@ 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'>`. In the case of
+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
     (url[, method], callback) -> <u> undefined
-    url      <s>       URL
+        Please note that the return value of `My.readURL` may change in the
+        future.
+    url <s|f> Remote URL, or function that returns one
     method <s|'GET'> Request method ('GET', 'POST', 'PUT' or 'DELETE')
     callback <f> Callback function
+        result <s|null> Response text, or `null` in case of an error
+        error <o|null> Error object, or `null` in case of success
+            code <n> Error code
+            text <s> Error text
 */
 My.readURL = function(url, method, callback) {
     var request = new XMLHttpRequest();
+    if (Ox.isFunction(url)) {
+        url = url();
+    }
     if (arguments.length == 2) {
         callback = method;
         method = 'GET';
     }
     request.open(method, url, true);
-    req.onreadystatechange = function() {
+    request.onreadystatechange = function() {
         if (request.readyState == 4) {
             if (request.status == 200) {
-                callback(request.responseText);
+                callback(request.responseText, null);
             } else {
-                throw new Error(
+                callback(null, {
-                    'Cannot get URL "' + url
+                    code: request.status,
-                    + '" (Status: ' + request.status + ')'
+                    text: request.statusText
-                );
+                });
             }
         }
     };
     request.send();
 };
 
+/*
+If a function's return value depends on the absence or presence of optional
+arguments, there can be multiple `(arguments) -> <type> summary` lines.
+*/
 /*@
 My.isOdd <f> Synchronously or asynchronously computes if a given number is odd
     (number) -> <b> True if the number is odd
@@ -207,10 +215,11 @@ My.isOdd = function(number, callback) {
 };
 
 /*
-Occasionally, you may write a function whose signature cannot be represented in
+Another case for multiple `(arguments) -> <type> summary` lines are functions
-`(required[, optional])` notation. For a range function — `(stop)` or `(start,
+whose signature cannot be represented in `(required[, optional])` notation. For
-stop)` or `(start, stop, step)` — the notation `([start, ]stop[, step])` would
+a range function — `(stop)` or `(start, stop)` or `(start, stop, step)` — the
-be ambigious, since you cannot call it with `(stop, step)`.
+notation `([start, ]stop[, step])` would be ambigious, since you cannot call it
+with `(stop, step)`.
 */
 /*@
 My.range <f> Returns a python-style range
@@ -226,6 +235,10 @@ My.range = function() {
     return a;
 };
 
+/*
+In case a function has a property or method one wants to document, it gets
+prefixed with `.`, in order to differentiate it from an argument.
+*/
 /*@
 My.localStorage <f> Returns a localStorage handler for a given namespace
     (ns) -> storage <f> localStorage handler
@@ -278,13 +291,63 @@ My.localStorage = (function() {
     };
 }());
 
-});
+/*
+And one more section, named 'UI Elements'.
+*/
+//@ UI Element
+
+/*@
+My.Box <f> A very simple colored box
+    options <o> Options
+        color <[n]> RGB value
+    self <o> Shared private object
+    ([options[, self]]) -> <o> Box object
+        grayscale <!> Fires when changing the color of the box to grayscale
+            color <n> Value between `0` and `255`
+*/
+My.Box = function(options, self) {
+    self = self || {};
+    var that = Ox.Element({}, self)
+        .defaults({color: [255, 0, 0]})
+        .options(options || {})
+        .update(setColor)
+        .css({width: '256px', height: '256px'});
+    function setColor() {
+        that.css({background: 'rgb(' + self.options.color.join(', ') + ')'});
+    }
+    /*@
+    .toGrayscale <f> Changes the color of the box to grayscale.
+        () -> <o> The box object
+    */
+    that.toGrayscale = function() {
+        return that.options({
+            color: Ox.repeat([Ox.avg(self.options.color)], 3)
+        }).triggerEvent('grayscale', {color: self.options.color[0]});
+    };
+    return that;
+};
+
 //@
 Ox.load('UI', function() {
-    var path = Ox.PATH + '../examples/documentation/js/';
+    var file = 'example.js',
-    Ox.print(path, '??')
+        path = Ox.PATH + '../examples/documentation/oxdoc/js/';
-    Ox.DocPanel({
+    Ox.get(path + file, function(source) {
+        var doc = Ox.doc(source);
+        Ox.TabPanel({
+            content: {
+                source: Ox.SyntaxHighlighter({source: path + file}),
+                doc: Ox.TreeList({data: doc}),
+                docpanel: Ox.DocPanel({
+                    expanded: true,
                     files: 'example.js',
                     path: path
+                })
+            },
+            tabs: [
+                {id: 'source', title: 'source'},
+                {id: 'doc', title: 'doc = Ox.doc(source)'},
+                {id: 'docpanel', title: 'Ox.DocPanel({items: doc})'}
+            ]
         }).appendTo(Ox.$body);
+    });
 });