eo: improve documentation for event forwarder.

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

1 files changed, 24 insertions, 4 deletions

diff --git a/src/lib/eo/efl_object.eo b/src/lib/eo/efl_object.eo
index 31ff5304e8..6049ceb29a 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]]