From 8018ba499f0495565111eb4505216163a16c2b36 Mon Sep 17 00:00:00 2001
From: rlx <0x0073@0x2620.org>
Date: Wed, 24 Sep 2014 12:17:46 +0200
Subject: [PATCH] Ox.Element: update documentation

---
 source/Ox.UI/js/Core/Element.js | 139 +++++++++++++++++++++++++-------
 1 file changed, 111 insertions(+), 28 deletions(-)

diff --git a/source/Ox.UI/js/Core/Element.js b/source/Ox.UI/js/Core/Element.js
index d59cc90c..f33d9b14 100644
--- a/source/Ox.UI/js/Core/Element.js
+++ b/source/Ox.UI/js/Core/Element.js
@@ -364,11 +364,11 @@
 
     /*@
     bindEvent <f> Adds event handler(s)
-        (callback) -> <o> This element
+        (callback) -> <o> This element object
             Adds a catch-all handler
-        (event, callback) -> <o> This element
+        (event, callback) -> <o> This element object
             Adds a handler for a single event
-        ({event: callback, ...}) -> <o> This element
+        ({event: callback, ...}) -> <o> This element object
             Adds handlers for one or more events
         callback <f> Callback function
             data <o> event data (key/value pairs)
@@ -401,16 +401,16 @@
     };
 
     /*@
-    bindMessage <f> Adds message handlers (if the element is an iframe)
-        (callback) -> <o> This element
+    bindMessage <f> Adds message handler(s) (if the element is an iframe)
+        (callback) -> <o> This element object
             Adds a catch-all handler
-        (event, callback) -> <o> This element
-            Adds a handler for a single event
-        ({event: callback, ...}) -> <o> This element
-            Adds handlers for on or more events
+        (message, callback) -> <o> This element object
+            Adds a handler for a single message
+        ({message: callback, ...}) -> <o> This element object
+            Adds handlers for one or more messages
         callback <f> Callback function
-            data <o> event data (key/value pairs)
-        event <s> Event name
+            data <o> Message data (key/value pairs)
+        message <s> Message name
     @*/
     Ox.Element.prototype.bindMessage = Ox.Element.prototype.onMessage = function bindMessage() {
         var self = this.self(_);
@@ -420,6 +420,18 @@
         return this;
     };
 
+    /*@
+    bindMessageOnce <f> Adds message handler(s) that run only once
+        (callback) -> <o> This element object
+            Adds a catch-all handler
+        (message, callback) -> <o> This element object
+            Adds a handler for a single message
+        ({message: callback, ...}) -> <o> This element object
+            Adds handlers for one or more messages
+        callback <f> Callback function
+            data <o> Message data (key/value pairs)
+        event <s> Message name
+    @*/
     Ox.Element.prototype.bindMessageOnce = Ox.Element.prototype.onMessageOnce = function bindMessageOnce() {
         var self = this.self(_);
         if (self.options.element == '<iframe>') {
@@ -430,6 +442,10 @@
         return this;
     };
 
+    /*@
+    childrenElements <f> Gets all direct children element objects
+        () -> <[o]> Array of element objects
+    @*/
     Ox.Element.prototype.childrenElements = function childrenElements() {
         return Ox.slice(this.children())
             .filter(Ox.isOxElement)
@@ -465,13 +481,17 @@
         return this;
     };
 
+    /*@
+    findElements <f> Gets all descendant element objects
+        () -> <[o]> Array of element objects
+    @*/
     Ox.Element.prototype.findElements = function findElements() {
         return Ox.slice(this.find('.OxElement')).map(Ox.getOxElement);
     };
 
     /*@
     gainFocus <function> Makes an element object gain focus
-    () -> <obj> This element object
+        () -> <obj> This element object
     @*/
     Ox.Element.prototype.gainFocus = function gainFocus() {
         Ox.Focus.gainFocus(this);
@@ -480,7 +500,7 @@
 
     /*@
     hasFocus <function> Returns true if an element object has focus
-    () -> <boolean> True if the element has focus
+        () -> <boolean> True if the element has focus
     @*/
     Ox.Element.prototype.hasFocus = function hasFocus() {
         return Ox.Focus.focusedElement() === this;
@@ -497,17 +517,25 @@
 
     /*@
     loseFocus <function> Makes an element object lose focus
-    () -> <object> This element object
+        () -> <object> This element object
     @*/
     Ox.Element.prototype.loseFocus = function loseFocus() {
         Ox.Focus.loseFocus(this);
         return this;
     };
 
+    /*@
+    nextElement <f> Gets the closest following sibling element object
+        () -> <o> Element object
+    @*/
     Ox.Element.prototype.nextElement = function nextElement() {
         return this.nextElements()[0];
     };
 
+    /*@
+    nextElements <f> Gets all following sibling element objects
+        () -> <[o]> Array of element objects
+    @*/
     Ox.Element.prototype.nextElements = function nextElements() {
         return this.nextAll().filter(Ox.isOxElement).map(Ox.getOxElement);
     };
@@ -530,10 +558,18 @@
         return Ox.getset(self.options, arguments, self.update, this);
     };
 
+    /*@
+    parentElement <f> Gets the closest parent element object
+        () -> <o> Element object
+    @*/
     Ox.Element.prototype.parentElement = function parentElement() {
         return Ox.last(this.parentElements());
     };
 
+    /*@
+    parentElements <f> Gets all parent element objects
+        () -> <[o]> Array of element objects
+    @*/
     Ox.Element.prototype.parentElements = function parentElements() {
         return Ox.slice(this.parents())
             .filter(Ox.isOxElement)
@@ -542,7 +578,7 @@
 
     /*@
     postMessage <f> Sends a message (if the element is an iframe)
-        (event, data) -> This element
+        (event, data) -> This element object
         event <s> Event name
         data <o> Event data
     @*/
@@ -553,10 +589,18 @@
         return this;
     };
 
+    /*@
+    prevElement <f> Gets the closest preceding sibling element object
+        () -> <[o]> Array of element objects
+    @*/
     Ox.Element.prototype.prevElement = function prevElement() {
         return Ox.last(this.prevElements());
     };
 
+    /*@
+    prevElements <f> Gets all preceding sibling element objects
+        () -> <[o]> Array of element objects
+    @*/
     Ox.Element.prototype.prevElements = function prevElements() {
         return this.prevAll().filter(Ox.isOxElement).map(Ox.getOxElement);
     };
@@ -568,6 +612,10 @@
         return this;
     };
 
+    /*@
+    removeElement <f> Clean up after removal from DOM
+        This gets invoked on .remove()
+    @*/
     Ox.Element.prototype.removeElement = function removeElement(includeChildren) {
         if (includeChildren !== false) {
             this.findElements().forEach(function($element) {
@@ -596,8 +644,10 @@
     };
 
     /*@
-    setElement <f> set $element
-        ($element) -> <o> This element
+    setElement <f> Sets the element to the element of another element object
+        This is useful if an element has specific options, but uses another
+        generic element as its DOM representation
+        ($element) -> <o> This element object
     @*/
     Ox.Element.prototype.setElement = function setElement($element) {
         $element.addClass('OxElement').data({oxid: this.oxid});
@@ -610,6 +660,10 @@
         return this;
     };
 
+    /*@
+    siblingElements <f> Gets all sibling element objects
+        () -> <[o]> Array of element objects
+    @*/
     Ox.Element.prototype.siblingElements = function siblingElements() {
         return Ox.slice(this.siblings())
             .filter(Ox.isOxElement)
@@ -627,7 +681,7 @@
 
     /*@
     toggleOption <f> Toggle boolean option(s)
-        (key[, key[, ...]]) -> <o> This element
+        (key[, key[, ...]]) -> <o> This element object
     @*/
     Ox.Element.prototype.toggleOption = function toggleOption() {
         var options = {}, self = this.self(_);
@@ -645,8 +699,8 @@
             Triggers an event with data
         ({event: data, ...}) -> <o> This element object
             Triggers one or more events with data
-        event <string> Event name
-        data <object> Event data (key/value pairs)
+        event <s> Event name
+        data <o> Event data (key/value pairs)
     @*/
     Ox.Element.prototype.triggerEvent = function triggerEvent() {
         Ox.Event.trigger.apply(
@@ -655,6 +709,17 @@
         return this;
     };
 
+    /*@
+    triggerMessage <f> Triggers one or more messages
+        (message) -> <o> This element object
+            Triggers an event
+        (message, data) -> <o> This element object
+            Triggers a message with data
+        ({message: data, ...}) -> <o> This element object
+            Triggers one or more messages with data
+        message <s> Message name
+        data <o> Message data (key/value pairs)
+    @*/
     Ox.Element.prototype.triggerMessage = function triggerMessage() {
         var self = this.self(_);
         if (self.options.element == '<iframe>') {
@@ -665,16 +730,16 @@
 
     /*@
     unbindEvent <f> Removes event handler(s)
-        () -> <o> This element
+        () -> <o> This element object
             Removes all handlers.
-        (callback) -> <o> This element
+        (callback) -> <o> This element object
             Removes a specific catch-all handler
-        (event) -> <o> This element
+        (event) -> <o> This element object
             Removes all handlers for a single event (to remove all catch-all
             handlers, pass '*' as event)
-        (event, callback) -> <o> This element
+        (event, callback) -> <o> This element object
             Removes a specific handler for a single event
-        ({event: callback}, ...) -> <o> This element
+        ({event: callback}, ...) -> <o> This element object
             Removes specific handlers for one or more events
         event <string> Event name
     @*/
@@ -683,6 +748,21 @@
         return this;
     };
 
+    /*@
+    unbindMessage <f> Removes message handler(s)
+        () -> <o> This element
+            Removes all handlers.
+        (callback) -> <o> This element object
+            Removes a specific catch-all handler
+        (message) -> <o> This element object
+            Removes all handlers for a single message (to remove all catch-all
+            handlers, pass '*' as message)
+        (message, callback) -> <o> This element object
+            Removes a specific handler for a single event
+        ({message: callback}, ...) -> <o> This element object
+            Removes specific handlers for one or more messages
+        message <string> Message name
+    @*/
     Ox.Element.prototype.unbindMessage = function unbindMessage() {
         var self = this.self(_);
         if (self.options.element == '<iframe>') {
@@ -693,9 +773,9 @@
 
     /*@
     update <f> Adds one or more handlers for options updates
-    (callback) -> <o> that
-    (key, callback) -> <o> that
-    ({key: callback, ...}) -> <o> that
+        (callback) -> <o> This element object
+        (key, callback) -> <o> This element object
+        ({key: callback, ...}) -> <o> This element object
     @*/
     Ox.Element.prototype.update = function update() {
         var callbacks, self = this.self(_);
@@ -714,6 +794,9 @@
 
     /*@
     value <f> Shortcut to get or set self.options.value
+        () -> <*> Value
+        (value) -> <o> This element object
+        value <*> Value
     @*/
     Ox.Element.prototype.value = function value() {
         return this.options(