event-controller: Document SugarTouchController

Also set up introspection annotations wherever it's needed

Signed-off-by: Carlos Garnacho <carlos@lanedo.com>
Acked-by: Simon Schampijer <simon@laptop.org>

src/sugar3/event-controller/Makefile.am

@@ -55,10 +55,11 @@ INTROSPECTION_GIRS = SugarEventController-1.0.gir
 INTROSPECTION_SCANNER_ARGS = --identifier-prefix=Sugar --symbol-prefix=sugar
 SugarEventController_1_0_gir_LIBS = libsugar-eventcontroller.la
 SugarEventController_1_0_gir_FILES =	\
+	$(BUILT_SOURCES)		\
 	$(eventcontroller_h_sources)	\
 	$(eventcontroller_c_sources)
 SugarEventController_1_0_gir_CFLAGS =	\
-	-DSUGAR_TOOLKIT_COMPILATION
+	-DSUGAR_TOOLKIT_COMPILATION --warn-all
 
 SugarEventController_1_0_gir_INCLUDES = Gtk-3.0 Gdk-3.0
 SugarEventController_1_0_gir_PACKAGES = gtk+-3.0 gdk-3.0

src/sugar3/event-controller/sugar-touch-controller.c

@@ -221,6 +221,17 @@ sugar_touch_controller_init (SugarTouchController *controller)
                                          (GDestroyNotify) g_free);
 }
 
+/**
+ * sugar_touch_controller_get_center:
+ * @controller: a #SugarTouchController
+ * @center_x: (out) (transfer none): Return location for the X axis of the bounding box center
+ * @center_y: (out) (transfer none): Return location for the Y axis of the bounding box center
+ *
+ * If a gesture is ongoing, this function returns the center of
+ * the bounding box containing all ongoing touches.
+ *
+ * Returns: %TRUE if a gesture is in progress
+ **/
 gboolean
 sugar_touch_controller_get_center (SugarTouchController *controller,
                                    gint                 *center_x,
@@ -234,6 +245,12 @@ sugar_touch_controller_get_center (SugarTouchController *controller,
   g_return_val_if_fail (SUGAR_IS_TOUCH_CONTROLLER (controller), FALSE);
 
   priv = controller->_priv;
+  x1 = y1 = G_MAXINT;
+  x2 = y2 = G_MININT;
+
+  if (!TOUCHES_IN_RANGE (g_hash_table_size (priv->touches), priv))
+    return FALSE;
+
   g_hash_table_iter_init (&iter, priv->touches);
 
   while (g_hash_table_iter_next (&iter, NULL, (gpointer *) &point))
@@ -255,8 +272,18 @@ sugar_touch_controller_get_center (SugarTouchController *controller,
       dy = y2 - y1;
       *center_y = y1 + (ABS (dy) / 2);
     }
+
+  return TRUE;
 }
 
+/**
+ * sugar_touch_controller_get_num_touches:
+ * @controller: a #SugarTouchController
+ *
+ * Returns the number of touches currently operating on @controller
+ *
+ * Returns: The number of touches
+ **/
 gint
 sugar_touch_controller_get_num_touches (SugarTouchController *controller)
 {
@@ -269,6 +296,14 @@ sugar_touch_controller_get_num_touches (SugarTouchController *controller)
   return g_hash_table_size (priv->touches);
 }
 
+/**
+ * sugar_touch_controller_get_sequences:
+ * @controller: a #SugarTouchController
+ *
+ * Returns the touch sequences currently operating on @controller
+ *
+ * Returns: (element-type Gdk.EventSequence) (transfer container): The list of sequences
+ **/
 GList *
 sugar_touch_controller_get_sequences (SugarTouchController *controller)
 {
@@ -281,6 +316,18 @@ sugar_touch_controller_get_sequences (SugarTouchController *controller)
   return g_hash_table_get_keys (priv->touches);
 }
 
+/**
+ * sugar_touch_controller_get_coords:
+ * @controller: a #SugarTouchController
+ * @sequence: a #GdkEventSequence
+ * @x: (out) (transfer none): Return location for the X coordinate of the touch
+ * @y: (out) (transfer none): Return location for the X coordinate of the touch
+ *
+ * If @sequence is operating on @controller, this function returns %TRUE and
+ * fills in @x and @y with the latest coordinates for that @sequence.
+ *
+ * Returns: %TRUE if @sequence operates on @controller
+ **/
 gboolean
 sugar_touch_controller_get_coords (SugarTouchController *controller,
                                    GdkEventSequence     *sequence,

src/sugar3/event-controller/sugar-touch-controller.h

@@ -54,8 +54,8 @@ struct _SugarTouchControllerClass
 
 GType     sugar_touch_controller_get_type     (void) G_GNUC_CONST;
 gboolean  sugar_touch_controller_get_center   (SugarTouchController *controller,
-                                               gint                 *x,
-                                               gint                 *y);
+                                               gint                 *center_x,
+                                               gint                 *center_y);
 
 gint      sugar_touch_controller_get_num_touches (SugarTouchController *controller);
 GList   * sugar_touch_controller_get_sequences   (SugarTouchController *controller);