From: Cedric BAIL <cedric.bail@free.fr>
Date: Wed, 2 Jan 2019 23:26:53 +0000 (-0800)
Subject: eo: improve documentation for event forwarder.
X-Git-Tag: submit/tizen/20190116.045417~30
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=f47977c6389d44664b6ef7868dcf3c7db89d2d51;p=platform%2Fupstream%2Fefl.git

eo: improve documentation for event forwarder.

Reviewed-by: Xavi Artigas <xavierartigas@yahoo.es>
Differential Revision: https://phab.enlightenment.org/D7532
---

diff --git a/src/lib/eo/Eo.h b/src/lib/eo/Eo.h
index a6aa5b9..21a4bf2 100644
--- a/src/lib/eo/Eo.h
+++ b/src/lib/eo/Eo.h
@@ -2017,7 +2017,7 @@ EAPI int efl_callbacks_cmp(const Efl_Callback_Array_Item *a, const Efl_Callback_
 /**
  * @def efl_event_callback_add(obj, desc, cb, data)
  * Add a callback for an event.
- * @param[in] desc The description of the event to listen to.
+ * @param[in] desc An #Efl_Event_Description of the event to listen to.
  * @param[in] cb the callback to call.
  * @param[in] data additional data to pass to the callback.
  *
@@ -2033,6 +2033,7 @@ EAPI int efl_callbacks_cmp(const Efl_Callback_Array_Item *a, const Efl_Callback_
  * @def efl_event_callback_array_add(obj, desc, cb, data)
  * Add an array of callbacks for an event.
  *
+ * @param[in] obj The object.
  * @param[in] array an #Efl_Callback_Array_Item of events to listen to.
  * @param[in] data additional data to pass to the callback.
  *
@@ -2053,7 +2054,7 @@ EAPI int efl_callbacks_cmp(const Efl_Callback_Array_Item *a, const Efl_Callback_
  * @brief Add an event callback forwarder for an event and an object.
  *
  * @param[in] obj The object.
- * @param[in] desc The description of the event to listen to
+ * @param[in] desc An #Efl_Event_Description of the event to forward to.
  * @param[in] new_obj The object to emit events from
  *
  * @ingroup Efl_Object
diff --git a/src/lib/eo/efl_object.eo b/src/lib/eo/efl_object.eo
index 31ff530..6049ceb 100644
--- a/src/lib/eo/efl_object.eo
+++ b/src/lib/eo/efl_object.eo
@@ -13,6 +13,10 @@ type Efl.Callback_Priority : short;
 [[
   Callback priority. Range is -32k - 32k. The lower the number, the higher the priority.
 
+  This is used to insert an event handler relative to the existing stack of sorted event
+  handlers according to that priority. All event handlers always have a priority. If not
+  specified @Efl.Callback_Priority_Default is to be assumed.
+
   See @Efl.Callback_Priority_Before @Efl.Callback_Priority_Default  @Efl.Callback_Priority_After
  ]]
 
@@ -245,15 +249,31 @@ abstract Efl.Object
          ]]
       }
       event_callback_forwarder_priority_add {
-         [[Add an event callback forwarder for an event and an object.]]
+         [[Add an event callback forwarder that will make this object emit an event whenever another
+         object ($source) emits it. The event is said to be forwarded from $source to this object.
+
+         The event is unaffected on $source and behave like any other event being propagated on
+         any object and will trigger all the handler registered on $source like nothing special
+         happened.
+
+         This allow object that hide internally another object to easily be able to propagate an event
+         without the need to add custom handler.
+
+         Note: The priority is used to make sure that you are intercepting the event when you expect
+         by inserting a handler at the right position in the stack of event handler on the object that
+         emit the event.]]
          params {
             @cref desc: Efl.Event_Description; [[The description of the event to listen to]]
-            @in priority: short; [[The priority at which to insert the callback handler.]]
-            @in new_obj: Efl.Object @nonull; [[The object to emit events from]]
+            @in priority: Efl.Callback_Priority; [[The priority at which to insert the event forwarder handler
+            in the existing list of handler on the source of event object. The lower the number, the higher
+            the priority. As a shortcut @Efl.Callback_Priority_Before,
+            @Efl.Callback_Priority_Default and @Efl.Callback_Priority_After can be used. See
+            @Efl.Callback_Priority for more details.]]
+            @in source: Efl.Object @nonull; [[The object which emits the initial event]]
          }
       }
       event_callback_forwarder_del {
-         [[Remove an event callback forwarder for an event and an object.]]
+         [[Remove an event callback forwarder for a specified event and object.]]
          params {
             @cref desc: Efl.Event_Description; [[The description of the event to listen to]]
             @in new_obj: Efl.Object @nonull; [[The object to emit events from]]