docs: Update documentation on Gestures

We need to keep in mind that the Manager and the Recognizers are not visible to the user.
The user only sees the events and the different Efl.Canvas.Gesture_* payloads.

18 files changed, 170 insertions, 133 deletions

diff --git a/src/lib/evas/gesture/efl_canvas_gesture.eo b/src/lib/evas/gesture/efl_canvas_gesture.eo
index b76aac0936..eaced25ad8 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture.eo
@@ -1,44 +1,49 @@
 import efl_canvas_gesture_types;
+parse efl_gesture_events;
 
 abstract @beta Efl.Canvas.Gesture extends Efl.Object
 {
-   [[EFL Gesture abstract class
+   [[Base abstract class to support gesture-specific classes.
 
-     A gesture class defines a method that specific gesture event and privides information
-     about the gesture's type, state, and associated pointer information.
+     A gesture object holds the current state of that gesture (i.e. whether the gesture has
+     just been started, it is in progress or it has finished) along with any gesture-specific
+     information it needs (like the number of taps so far, to detect triple-taps, for example).
 
-     For cetain gesture types, additional methods are defined to provide meaningful gesture
-     information to the user.]]
+     Typically this class is not used directly, instead, some sub-class of it (like
+     @Efl.Canvas.Gesture_Tap or @Efl.Canvas.Gesture_Zoom) is retrieved from gesture events
+     (like @[Efl.Gesture.Events.gesture,tap] or @[Efl.Gesture.Events.gesture,zoom]).
+   ]]
    c_prefix: efl_gesture;
    methods {
       @property state {
-         [[This property holds the current state of the gesture.]]
+         [[Current state of the gesture, from initial detection to successful recognition.]]
          get {
          }
          set {
          }
          values {
-            state: Efl.Canvas.Gesture_State; [[gesture state]]
+            state: Efl.Canvas.Gesture_State; [[State.]]
          }
       }
       @property hotspot {
-         [[This property holds the hotspot of the current gesture.]]
+         [[Hotspot of the gesture currently being analyzed.
+           The exact meaning depends on the gesture type.]]
          get {
          }
          set {
          }
          values {
-            hotspot: Eina.Position2D;[[hotspot co-ordinate]]
+            hotspot: Eina.Position2D;[[Hotspot coordinates.]]
          }
       }
       @property timestamp {
-         [[This property holds the timestamp of the current gesture.]]
+         [[Moment when the gesture currently being analyzed started.]]
          get {
          }
          set {
          }
          values {
-            timestamp: uint;[[The timestamp]]
+            timestamp: uint;[[The time-stamp.]]
          }
       }
    }
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_double_tap.eo b/src/lib/evas/gesture/efl_canvas_gesture_double_tap.eo
index 5a0b1bc57b..87b93ccd9c 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_double_tap.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_double_tap.eo
@@ -1,9 +1,9 @@
 class @beta Efl.Canvas.Gesture_Double_Tap extends Efl.Canvas.Gesture
 {
-   [[EFL Gesture Double Tap class
-   
-     A gesture class defines a method that double tap gesture event and provides information
-     about the double tap gesture's type, state and associated pointer information.]]
+   [[Double-tap gesture class holding state information.
+     See @Efl.Canvas.Gesture to see what this state is and
+     @[Efl.Gesture.Events.gesture,double_tap] for a description of the Double-tap gesture.
+   ]]
    data: null;
    c_prefix: efl_gesture_double_tap;
    implements {
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_flick.eo b/src/lib/evas/gesture/efl_canvas_gesture_flick.eo
index b0c6f4bcd2..afc8391550 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_flick.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_flick.eo
@@ -2,20 +2,21 @@ import eina_types;
 
 class @beta Efl.Canvas.Gesture_Flick extends Efl.Canvas.Gesture
 {
-   [[EFL Gesture Flick class
-   
-     This gesture class defines a method that flick gesture event and provides
-     information about the flick gesture's type, state, and associated pointer
-     information.]]
+   [[Flick gesture class holding state information.
+     See @Efl.Canvas.Gesture to see what this state is and
+     @[Efl.Gesture.Events.gesture,flick] for a description of the Flick gesture.
+   ]]
    c_prefix: efl_gesture_flick;
    methods {
       momentum_get {
-         [[Gets flick gesture momentum value]]
-         return: Eina.Vector2; [[The momentum vector]]
-	  }
+         [[Gets flick gesture momentum value, this is, the direction in which the
+           pointer was flicked.]]
+         return: Eina.Vector2; [[The momentum vector.]]
+      }
       angle_get {
-         [[Gets flick direction angle]]
-         return: double; [[The angle value]]
+         [[Gets flick gesture direction angle, this is, the angle in which the
+           pointer was flicked.]]
+         return: double; [[The angle value.]]
       }
    }
    implements {
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_long_tap.eo b/src/lib/evas/gesture/efl_canvas_gesture_long_tap.eo
index e9de7225b2..6c0d0c979d 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_long_tap.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_long_tap.eo
@@ -1,10 +1,9 @@
 class @beta Efl.Canvas.Gesture_Long_Tap extends Efl.Canvas.Gesture
 {
-   [[EFL Gesture Long Tap class
-   
-     This gesture class defines a method that long tap gesture event and provides
-     information about the long tap gesture's type, state and associated pointer
-     information.]]
+   [[Long-tap gesture class holding state information.
+     See @Efl.Canvas.Gesture to see what this state is and
+     @[Efl.Gesture.Events.gesture,long_tap] for a description of the Long-tap gesture.
+   ]]
    data: null;
    c_prefix: efl_gesture_long_tap;
    implements {
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_manager.eo b/src/lib/evas/gesture/efl_canvas_gesture_manager.eo
index 2e52f6ace8..8e5d75dead 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_manager.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_manager.eo
@@ -1,41 +1,43 @@
 class @beta Efl.Canvas.Gesture_Manager extends Efl.Object
 {
-   [[EFL Gesture Manager class
+   [[This class keeps track of active @Efl.Canvas.Gesture_Recognizer objects.
+     For internal use only.
    
      This gesture class defines methods that register and unregister a recognizer and
-     get a recognizer according to gesture event type.]]
+     get a recognizer according to gesture event type.
+   ]]
    c_prefix: efl_gesture_manager;
    methods {
       recognizer_register {
-         [[This function is called to register a new Efl.Canvas.Gesture_Recognizer]]
+         [[Registers a new @Efl.Canvas.Gesture_Recognizer.]]
          params {
-            @in recognizer: Efl.Canvas.Gesture_Recognizer; [[The gesture recognizer object]]
+            @in recognizer: Efl.Canvas.Gesture_Recognizer; [[The gesture recognizer object.]]
          }
       }
       recognizer_unregister {
-         [[This function is called to unregister a Efl.Canvas.Gesture_Recognizer]]
+         [[Unregisters an existing @Efl.Canvas.Gesture_Recognizer.]]
          params {
-            @in recognizer: Efl.Canvas.Gesture_Recognizer; [[The gesture recognizer object]]
+            @in recognizer: Efl.Canvas.Gesture_Recognizer; [[The gesture recognizer object.]]
          }
       }
       recognizer_get {
-         [[Gets event type's recognizer]]
+         [[Returns the event recognizer object associated with the given $gesture_type.]]
          params {
-            @in gesture_type: Efl.Canvas.Gesture_Recognizer_Type; [[The gesture event type]]
+            @in gesture_type: Efl.Canvas.Gesture_Recognizer_Type; [[The gesture event type.]]
          }
-         return: const(Efl.Canvas.Gesture_Recognizer); [[The gesture recognizer]]
+         return: const(Efl.Canvas.Gesture_Recognizer); [[The gesture recognizer.]]
       }
       @property config {
-         [[This property holds the config value for the recognizer]]
+         [[This property holds configuration values for the recognizer.]]
          set {
          }
          get {
          }
          keys {
-            name: string; [[propery name]]
+            name: string; [[Property name.]]
          }
          values {
-            value: any_value_ptr; [[value of the property]]
+            value: any_value_ptr; [[Value of the property.]]
          }
       }
    }
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_momentum.eo b/src/lib/evas/gesture/efl_canvas_gesture_momentum.eo
index 1cea8b1949..0f78ad69aa 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_momentum.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_momentum.eo
@@ -2,15 +2,15 @@ import eina_types;
 
 class @beta Efl.Canvas.Gesture_Momentum extends Efl.Canvas.Gesture
 {
-   [[EFL Gesture Momentum class
-   
-     This gesture class defines a method to get momentum value of specific
-     gesture event such as flick.]]
+   [[Momentum gesture class holding state information.
+     See @Efl.Canvas.Gesture to see what this state is and
+     @[Efl.Gesture.Events.gesture,momentum] for a description of the Momentum gesture.
+   ]]
    c_prefix: efl_gesture_momentum;
    methods {
       momentum_get {
-         [[Gets momentum value]]
-         return: Eina.Vector2; [[The momentum vector]]
+         [[Gets the momentum value, this is, the direction in which the action occurred.]]
+         return: Eina.Vector2; [[The momentum vector.]]
       }
    }
    implements {
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_recognizer.eo b/src/lib/evas/gesture/efl_canvas_gesture_recognizer.eo
index aaee7d29b1..c12274b899 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_recognizer.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_recognizer.eo
@@ -2,53 +2,53 @@ import efl_canvas_gesture_types;
 
 abstract @beta Efl.Canvas.Gesture_Recognizer extends Efl.Object
 {
-   [[EFL Gesture Recognizer abstract class
+   [[Base abstract class for Gesture Recognizers. For internal use only.
 
-     The gesture recognizer class grabs events that occur on the target
-     object that user register to see if a particluar gesture has occurred.
+     Gesture recognizers listen to events that occur on a target object
+     to see if a particular gesture has occurred.
 
-     Uesr can adjust the config value involved in gesture recognition
-     through the method provided by the gesture recognizer.
-
-     The default config values follow the system default config value.]]
+     Recognizer-specific configuration values can be modified through @.config.
+     Default configuration values are taken from the system's configuration.
+   ]]
    c_prefix: efl_gesture_recognizer;
    methods {
       add @pure_virtual {
-         [[This function is called to create a new Efl.Canvas.Gesture object for the given target]]
+         [[This function is called to create a new @Efl.Canvas.Gesture object for the given target.]]
          params {
-            @in target: Efl.Object; [[The target widget]]
+            @in target: Efl.Object; [[The target canvas object.]]
          }
-         return: Efl.Canvas.Gesture; [[Returns the Efl.Canvas.Gesture event object]]
+         return: Efl.Canvas.Gesture; [[Returns the gesture object that will be used to track this gesture.]]
       }
       recognize @pure_virtual {
-         [[Handles the given event for the watched object.
+         [[Analyzes the given $event and the current state of the $gesture object to see if the state
+           has to be modified. For example, to signal a complete gesture detection.
 
            Updates the state of the gesture object as required, and returns a
            suitable result for the current recognition step.
          ]]
          params {
-            @in gesture: Efl.Canvas.Gesture; [[The gesture object]]
-            @in watched: Efl.Object; [[The watched object]]
-            @in event: Efl.Canvas.Gesture_Touch; [[The pointer event]]
+            @in gesture: Efl.Canvas.Gesture; [[The gesture object.]]
+            @in watched: Efl.Object; [[The target canvas object.]]
+            @in event: Efl.Canvas.Gesture_Touch; [[The pointer event being analyzed.]]
          }
-         return: Efl.Canvas.Gesture_Recognizer_Result; [[Returns the Efl.Canvas.Gesture event object]]
+         return: Efl.Canvas.Gesture_Recognizer_Result; [[Returns the result of the analysis.]]
       }
       /* FIXME: This function is not used? */
       reset {
          [[This function is called by the framework to reset a given gesture.]]
          params {
-            @in gesture: Efl.Canvas.Gesture; [[The gesture object]]
+            @in gesture: Efl.Canvas.Gesture; [[The gesture object.]]
          }
       }
       @property config {
-         [[This property holds the config value for the recognizer]]
+         [[This property holds configuration values for the recognizer.]]
          get {
          }
          keys {
-            name: string; [[propery name]]
+            name: string; [[Property name.]]
          }
          values {
-            value: any_value_ptr; [[value of the property]]
+            value: any_value_ptr; [[Value of the property.]]
          }
       }
    }
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_double_tap.eo b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_double_tap.eo
index 24e35f54dc..de229b7147 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_double_tap.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_double_tap.eo
@@ -1,19 +1,19 @@
 class @beta Efl.Canvas.Gesture_Recognizer_Double_Tap extends Efl.Canvas.Gesture_Recognizer
 {
-   [[EFL Gesture Recognizer Double Tap class
-   
-     This gesture recognizer class grabs double tap gesture events that occur on
-     target object that user register.]]
+   [[This is the recognizer for Double-Tap gestures.
+     See @Efl.Canvas.Gesture_Double_Tap and @Efl.Canvas.Gesture_Recognizer.
+     For internal use only.
+   ]]
    c_prefix: efl_gesture_recognizer_double_tap;
    methods {
       @property timeout {
-         [[Sets the time between taps to be recognized as a double tap]]
+         [[Maximum time between taps to be recognized as a double tap.]]
          set {
          }
          get {
          }
          values {
-            time: double; [[Allowed time gap value]]
+            time: double; [[Time in seconds.]]
          }
       }
    }
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_flick.eo b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_flick.eo
index e8d8c83aac..5f038f1a17 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_flick.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_flick.eo
@@ -1,9 +1,9 @@
 class @beta Efl.Canvas.Gesture_Recognizer_Flick extends Efl.Canvas.Gesture_Recognizer
 {
-   [[EFL Gesture Recognizer Flick Class
-   
-     This gesture recognizer class grabs flick gesture events that occur on
-     the target object that user register.]]
+   [[This is the recognizer for Flick gestures.
+     See @Efl.Canvas.Gesture_Flick and @Efl.Canvas.Gesture_Recognizer.
+     For internal use only.
+   ]]
    c_prefix: efl_gesture_recognizer_flick;
    implements {
       Efl.Canvas.Gesture_Recognizer.add;
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_long_tap.eo b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_long_tap.eo
index e3efea44ff..d18d2c236f 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_long_tap.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_long_tap.eo
@@ -1,19 +1,19 @@
 class @beta Efl.Canvas.Gesture_Recognizer_Long_Tap extends Efl.Canvas.Gesture_Recognizer
 {
-   [[EFL Gesture Recognizer Long Tap class
-   
-     This gesture recognizer class grabs long tap gesture events that occur
-     on the target that user register.]]
+   [[This is the recognizer for Long-tap gestures.
+     See @Efl.Canvas.Gesture_Long_Tap and @Efl.Canvas.Gesture_Recognizer.
+     For internal use only.
+   ]]
    c_prefix: efl_gesture_recognizer_long_tap;
    methods {
       @property timeout {
-         [[Sets the holding time to be recognized as a long tap.]]
+         [[Minimum holding time to be recognized as a long tap.]]
          set {
          }
          get {
          }
          values {
-            time: double; [[Allowed time gap value]]
+            time: double; [[Time in seconds.]]
          }
       }
    }
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_momentum.eo b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_momentum.eo
index e52abdc483..1713fb4f68 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_momentum.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_momentum.eo
@@ -1,9 +1,9 @@
 class @beta Efl.Canvas.Gesture_Recognizer_Momentum extends Efl.Canvas.Gesture_Recognizer
 {
-   [[EFL Gesture Recognizer Momentum class
-   
-     This gesture recognizer class grabs monentum based gesture events such as
-	 from flick on the target object that user register.]]
+   [[This is the recognizer for Momentum gestures.
+     See @Efl.Canvas.Gesture_Momentum and @Efl.Canvas.Gesture_Recognizer.
+     For internal use only.
+   ]]
    c_prefix: efl_gesture_recognizer_momentum;
    implements {
       Efl.Canvas.Gesture_Recognizer.add;
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_tap.eo b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_tap.eo
index 5eefcdcd4c..26aeb83a4d 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_tap.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_tap.eo
@@ -1,9 +1,9 @@
 class @beta Efl.Canvas.Gesture_Recognizer_Tap extends Efl.Canvas.Gesture_Recognizer
 {
-   [[EFL Gesture Recognizer Tap class
-   
-     This gesture recognizer class grabs tap based gesture events that occur on
-	 the target object that user register.]]
+   [[This is the recognizer for Tap gestures.
+     See @Efl.Canvas.Gesture_Tap and @Efl.Canvas.Gesture_Recognizer.
+     For internal use only.
+   ]]
    c_prefix: efl_gesture_recognizer_tap;
    implements {
       Efl.Canvas.Gesture_Recognizer.add;
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_triple_tap.eo b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_triple_tap.eo
index dbb5ca6a6b..99458938fa 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_triple_tap.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_triple_tap.eo
@@ -1,21 +1,21 @@
 class @beta Efl.Canvas.Gesture_Recognizer_Triple_Tap extends Efl.Canvas.Gesture_Recognizer
 {
-   [[EFL Gesture Recognizer Triple Tap class
-   
-     This gesture recognizer class grabs triple tap gesture events that occur on the
-     target object that user register.]]
+   [[This is the recognizer for Triple-tap gestures.
+     See @Efl.Canvas.Gesture_Triple_Tap and @Efl.Canvas.Gesture_Recognizer.
+     For internal use only.
+   ]]
    c_prefix: efl_gesture_recognizer_triple_tap;
    methods {
       @property timeout {
-         [[Sets the time between taps to be recognized as a double tap.]]
+         [[Minimum time between each consecutive tap to be recognized as a triple tap.]]
          set {
-		 }
-		 get {
-		 }
-		 values {
-            time: double; [[Time value.]]
-		 }
-	  }
+         }
+         get {
+         }
+         values {
+            time: double; [[Time in seconds.]]
+         }
+      }
    }
    implements {
       Efl.Object.destructor;
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_zoom.eo b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_zoom.eo
index b93a49d7e5..a07e112d87 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_zoom.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_zoom.eo
@@ -1,9 +1,9 @@
 class @beta Efl.Canvas.Gesture_Recognizer_Zoom extends Efl.Canvas.Gesture_Recognizer
 {
-   [[EFL Gesture Recognizer Zoom class
-   
-     This gesture recognizer class grabs zoom gesture events that occur on the
-     target object that user register.]]
+   [[This is the recognizer for Zoom gestures.
+     See @Efl.Canvas.Gesture_Zoom and @Efl.Canvas.Gesture_Recognizer.
+     For internal use only.
+   ]]
    c_prefix: efl_gesture_recognizer_zoom;
    implements {
       Efl.Canvas.Gesture_Recognizer.add;
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_tap.eo b/src/lib/evas/gesture/efl_canvas_gesture_tap.eo
index 1f108f83c2..0e940608d3 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_tap.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_tap.eo
@@ -1,10 +1,9 @@
 class @beta Efl.Canvas.Gesture_Tap extends Efl.Canvas.Gesture
 {
-   [[EFL Gesture Tap class
-   
-     This gesture class defines a method that tap gesture event and provides
-     information about the tap gesture's type, state, and associated pointer
-     information.]]
+   [[Tap gesture class holding state information.
+     See @Efl.Canvas.Gesture to see what this state is and
+     @[Efl.Gesture.Events.gesture,tap] for a description of the Tap gesture.
+   ]]
    data: null;
    c_prefix: efl_gesture_tap;
    implements {
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_triple_tap.eo b/src/lib/evas/gesture/efl_canvas_gesture_triple_tap.eo
index 2b58c759b8..abedc442d4 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_triple_tap.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_triple_tap.eo
@@ -1,10 +1,9 @@
 class @beta Efl.Canvas.Gesture_Triple_Tap extends Efl.Canvas.Gesture
 {
-   [[EFL Gesture Triple Tap class
-   
-     This gesture class defines a method that triple tap gesture event and provides
-     information about the triple tap gesture's type, state and associated pointer
-     information.]]
+   [[Triple-tap gesture class holding state information.
+     See @Efl.Canvas.Gesture to see what this state is and
+     @[Efl.Gesture.Events.gesture,triple_tap] for a description of the Triple-tap gesture.
+   ]]
    data: null;
    c_prefix: efl_gesture_triple_tap;
    implements {
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_zoom.eo b/src/lib/evas/gesture/efl_canvas_gesture_zoom.eo
index 51b5cea1ad..7137689a7c 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_zoom.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_zoom.eo
@@ -1,19 +1,21 @@
 class @beta Efl.Canvas.Gesture_Zoom extends Efl.Canvas.Gesture
 {
-   [[EFL Gesture Zoom class
-   
-     This gesture class defines methods to get zoom center point and zoom value
-     and provides information about the zoom gesture's type, state and associated
-     pointer information.]]
+   [[Zoom gesture class holding state information.
+     See @Efl.Canvas.Gesture to see what this state is and
+     @[Efl.Gesture.Events.gesture,zoom] for a description of the Flick gesture.
+   ]]
    c_prefix: efl_gesture_zoom;
    methods {
       radius_get {
-         [[Gets zoom center point reported to user]]
-         return: double; [[The radius value]]
+         [[Gets the current radius (i.e. the distance between the two fingers) of the gesture.]]
+         return: double; [[The radius value in pixels.]]
       }
       zoom_get {
-         [[Gets zoom value. (1.0 means no zoom)]]
-         return: double; [[The zoom value]]
+         [[Gets the current zoom value of the gesture. When the gesture begins, the finger
+           distance is recorded. When the distance becomes greater than the initial one, a
+           zoom value greater than $[1.0] is reported. When it becomes smaller, a zoom value
+           lesser than $[1.0] is reported.]]
+         return: double; [[The zoom value. $[1.0] means no zoom.]]
       }
    }
    implements {
diff --git a/src/lib/evas/gesture/efl_gesture_events.eo b/src/lib/evas/gesture/efl_gesture_events.eo
index df4e874ad8..da67ccc9d2 100644
--- a/src/lib/evas/gesture/efl_gesture_events.eo
+++ b/src/lib/evas/gesture/efl_gesture_events.eo
@@ -2,12 +2,42 @@ interface @beta Efl.Gesture.Events
 {
    event_prefix: efl;
    events {
-      gesture,tap: Efl.Canvas.Gesture_Tap; [[Event for tap gesture]]
-      gesture,double_tap: Efl.Canvas.Gesture_Double_Tap; [[Event for double tap gesture]]
-      gesture,triple_tap: Efl.Canvas.Gesture_Triple_Tap; [[Event for triple tap gesture]]
-      gesture,long_tap: Efl.Canvas.Gesture_Long_Tap; [[Event for long tap gesture]]
-      gesture,momentum: Efl.Canvas.Gesture_Momentum; [[Event for momentum gesture]]
-      gesture,flick: Efl.Canvas.Gesture_Flick; [[Event for flick gesture]]
-      gesture,zoom: Efl.Canvas.Gesture_Zoom; [[Event for zoom gesture]]
+      gesture,tap: Efl.Canvas.Gesture_Tap; [[Emitted when a Tap gesture has been detected.
+        A Tap gesture consists of a touch of the screen (or click of the mouse) quickly followed by
+        a release. If the release happens too late a @[Efl.Gesture.Events.gesture,long_tap] event will be
+        emitted instead.
+      ]]
+
+      gesture,double_tap: Efl.Canvas.Gesture_Double_Tap; [[Emitted when a Double-tap gesture has been detected.
+        A Double-tap gesture consists of two taps on the screen (or clicks of the mouse) in quick
+        succession. If the second one is delayed for too long they will be detected as two independent
+        @[Efl.Gesture.Events.gesture,tap] events.
+      ]]
+
+      gesture,triple_tap: Efl.Canvas.Gesture_Triple_Tap; [[Emitted when a Triple-tap gesture has been detected.
+        A Triple-tap gesture consists of three taps on the screen (or clicks of the mouse) in quick
+        succession. If any of them is delayed for too long they will be detected as independent
+        @[Efl.Gesture.Events.gesture,tap] or @[Efl.Gesture.Events.gesture,double_tap] events.
+      ]]
+
+      gesture,long_tap: Efl.Canvas.Gesture_Long_Tap; [[Emitted when a Long-tap gesture has been detected.
+        A Long-tap gesture consists of a touch of the screen (or click of the mouse) followed by a release
+        after some time. If the release happens too quickly a @[Efl.Gesture.Events.gesture,tap] event will be
+        emitted instead.
+      ]]
+
+      gesture,momentum: Efl.Canvas.Gesture_Momentum; [[Emitted when a Momentum gesture has been detected.
+        A Momentum gesture consists of a quick displacement of the finger while touching the screen (or while
+        holding down a mouse button).
+      ]]
+
+      gesture,flick: Efl.Canvas.Gesture_Flick; [[Emitted when a Flick gesture has been detected.
+      ]]
+
+      gesture,zoom: Efl.Canvas.Gesture_Zoom; [[Emitted when a Zoom gesture has been detected.
+        A Zoom gesture consists of two fingers touching the screen and separating ("zoom in") or
+        getting closer ("zoom out" or "pinch").
+        This gesture cannot be performed with a mouse as it requires more than one pointer.
+      ]]
    }
 }