From 2dc8fd19aa92865f4e8ded54b0664c4a2eaf21c4 Mon Sep 17 00:00:00 2001
From: rolux <rolux@rolux.org>
Date: Sat, 30 Jun 2012 12:29:06 +0200
Subject: [PATCH] update docs

---
 source/Ox.UI/js/Core/Element.js | 47 ++++++++++++++++++++-------------
 source/Ox.UI/js/Core/Event.js   | 38 +++++++++++++-------------
 2 files changed, 47 insertions(+), 38 deletions(-)

diff --git a/source/Ox.UI/js/Core/Element.js b/source/Ox.UI/js/Core/Element.js
index c2bc5e78..cb0d4387 100644
--- a/source/Ox.UI/js/Core/Element.js
+++ b/source/Ox.UI/js/Core/Element.js
@@ -247,10 +247,13 @@ Ox.Element = function(options, self) {
     }
 
     /*@
-    bindEvent <function> Binds a function to an event
-        (callback)               -> <o> This element
-        (event, callback)        -> <o> This element
+    bindEvent <f> Adds event handler(s)
+        (callback) -> <o> This element
+            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 multiple events
         callback <f> Callback function
             data <o> event data (key/value pairs)
         event <s> Event name
@@ -262,9 +265,13 @@ Ox.Element = function(options, self) {
     };
 
     /*@
-    bindEventOnce <function> Binds a function to an event, once
-        (event, callback)        -> <obj> This element object
-        ({event: callback, ...}) -> <obj> This element object
+    bindEventOnce <f> Adds event handler(s) that run(s) only once
+        (callback) -> <o> This element
+            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 multiple events
         callback <f> Callback function
             data <o> event data (key/value pairs)
         event <s> Event name
@@ -392,10 +399,13 @@ Ox.Element = function(options, self) {
     };
 
     /*@
-    triggerEvent <function> Triggers an event
-        (event) -> <object> This element object
-        (event, data) -> <object> This element object
-        ({event: data, ...}) -> <object> This element object
+    triggerEvent <f> Triggers one or more events
+        (event) -> <o> This element object
+            Triggers an event
+        (event, data) -> <o> This element object
+            Triggers an event with data
+        ({event: data, ...}) -> <o> This element object
+            Triggers multiple events with data
         event <string> Event name
         data <object> Event data (key/value pairs)
     @*/
@@ -405,19 +415,18 @@ Ox.Element = function(options, self) {
     };
 
     /*@
-    unbindEvent <function> Unbinds all callbacks from an event
-        To unbind a specific handler, use namespaced events, like
-        `bindEvent('click.foo', callback)`, and then `unbindEvent('click.foo')`.
-        () -> <object> This element
-            Unbinds all callbacks from all events
+    unbindEvent <f> Removes event handler(s)
+        () -> <o> This element
+            Removes all handlers.
         (callback) -> <o> This element
-            Unbinds one callback from all events
+            Removes a specific catch-all handler
         (event) -> <o> This element
-            Unbinds all callbacks from one event
+            Removes all handlers for a single event (to remove all catch-all
+            handlers, pass '*' as event)
         (event, callback) -> <o> This element
-            Unbinds one callback from one event
+            Removes a specific handler for a single event
         ({event: callback}, ...) -> <o> This element
-            Unbinds multiple callbacks from multiple events
+            Removes specific handlers for multiple events
         event <string> Event name
     @*/
     that.unbindEvent = function() {
diff --git a/source/Ox.UI/js/Core/Event.js b/source/Ox.UI/js/Core/Event.js
index 5dd277d0..245d11ca 100644
--- a/source/Ox.UI/js/Core/Event.js
+++ b/source/Ox.UI/js/Core/Event.js
@@ -40,15 +40,15 @@ Ox.Event = (function() {
     }
 
     /*@
-    .bind <f> Adds an event handler
+    .bind <f> Adds event handler(s)
         (callback) -> <o> Ox.Event
-            Add a global event handler
+            Adds a global event handler
         (self, callback) -> <o> Ox.Event
-            Add a catch-all event handler
+            Adds a catch-all handler
         (self, event, callback) -> <o> Ox.Event
-            Add an event handler for a single event
+            Adds a handler for a single event
         (self, {event: callback, ...}) -> <o> Ox.Event
-            Add event handlers for multiple events
+            Adds handlers for multiple events
         self <o> The element's shared private object
         callback <f> Callback function
             data <o> Event data
@@ -78,13 +78,13 @@ Ox.Event = (function() {
     };
 
     /*@
-    .bindOnce <f> Adds an event handler that fires once
+    .bindOnce <f> Adds event handler(s) that run(s) only once
         (self, callback) -> <o> Ox.Event
-            Add a catch-all event handler
+            Adds a catch-all handler
         (self, event, callback) -> <o> Ox.Event
-            Add an event handler for a single event
+            Adds an event handler for a single event
         (self, {event: callback, ...}) -> <o> Ox.Event
-            Add event handlers for multiple events
+            Adds event handlers for multiple events
         self <o> The element's shared private object
         callback <f> Callback function
             data <o> Event data
@@ -110,11 +110,11 @@ Ox.Event = (function() {
     /*@
     .trigger <f> Triggers an event
         (self, event) -> <o> Ox.Event
-            Trigger an event
+            Triggers an event
         (self, event, data) -> <o> Ox.Event
-            Trigger an event with event data
+            Triggers an event with data
         (self, {event: data, ...}) -> Ox.Event
-            Trigger multiple events with event data
+            Triggers multiple events with data
         self <o> The element's shared private object
         event <s> Event name
         data <o> Event data
@@ -144,19 +144,19 @@ Ox.Event = (function() {
     /*@
     .unbind <f> Removes an event handler
         () -> Ox.Event
-            Remove all global event handlers
+            Removes all global handlers
         (callback) -> <o> Ox.Event
-            Remove a global event handler
+            Removes a global handler
         (self) -> <o> Ox.Event
-            Remove all event handlers
+            Removes all handlers
         (self, callback) -> <o> Ox.Event
-            Unbind a specific catch-all event handler
+            Removes a specific catch-all handler
         (self, event) -> <o> Ox.Event
-            Unbind all event handlers for a single event
+            Remove all handlers for a single event
         (self, event, callback) -> <o> Ox.Event
-            Unbind a specific event handler for a single event
+            Removes a specific handler for a single event
         (self, {event: callback, ...}) -> <o> Ox.Event
-            Unbind specific event handlers for multiple events
+            Removes specific event handlers for multiple events
         self <o> The element's shared private object
         callback <f> Callback function
         event <s> Event name