From 76722ec437bb9674f1d7a4195d4b35d2312548c6 Mon Sep 17 00:00:00 2001
From: rolux <rolux@rolux.org>
Date: Sat, 23 Jun 2012 20:26:55 +0200
Subject: [PATCH] update documentation example

---
 examples/documentation/oxdoc/js/example.js | 145 ++++++++++++++++++---
 1 file changed, 129 insertions(+), 16 deletions(-)

diff --git a/examples/documentation/oxdoc/js/example.js b/examples/documentation/oxdoc/js/example.js
index f60285a3..d278054d 100644
--- a/examples/documentation/oxdoc/js/example.js
+++ b/examples/documentation/oxdoc/js/example.js
@@ -1,3 +1,6 @@
+/*
+**OxDoc Tutorial**
+*/
 'use strict';
 /*
 An OxDoc comment is an inline or  multi-line comment that starts with `@`:
@@ -294,15 +297,21 @@ My.localStorage = (function() {
 /*
 And one more section, named 'UI Elements'.
 */
-//@ UI Element
+//@ 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.
+*/
 /*@
 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
+        change <!> Fires when the color of the box changes
             color <n> Value between `0` and `255`
 */
 My.Box = function(options, self) {
@@ -312,41 +321,145 @@ My.Box = function(options, self) {
         .options(options || {})
         .update(setColor)
         .css({width: '256px', height: '256px'});
+    setColor();
     function setColor() {
         that.css({background: 'rgb(' + self.options.color.join(', ') + ')'});
+        if (arguments.length) {
+            that.triggerEvent('change', {color: self.options.color});
+        }
     }
+    /*
+    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).
+    */
+    /*@
+    .getHSL <f> Returns the color of the box as HSL value
+        () -> <[n]> HSL value
+    */
+    that.getHSL = function() {
+        return Ox.hsl(self.options.value);
+    };
+    /*@
+    .setHSL <f> Sets the color of the box to a given HSL value
+        (hsl) -> <o> The Box object
+        hsl <[n]> HSL value
+    */
+    that.setHSL = function(hsl) {
+        return that.options({color: Ox.rgb(hsl)});
+    };
     /*@
     .toGrayscale <f> Changes the color of the box to grayscale.
-        () -> <o> The box object
+        () -> <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;
 };
 
+/*@
+My.ExtendedBox <f> ...
+    options <o> Options
+        height <n> Height in px
+        width <n> Width in px
+    self <o> Shared private object
+    ([options[, self]]) -> <o:My.Box> Extended Box object
+*/
+My.ExtendedBox = function(options, self) {
+    self = self || {};
+    var that = My.Box({}, self)
+        .defaults({
+            height: 256,
+            width: 256
+        })
+        .options(options || {})
+        .update(function(key, value) {
+            if (key == 'width' || key == 'height') {
+                setSize();
+            }
+        })
+        .css({
+        });
+    randomize();
+    setSize();
+    function randomize() {
+        that.options({
+            color: Ox.range(3).map(function() {
+                return Ox.random(256);
+            })
+        });
+    }
+    function setSize() {
+        that.css({
+            width: self.options.width + 'px',
+            height: self.options.height + 'px'
+        })
+    }
+    /*@
+    .randomize <f> Randomizes the colors of the box
+        () -> <o> The Extended Box object
+    */
+    that.randomize = randomize;
+    return that;
+};
+
 //@
+/*
+And finally, this is how everything gets parsed and displayed, in 25 lines of
+code. Note that it would be more efficient to parse the source once
+```
+var doc = Ox.doc(source);
+```
+and use
+```
+Ox.SyntaxHighlighter({
+    showLineNumbers: true,
+    source: source
+})
+```
+and
+```
+Ox.TreeList({data: doc})
+```
+and
+```
+Ox.DocPanel({
+    expanded: true,
+    items: doc,
+    getModule: function() { return 'My'; },
+    path: path
+});
+```
+— 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.
+*/
 Ox.load('UI', function() {
     var file = 'example.js',
         path = Ox.PATH + '../examples/documentation/oxdoc/js/';
     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
-                })
+            content: function(id) {
+                return id == 'source' ? Ox.SyntaxHighlighter({
+                        file: path + file,
+                        showLineNumbers: true,
+                    }).css({overflowY: 'scroll'})
+                    : id == 'items' ? Ox.TreeList({data: Ox.doc(source)})
+                    : Ox.DocPanel({
+                        expanded: true,
+                        files: [file],
+                        getModule: function() { return 'My'; },
+                        path: path
+                    });
             },
             tabs: [
-                {id: 'source', title: 'source'},
-                {id: 'doc', title: 'doc = Ox.doc(source)'},
-                {id: 'docpanel', title: 'Ox.DocPanel({items: doc})'}
+                {id: 'source', title: 'Source Code', selected: true},
+                {id: 'items', title: 'Parsed Documentation'},
+                {id: 'panel', title: 'Documentation Browser'}
             ]
         }).appendTo(Ox.$body);
     });