2008-06-27 Emmanuele Bassi <ebassi@openedhand.com>

* clutter/clutter-event.h:
	* clutter/clutter-main.c:
	* clutter/x11/clutter-backend-x11.c: Add further documentation,
	and increase the coverage to 94%.

ChangeLog

@@ -1,3 +1,10 @@
+2008-06-27  Emmanuele Bassi  <ebassi@openedhand.com>
+
+	* clutter/clutter-event.h:
+	* clutter/clutter-main.c:
+	* clutter/x11/clutter-backend-x11.c: Add further documentation,
+	and increase the coverage to 94%.
+
 2008-06-27  Emmanuele Bassi  <ebassi@openedhand.com>
 
 	* configure.ac: Post release bump to 0.7.7.

clutter/clutter-event.h

@@ -269,6 +269,21 @@ struct _ClutterButtonEvent
   ClutterInputDevice *device; /* Future use */
 };
 
+/**
+ * ClutterCrossingEvent:
+ * @type: event type
+ * @time: event time
+ * @flags: event flags
+ * @stage: event source stage
+ * @source: event source actor
+ * @x: event X coordinate
+ * @y: event Y coordinate
+ * @related: actor related to the crossing
+ *
+ * Event for the movement of the pointer across different actors
+ *
+ * Since: 0.2
+ */
 struct _ClutterCrossingEvent
 {
   ClutterEventType type;
@@ -281,7 +296,23 @@ struct _ClutterCrossingEvent
   ClutterActor *related;
 };
 
-
+/**
+ * ClutterMotionEvent:
+ * @type: event type
+ * @time: event time
+ * @flags: event flags
+ * @stage: event source stage
+ * @source: event source actor
+ * @x: event X coordinate
+ * @y: event Y coordinate
+ * @modifier_state: button modifiers
+ * @axes: reserved for future use
+ * @device: reserved for future use
+ *
+ * Event for the pointer motion
+ *
+ * Since: 0.2
+ */
 struct _ClutterMotionEvent
 {
   ClutterEventType type;
@@ -296,6 +327,24 @@ struct _ClutterMotionEvent
   ClutterInputDevice *device; /* Future use */
 };
 
+/**
+ * ClutterScrollEvent:
+ * @type: event type
+ * @time: event time
+ * @flags: event flags
+ * @stage: event source stage
+ * @source: event source actor
+ * @x: event X coordinate
+ * @y: event Y coordinate
+ * @direction: direction of the scrolling
+ * @modifier_state: button modifiers
+ * @axes: reserved for future use
+ * @device: reserved for future use
+ *
+ * Scroll wheel (or similar device) event
+ *
+ * Since: 0.2
+ */
 struct _ClutterScrollEvent
 {
   ClutterEventType type;
@@ -311,6 +360,20 @@ struct _ClutterScrollEvent
   ClutterInputDevice *device; /* future use */
 };
 
+/**
+ * ClutterStageStateEvent:
+ * @type: event type
+ * @time: event time
+ * @flags: event flags
+ * @stage: event source stage
+ * @source: event source actor (unused)
+ * @changed_mask: bitwise OR of the changed flags
+ * @new_state: bitwise OR of the current state flags
+ *
+ * Event signalling a change in the #ClutterStage state.
+ *
+ * Since: 0.2
+ */
 struct _ClutterStageStateEvent
 {
   ClutterEventType type;
@@ -322,6 +385,14 @@ struct _ClutterStageStateEvent
   ClutterStageState new_state;
 };
 
+/**
+ * ClutterEvent:
+ * @type: event type
+ *
+ * Generic event wrapper.
+ *
+ * Since: 0.2
+ */
 union _ClutterEvent
 {
   ClutterEventType type;

clutter/clutter-main.c

@@ -1997,6 +1997,9 @@ on_pointer_grab_weak_notify (gpointer data,
  * actor directly. The source set in the event will be the actor that would
  * have received the event if the pointer grab was not in effect.
  *
+ * If you wish to grab all the pointer events for a specific input device,
+ * you should use clutter_grab_pointer_for_device().
+ *
  * Since: 0.6
  */
 void
@@ -2029,6 +2032,17 @@ clutter_grab_pointer (ClutterActor *actor)
     }
 }
 
+/**
+ * clutter_grab_pointer_for_device:
+ * @actor: a #ClutterActor
+ * @id: a device id, or -1
+ *
+ * Grabs all the pointer events coming from the device @id for @actor.
+ *
+ * If @id is -1 then this function is equivalent to clutter_grab_pointer().
+ *
+ * Since: 0.8
+ */
 void
 clutter_grab_pointer_for_device (ClutterActor *actor,
                                  gint          id)
@@ -2084,6 +2098,14 @@ clutter_ungrab_pointer (void)
   clutter_grab_pointer (NULL);
 }
 
+/**
+ * clutter_ungrab_pointer_for_device:
+ * @id: a device id
+ *
+ * Removes an existing grab of the pointer events for device @id.
+ *
+ * Since: 0.8
+ */
 void
 clutter_ungrab_pointer_for_device (gint id)
 {
@@ -2308,7 +2330,17 @@ clutter_get_use_mipmapped_text (void)
   return FALSE;    
 }
 
-ClutterInputDevice*
+/**
+ * clutter_get_input_device_for_id:
+ * @id: a device id
+ *
+ * Retrieves the #ClutterInputDevice from its id.
+ *
+ * Return value: a #ClutterInputDevice, or %NULL
+ *
+ * Since: 0.8
+ */
+ClutterInputDevice *
 clutter_get_input_device_for_id (gint id)
 {
   GSList *item;
@@ -2321,7 +2353,7 @@ clutter_get_input_device_for_id (gint id)
        item != NULL; 
        item = item->next)
   {
-    device = (ClutterInputDevice *)item->data;
+    device = item->data;
 
     if (device->id == id)
       return device;

clutter/x11/clutter-backend-x11.c

@@ -756,7 +756,7 @@ _clutter_x11_select_events (Window xwin)
   }
 }
 
-ClutterX11XInputDevice*
+ClutterX11XInputDevice *
 _clutter_x11_get_device_for_xid (XID id)
 {
   GSList *list_it;
@@ -806,12 +806,32 @@ clutter_x11_get_input_devices (void)
 #endif
 }
 
+/**
+ * clutter_x11_get_input_device_type:
+ * @device: a #ClutterX11XInputDevice
+ *
+ * Retrieves the type of @device.
+ *
+ * Return value: the type of the device
+ *
+ * Since: 0.8
+ */
 ClutterX11InputDeviceType
 clutter_x11_get_input_device_type (ClutterX11XInputDevice *device)
 {
   return device->type;
 }
 
+/**
+ * clutter_x11_has_xinput:
+ * 
+ * Gets whether Clutter has XInput support.
+ *
+ * Return value: %TRUE if Clutter was compiled with XInput support
+ *   and XInput support is available at run time.
+ *
+ * Since: 0.8
+ */
 gboolean
 clutter_x11_has_xinput (void)
 {