efl/gesture: improve docs

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

src/lib/evas/gesture/efl_canvas_gesture.eo

@@ -27,7 +27,8 @@ abstract @beta Efl.Canvas.Gesture extends Efl.Object
       }
       @property hotspot {
          [[Hotspot of the gesture currently being analyzed.
-           The exact meaning depends on the gesture type.]]
+           The exact meaning depends on the gesture type, but by default it
+           reflects the current position of the last touch event.]]
          get {
          }
          set {
@@ -43,7 +44,7 @@ abstract @beta Efl.Canvas.Gesture extends Efl.Object
          set {
          }
          values {
-            timestamp: uint;[[The time-stamp.]]
+            timestamp: uint;[[The time-stamp, valued in milliseconds.]]
          }
       }
       @property touch_count {

src/lib/evas/gesture/efl_canvas_gesture_custom.eo

@@ -7,6 +7,9 @@ class @beta Efl.Canvas.Gesture_Custom extends Efl.Canvas.Gesture
      @[Efl.Canvas.Gesture_Events.gesture,custom] for a description of the Custom gesture.
 
      Application developers receive these objects inside a gesture event and do not typically need to create their own.
+
+     Custom gesture recognizers which implement their own gesture properties (e.g., gesture momentum or angle) must
+     inherit this class.
    ]]
    c_prefix: efl_gesture_custom;
    methods {

src/lib/evas/gesture/efl_canvas_gesture_manager.eo

@@ -5,8 +5,8 @@ class @beta Efl.Canvas.Gesture_Manager extends Efl.Object
    [[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.
+     This class defines methods to manage gesture recognizers and handles passing input events
+     to the recognizers that it manages.
    ]]
    c_prefix: efl_gesture_manager;
    methods {

src/lib/evas/gesture/efl_canvas_gesture_recognizer.eo

@@ -14,7 +14,8 @@ abstract @beta Efl.Canvas.Gesture_Recognizer extends Efl.Object
    c_prefix: efl_gesture_recognizer;
    methods {
       @property type @pure_virtual {
-         [[This property returns the type of gesture recognized by this recognizer.]]
+         [[This property returns the type of gesture recognized by this recognizer.
+           It must be implemented for the recognizer to function.]]
          get {}
          values {
             type: Efl.Canvas.Gesture_Recognizer_Type; [[The gesture type to recognize.]]
@@ -26,6 +27,8 @@ abstract @beta Efl.Canvas.Gesture_Recognizer extends Efl.Object
 
            Updates the state of the gesture object as required, and returns a
            suitable result for the current recognition step.
+
+           This method must be implemented for the recognizer to function.
          ]]
          params {
             @in gesture: Efl.Canvas.Gesture; [[The gesture object.]]

src/lib/evas/gesture/efl_canvas_gesture_recognizer_custom.eo

@@ -2,6 +2,10 @@ abstract @beta Efl.Canvas.Gesture_Recognizer_Custom extends Efl.Canvas.Gesture_R
 {
    [[This is the recognizer for Custom gestures.
      See @Efl.Canvas.Gesture_Recognizer.
+
+     Custom-written recognizers must inherit this class.
+     They are responsible for managing and updating the state of the recognized @Efl.Canvas.Gesture object inside
+     their implementation of the @Efl.Canvas.Gesture_Recognizer.recognize method, which is required.
    ]]
    c_prefix: efl_gesture_recognizer_custom;
    methods {

src/lib/evas/gesture/efl_canvas_gesture_types.eot

@@ -1,25 +1,26 @@
 import eina_types;
 import efl_input_types;
+import efl_canvas_gesture_events;
 
 enum @beta Efl.Canvas.Gesture_Touch_State
 {
    [[ This enum type describes the state of a touch event. ]]
    legacy: efl_gesture_touch_state;
-   unknown = 0, [[Gesture Touch State unknown]]
-   begin ,      [[First fingure touch down]]
-   update,      [[fingure touch update]]
-   end,         [[Last fingure touch up]]
+   unknown = 0, [[Touch state is unset.]]
+   begin,       [[First touch point has just been added.]]
+   update,      [[A touch point position has updated or other touch points were added.]]
+   end,         [[A touch point has been released.]]
 }
 
 enum @beta Efl.Canvas.Gesture_State
 {
    [[ This enum type describes the state of a gesture. ]]
    legacy: efl_gesture_state;
-   none    = 0, [[No gesture state]]
-   started = 1, [[A continuous gesture has started.]]
-   updated,     [[A gesture continues.]]
-   finished,    [[A gesture has finished.]]
-   canceled,    [[A gesture was canceled.]]
+   none    = 0, [[No gesture state.]]
+   started = 1, [[A gesture has started.]]
+   updated,     [[A gesture has triggered.]]
+   finished,    [[A gesture has ended and has triggered.]]
+   canceled,    [[A gesture has ended without triggering.]]
 }
 
 enum @beta Efl.Canvas.Gesture_Recognizer_Result
@@ -28,37 +29,37 @@ enum @beta Efl.Canvas.Gesture_Recognizer_Result
    legacy: efl_gesture_recognizer_result;
 
    ignore    = 0x0001, [[The event does not change the state of the recognizer.]]
-   maybe     = 0x0002, [[The event changed the internal state of the recognizer, but it isn't clear yet if it is a  gesture or not. The recognizer needs to filter more events to decide.]]
+   maybe     = 0x0002, [[The event changed the internal state of the recognizer, but it isn't clear yet if it is a gesture or not. The recognizer needs to filter more events to decide.]]
    trigger   = 0x0004, [[The gesture has been triggered]]
-   finish    = 0x0008, [[The gesture has been finished successfully.]]
+   finish    = 0x0008, [[The gesture has been finished successfully and the gesture triggered.]]
    cancel    = 0x0010, [[The event made it clear that it is not a gesture. If the gesture recognizer was in Triggered state before, then the gesture is canceled.]]
    result_mask = 0x00ff, [[The gesture result mask]]
 }
 
 enum @beta Efl.Canvas.Gesture_Recognizer_Type
 {
-   [[ This enum type describes the state of a touch event. ]]
+   [[ This enum type describes the type of gesture recognized by a given recognizer. ]]
    legacy: efl_gesture_recognizer_type;
-   tap = 0,
-   double_tap,
-   triple_tap,
-   long_tap,
-   momentum,
-   flick,
-   zoom,
-   custom,
+   tap = 0, [[See @[Efl.Canvas.Gesture_Events.gesture,tap] ]]
+   double_tap, [[See @[Efl.Canvas.Gesture_Events.gesture,double_tap] ]]
+   triple_tap, [[See @[Efl.Canvas.Gesture_Events.gesture,triple_tap] ]]
+   long_tap, [[See @[Efl.Canvas.Gesture_Events.gesture,long_tap] ]]
+   momentum, [[See @[Efl.Canvas.Gesture_Events.gesture,momentum] ]]
+   flick, [[See @[Efl.Canvas.Gesture_Events.gesture,flick] ]]
+   zoom, [[See @[Efl.Canvas.Gesture_Events.gesture,zoom] ]]
+   custom, [[See @[Efl.Canvas.Gesture_Events.gesture,custom] ]]
 }
 
 struct @beta @c_name(Efl_Gesture_Touch_Point_Info) Efl.Canvas.Gesture_Touch_Point_Info {
    [[This struct represents the underlying data of a touch point.]]
    pos: Eina.Position2D; [[The canvas position of the touch point data.]]
-   pressed: bool; [[Whether this touch point is being pressed down.]]
-   timestamp: uint; [[The timestamp of the touch point data.]]
+   pressed: bool; [[Whether this touch point is currently being pressed down.]]
+   timestamp: uint; [[The timestamp of the touch point data in milliseconds.]]
 }
 
 struct @beta @c_name(Efl_Gesture_Touch_Point_Data) Efl.Canvas.Gesture_Touch_Point_Data {
     [[This struct represents the state of a touch point.]]
-    id: int; [[Touch id of the point.]]
+    id: int; [[Touch id of the point, where the first point is $0.]]
     action: Efl.Pointer.Action; [[The last event with this point.]]
     start: Efl.Canvas.Gesture_Touch_Point_Info; [[The start data for the touch point.]]
     prev: Efl.Canvas.Gesture_Touch_Point_Info; [[The previous data for the touch point.]]