From d41e12de2fa81e0147ea40a9d15d25d159ed0e0f Mon Sep 17 00:00:00 2001
From: rolux <rolux@rolux.org>
Date: Sat, 23 Jun 2012 23:46:58 +0200
Subject: [PATCH] update documentation example

---
 examples/documentation/oxdoc/js/example.js | 30 +++++++++++++---------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/examples/documentation/oxdoc/js/example.js b/examples/documentation/oxdoc/js/example.js
index b0a2a80c..fef29e26 100644
--- a/examples/documentation/oxdoc/js/example.js
+++ b/examples/documentation/oxdoc/js/example.js
@@ -68,8 +68,8 @@ My.favorites <object> ...
     regexp      <r> My favorite regular expression
     string      <s> My favorite string
     undefined   <u> Undefined is an all-time favorite
-    window      <w> ...
-    other       <+> ...
+    window      <w> So is the DOM window
+    other       <+> And the document
     any         <*> Favorite of the day
     # Events -------------------------------------------------------------------
     event       <!> Fires when My.favorite['function'] is called
@@ -95,7 +95,9 @@ My.favorites = (function() {
             other: document
         },
         keys = Object.keys(favorites);
-    favorites.any = favorites[keys[Math.floor(Math.random() * keys.length)]];
+    favorites.any = favorites[
+        keys[Math.floor(+new Date / 86400) * keys.length]
+    ];
     return favorites;
 }());
 
@@ -103,7 +105,7 @@ My.favorites = (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
-`<array>`.
+`<a>`.
 */
 /*@
 My.HTMLUtils <o> HTML Utilities
@@ -153,9 +155,9 @@ 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.
+this case the string `'GET'`), this is documented as `<s|'GET'>`. For 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
@@ -239,8 +241,8 @@ My.range = function() {
 };
 
 /*
-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.
+In case a function has properties or methods that need documentation, they get
+prefixed with `.`, in order to differentiate them from arguments.
 */
 /*@
 My.localStorage <f> Returns a localStorage handler for a given namespace
@@ -362,8 +364,14 @@ My.Box = function(options, self) {
     return that;
 };
 
+/*
+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,
+`My.ExtendedBox` extends `My.Box`. All events and properties of the latter,
+unless redefined will, be present on the former
+*/
 /*@
-My.ExtendedBox <f> ...
+My.ExtendedBox <f> An extended box with random color
     options <o> Options
         height <n> Height in px
         width <n> Width in px
@@ -382,8 +390,6 @@ My.ExtendedBox = function(options, self) {
             if (key == 'width' || key == 'height') {
                 setSize();
             }
-        })
-        .css({
         });
     randomize();
     setSize();