From 874d316fb2c714e422bf1e3bdf51077e90245de5 Mon Sep 17 00:00:00 2001
From: rolux <rolux@rolux.org>
Date: Wed, 30 May 2012 19:23:47 +0200
Subject: [PATCH] update documentation example

---
 examples/documentation/js/example.js | 93 ++++++++++++++++++++++++----
 1 file changed, 80 insertions(+), 13 deletions(-)

diff --git a/examples/documentation/js/example.js b/examples/documentation/js/example.js
index e20d55f0..ed1559aa 100644
--- a/examples/documentation/js/example.js
+++ b/examples/documentation/js/example.js
@@ -1,5 +1,24 @@
+/*
+An Ox.doc comment looks like this `//@ foo` or
+```
+/*@
+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'.
+*/
+//@ Primitives
+
 //@ My.REQUEST_TIMEOUT <number> Request timeout, in seconds
 My.REQUEST_TIMEOUT = 60;
 
@@ -9,21 +28,23 @@ My.MAGIC_CONSTANT <number> Magic constant needed for HTTP requests
 */
 My.MAGIC_CONSTANT = navigator.userAgent.length % 2 == 0 ? 23 : 42;
 
+//@ Objects
+
 /*@
 My.favorites <object> ...
-    array     <a> My favorite array
-    boolean   <b> My favorite boolean value
-    date      <d> My favorite date
-    element   <e> My favorite HTML element
-    number    <n> My favorite number
-    object    <o> My favorite object
-    regexp    <r> My favorite regular expression
-    string    <s> My favorite string
+    array   <a> My favorite array
+    boolean <b> My favorite boolean value
+    date    <d> My favorite date
+    element <e> My favorite HTML element
+    number  <n> My favorite number
+    object  <o> My favorite object
+    regexp  <r> My favorite regular expression
+    string  <s> My favorite string
 */
 My.favorites = {
     array: [],
     boolean: false,
-    date: new Date(0);
+    date: new Date(0),
     element: document.createElement('a'),
     number: 0,
     object: {},
@@ -31,6 +52,42 @@ My.favorites = {
     string: ''
 };
 
+/*@
+My.place <o> Default place object
+    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> Short German name
+            en <s> Short English name
+            fr <s> Short French name
+    points <[o]> Points of interest
+        lat <n> Latitude
+        lng <n> Longitude
+@*/
+My.place = {
+    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
+
 /*@
     (url[, method], callback) -> <u> undefined
     url      <s>       URL
@@ -75,7 +132,7 @@ My.isOdd = function(number, callback) {
     } else {
         return isOdd;
     }
-}
+};
 
 /*
 Occasionally, you may write a function whose signature cannot be represented in
@@ -87,7 +144,7 @@ be ambigious, since you cannot call it with `(stop, step)`.
 My.range <f> Returns a python-style range
     (b)       -> <[n]> Integers from 0 (inclusive) to b (exclusive)
     (a, b)    -> <[n]> Integers from a (inclusice) to b (exclusive)
-    (a, b, x) -> <[n]> Numbers from a (inclusive) to b (exclusive), growing by x
+    (a, b, c) -> <[n]> Numbers from a (inclusive) to b (exclusive), growing by c
 */
 My.range = function() {
     var a = [];
@@ -126,7 +183,7 @@ My.localStorage = (function() {
                         ret[key.slice(ns.length + 1)] = JSON.parse(value);
                     }
                 });
-            } else if (arguments.length == 1 && typeof key == 'string') {
+            } else if (arguments.length == 1 && !Ox.isObject(key)) {
                 value = localStorage[ns + '.' + key];
                 ret = Ox.isUndefined(value) ? void 0 : JSON.parse(value);
             } else {
@@ -147,4 +204,14 @@ My.localStorage = (function() {
         };
         return storage;
     };
-}();
\ No newline at end of file
+}());
+
+//@
+Ox.load('UI', function() {
+    var path = Ox.PATH + '../examples/documentation/js/';
+    Ox.print(path, '??')
+    Ox.DocPanel({
+        files: 'example.js',
+        path: path
+    }).appendTo(Ox.$body);
+});