[gtk+/xi2] Add missing docs to multidevice API.

[Carlos Garnacho <carlosg src gnome org>]

commit 7971fe880174f2c658402f7692b894a727d467e2
Author: Carlos Garnacho <carlos gnome org>
Date:   Wed Jan 20 01:17:00 2010 +0100

    Add missing docs to multidevice API.

 docs/reference/gdk/gdk-docs.sgml           |    2 +-
 docs/reference/gdk/gdk-sections.txt        |   65 ++++++-
 docs/reference/gdk/gdk.types               |    2 +
 docs/reference/gdk/tmpl/input_devices.sgml |  303 ----------------------------
 docs/reference/gtk/gtk-docs.sgml           |    1 +
 docs/reference/gtk/gtk-sections.txt        |   29 +++
 gdk/gdkdevice.c                            |   53 +++++-
 gdk/gdkdevice.h                            |   84 ++++++++
 gdk/gdkdevicemanager.c                     |   65 ++++++-
 gdk/gdkdisplay.c                           |    9 +
 gdk/gdkdisplay.h                           |   18 ++
 gdk/gdkevents.c                            |   45 ++++
 gdk/gdktypes.h                             |    8 +
 gdk/gdkwindow.c                            |    2 +-
 gdk/x11/gdkdnd-x11.c                       |   16 ++
 gdk/x11/gdkinput.c                         |   14 +-
 gtk/gtkdevicegroup.c                       |   56 +++++
 gtk/gtkmenu.c                              |    7 +-
 gtk/gtkwidget.c                            |   54 +++++
 gtk/gtkwidget.h                            |   21 ++
 20 files changed, 535 insertions(+), 319 deletions(-)
---
diff --git a/docs/reference/gdk/gdk-docs.sgml b/docs/reference/gdk/gdk-docs.sgml
index 6d48274..b959262 100644
--- a/docs/reference/gdk/gdk-docs.sgml
+++ b/docs/reference/gdk/gdk-docs.sgml
@@ -53,7 +53,7 @@
     <xi:include href="xml/threads.xml" />
 
     <xi:include href="xml/input.xml" />
-    <xi:include href="xml/input_devices.xml" />
+    <xi:include href="xml/gdkdevicemanager.xml" />
 
     <xi:include href="xml/pango_interaction.xml" />
     <xi:include href="xml/cairo_interaction.xml" />
diff --git a/docs/reference/gdk/gdk-sections.txt b/docs/reference/gdk/gdk-sections.txt
index e81c3be..68a7f7c 100644
--- a/docs/reference/gdk/gdk-sections.txt
+++ b/docs/reference/gdk/gdk-sections.txt
@@ -80,6 +80,7 @@ gdk_filter_return_get_type
 gdk_font_type_get_type
 gdk_function_get_type
 gdk_gc_values_mask_get_type
+gdk_grab_ownership_get_type
 gdk_grab_status_get_type
 gdk_gravity_get_type
 gdk_image_type_get_type
@@ -109,8 +110,7 @@ gdk_window_type_get_type
 gdk_window_type_hint_get_type
 gdk_wm_decoration_get_type
 gdk_wm_function_get_type
-gdk_pointer_grab_info_libgtk_only
-gdk_keyboard_grab_info_libgtk_only
+gdk_device_grab_info_libgtk_only
 gdk_add_option_entries_libgtk_only
 gdk_pre_parse_libgtk_only
 </SECTION>
@@ -125,9 +125,11 @@ gdk_display_get_name
 gdk_display_get_n_screens
 gdk_display_get_screen
 gdk_display_get_default_screen
+gdk_display_get_device_manager
 gdk_display_pointer_ungrab
 gdk_display_keyboard_ungrab
 gdk_display_pointer_is_grabbed
+gdk_display_device_is_grabbed
 gdk_display_beep
 gdk_display_sync
 gdk_display_flush
@@ -140,10 +142,15 @@ gdk_display_add_client_message_filter
 gdk_display_set_double_click_time
 gdk_display_set_double_click_distance
 gdk_display_get_pointer
+gdk_display_get_device_state
 gdk_display_get_window_at_pointer
+gdk_display_get_window_at_device_position
 GdkDisplayPointerHooks
 gdk_display_set_pointer_hooks
+GdkDisplayDeviceHooks
+gdk_display_set_device_hooks
 gdk_display_warp_pointer
+gdk_display_warp_device
 gdk_display_supports_cursor_color
 gdk_display_supports_cursor_alpha
 gdk_display_get_default_cursor_size
@@ -746,6 +753,7 @@ gdk_window_get_origin
 gdk_window_get_deskrelative_origin
 gdk_window_get_root_coords
 gdk_window_get_pointer
+gdk_window_get_device_position
 GdkModifierType
 gdk_window_get_parent
 gdk_window_get_toplevel
@@ -769,6 +777,14 @@ gdk_window_get_toplevels
 gdk_get_default_root_window
 
 <SUBSECTION>
+gdk_window_get_support_multidevice
+gdk_window_set_support_multidevice
+gdk_window_get_device_cursor
+gdk_window_set_device_cursor
+gdk_window_get_device_events
+gdk_window_set_device_events
+
+<SUBSECTION>
 GdkPointerHooks
 gdk_set_pointer_hooks
 
@@ -1036,20 +1052,33 @@ gdk_keymap_get_type
 </SECTION>
 
 <SECTION>
-<TITLE>Input Devices</TITLE>
-<FILE>input_devices</FILE>
+<TITLE>GdkDeviceManager</TITLE>
+<FILE>gdkdevicemanager</FILE>
+GdkDeviceManager
 GdkDevice
+GdkDeviceType
 GdkInputSource
 GdkInputMode
 GdkDeviceKey
 GdkDeviceAxis
 GdkAxisUse
-gdk_devices_list
+GdkGrabOwnership
+gdk_enable_multidevice
+gdk_device_manager_get_display
+gdk_device_manager_list_devices
+
+<SUBSECTION>
 gdk_device_set_source
 gdk_device_set_mode
 gdk_device_set_key
 gdk_device_set_axis_use
-gdk_device_get_core_pointer
+gdk_device_get_associated_device
+gdk_device_get_device_type
+gdk_device_get_display
+
+<SUBSECTION>
+gdk_device_grab
+gdk_device_ungrab
 
 <SUBSECTION>
 gdk_device_get_state
@@ -1057,16 +1086,30 @@ gdk_device_get_history
 gdk_device_free_history
 GdkTimeCoord
 gdk_device_get_axis
+gdk_device_list_axes
+gdk_device_get_axis_value
 
 <SUBSECTION>
 gdk_input_set_extension_events
 GdkExtensionMode
 
+<SUBSECTION>
+gdk_devices_list
+gdk_device_get_core_pointer
+
 <SUBSECTION Standard>
 GDK_TYPE_AXIS_USE
 GDK_TYPE_EXTENSION_MODE
 GDK_TYPE_INPUT_MODE
 GDK_TYPE_INPUT_SOURCE
+GDK_TYPE_DEVICE_TYPE
+GDK_TYPE_GRAB_OWNERSHIP
+GDK_DEVICE_MANAGER
+GDK_DEVICE_MANAGER_CLASS
+GDK_DEVICE_MANAGER_GET_CLASS
+GDK_IS_DEVICE_MANAGER
+GDK_IS_DEVICE_MANAGER_CLASS
+GDK_TYPE_DEVICE_MANAGER
 GDK_DEVICE
 GDK_DEVICE_CLASS
 GDK_DEVICE_GET_CLASS
@@ -1076,7 +1119,10 @@ GDK_TYPE_DEVICE
 
 <SUBSECTION Private>
 GdkDeviceClass
+GdkDeviceManagerClass
 gdk_device_get_type
+gdk_device_manager_get_type
+gdk_device_type_get_type
 GDK_MAX_TIMECOORD_AXES
 </SECTION>
 
@@ -1105,6 +1151,9 @@ gdk_event_get_axis
 gdk_event_get_coords
 gdk_event_get_root_coords
 gdk_event_request_motions
+gdk_events_get_angle
+gdk_events_get_center
+gdk_events_get_distance
 
 <SUBSECTION>
 gdk_event_handler_set
@@ -1121,6 +1170,8 @@ gdk_get_show_events
 gdk_set_show_events
 gdk_event_set_screen
 gdk_event_get_screen
+gdk_event_get_device
+gdk_event_set_device
 
 <SUBSECTION>
 gdk_setting_get
@@ -1244,6 +1295,8 @@ GdkDragContext
 GdkDragAction
 gdk_drag_status
 gdk_drag_drop_succeeded
+gdk_drag_context_get_device
+gdk_drag_context_set_device
 
 <SUBSECTION Standard>
 GDK_DRAG_CONTEXT
diff --git a/docs/reference/gdk/gdk.types b/docs/reference/gdk/gdk.types
index 12b0f8d..8b200f5 100644
--- a/docs/reference/gdk/gdk.types
+++ b/docs/reference/gdk/gdk.types
@@ -9,3 +9,5 @@ gdk_pango_renderer_get_type
 gdk_pixmap_get_type
 gdk_gc_get_type
 gdk_keymap_get_type
+gdk_device_get_type
+gdk_device_manager_get_type
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 265aef4..d33b065 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -336,6 +336,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
       <xi:include href="xml/gtktooltip.xml" />
       <xi:include href="xml/gtkviewport.xml" />
       <xi:include href="xml/gtkaccessible.xml" />
+      <xi:include href="xml/gtkdevicegroup.xml" />
     </chapter>
 
     <chapter id="AbstractObjects">
diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt
index 58c61fa..65b9375 100644
--- a/docs/reference/gtk/gtk-sections.txt
+++ b/docs/reference/gtk/gtk-sections.txt
@@ -947,6 +947,7 @@ gtk_combo_box_insert_text
 gtk_combo_box_prepend_text
 gtk_combo_box_remove_text
 gtk_combo_box_get_active_text
+gtk_combo_box_popup_for_device
 gtk_combo_box_popup
 gtk_combo_box_popdown
 gtk_combo_box_get_popup_accessible
@@ -2450,6 +2451,7 @@ gtk_menu_prepend
 gtk_menu_insert
 gtk_menu_reorder_child
 gtk_menu_attach
+gtk_menu_popup_for_device
 gtk_menu_popup
 gtk_menu_set_accel_group
 gtk_menu_get_accel_group
@@ -5562,6 +5564,8 @@ GtkSelectionData
 GtkWidgetAuxInfo
 GtkWidgetShapeInfo
 GtkWidgetHelpType
+GtkMultiDeviceEvent
+GtkMultiDeviceEventType
 gtk_widget_new
 gtk_widget_ref
 gtk_widget_unref
@@ -5738,6 +5742,10 @@ gtk_widget_is_toplevel
 gtk_widget_set_window
 gtk_widget_set_receives_default
 gtk_widget_get_receives_default
+gtk_widget_set_support_multidevice
+gtk_widget_create_device_group
+gtk_widget_remove_device_group
+gtk_widget_get_group_for_device
 
 <SUBSECTION>
 gtk_requisition_copy
@@ -5757,6 +5765,26 @@ gtk_requisition_get_type
 </SECTION>
 
 <SECTION>
+<FILE>gtkdevicegroup</FILE>
+<TITLE>GtkDeviceGroup</TITLE>
+GtkDeviceGroup
+gtk_device_group_add_device
+gtk_device_group_remove_device
+gtk_device_group_get_devices
+
+<SUBSECTION Standard>
+GTK_DEVICE_GROUP
+GTK_DEVICE_GROUP_CLASS
+GTK_DEVICE_GROUP_GET_CLASS
+GTK_IS_DEVICE_GROUP
+GTK_IS_DEVICE_GROUP_CLASS
+GTK_TYPE_DEVICE_GROUP
+
+<SUBSECTION Private>
+gtk_device_group_get_type
+</SECTION>
+
+<SECTION>
 <FILE>gtkwindow</FILE>
 <TITLE>GtkWindow</TITLE>
 GtkWindow
@@ -5970,6 +5998,7 @@ gtk_key_snooper_remove
 gtk_get_current_event
 gtk_get_current_event_time
 gtk_get_current_event_state
+gtk_get_current_event_device
 gtk_get_event_widget
 gtk_propagate_event
 
diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index 0e635a3..7530826 100644
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -300,7 +300,7 @@ gdk_device_get_property (GObject    *object,
  * or %NULL.
  * @mask: location to store the modifiers, or %NULL.
  *
- * Gets the current state of a device.
+ * Gets the current state of a device relative to @window.
  */
 void
 gdk_device_get_state (GdkDevice       *device,
@@ -385,6 +385,13 @@ gdk_device_free_history (GdkTimeCoord **events,
   g_free (events);
 }
 
+/**
+ * gdk_device_set_source:
+ * @device: a #GdkDevice.
+ * @source: the source type.
+ *
+ * Sets the source type for an input device.
+ **/
 void
 gdk_device_set_source (GdkDevice      *device,
 		       GdkInputSource  source)
@@ -394,6 +401,17 @@ gdk_device_set_source (GdkDevice      *device,
   device->source = source;
 }
 
+/**
+ * gdk_device_set_mode:
+ * @device: a #GdkDevice.
+ * @mode: the input mode.
+ *
+ * Sets a the mode of an input device. The mode controls if the
+ * device is active and whether the device's range is mapped to the
+ * entire screen or to a single window.
+ *
+ * Returns: %TRUE if the mode was successfully changed.
+ **/
 gboolean
 gdk_device_set_mode (GdkDevice    *device,
                      GdkInputMode  mode)
@@ -418,6 +436,16 @@ gdk_device_set_mode (GdkDevice    *device,
   return TRUE;
 }
 
+/**
+ * gdk_device_set_key:
+ * @device: a #GdkDevice.
+ * @index: the index of the macro button to set.
+ * @keyval: the keyval to generate.
+ * @modifiers: the modifiers to set.
+ *
+ * Specifies the X key event to generate when a macro button of a device
+ * is pressed.
+ **/
 void
 gdk_device_set_key (GdkDevice      *device,
 		    guint           index,
@@ -431,6 +459,14 @@ gdk_device_set_key (GdkDevice      *device,
   device->keys[index].modifiers = modifiers;
 }
 
+/**
+ * gdk_device_set_axis_use:
+ * @device: a #GdkDevice.
+ * @index: the index of the axis.
+ * @use: specifies how the axis is used.
+ *
+ * Specifies how an axis of a device is used.
+ **/
 void
 gdk_device_set_axis_use (GdkDevice   *device,
 			 guint        index,
@@ -589,6 +625,19 @@ gdk_device_list_axes (GdkDevice *device)
   return g_list_reverse (axes);
 }
 
+/**
+ * gdk_device_get_axis_value:
+ * @device: a #GdkDevice.
+ * @axes: pointer to an array of axes
+ * @axis_label: #GdkAtom with the axis label.
+ * @value: location to store the found value.
+ *
+ * Interprets an array of double as axis values for a given device,
+ * and locates the value in the array for a given axis label, as returned
+ * by gdk_device_list_axes()
+ *
+ * Returns: %TRUE if the given axis use was found, otherwise %FALSE.
+ **/
 gboolean
 gdk_device_get_axis_value (GdkDevice *device,
                            gdouble   *axes,
@@ -692,7 +741,7 @@ get_native_grab_event_mask (GdkEventMask grab_mask)
  * gdk_device_grab:
  * @device: a #GdkDevice
  * @window: the #GdkWindow which will own the grab (the grab window)
- * @grab_ownership: 
+ * @grab_ownership: specifies the grab ownership.
  * @owner_events: if %FALSE then all device events are reported with respect to
  *                @window and are only reported if selected by @event_mask. If
  *                %TRUE then pointer events for this application are reported
diff --git a/gdk/gdkdevice.h b/gdk/gdkdevice.h
index 3107315..3e7c44f 100644
--- a/gdk/gdkdevice.h
+++ b/gdk/gdkdevice.h
@@ -38,6 +38,16 @@ typedef struct _GdkDeviceKey GdkDeviceKey;
 typedef struct _GdkDeviceAxis GdkDeviceAxis;
 typedef struct _GdkTimeCoord GdkTimeCoord;
 
+/**
+ * GdkExtensionMode:
+ * @GDK_EXTENSION_EVENTS_NONE: no extension events are desired.
+ * @GDK_EXTENSION_EVENTS_ALL: all extension events are desired.
+ * @GDK_EXTENSION_EVENTS_CURSOR: extension events are desired only if a cursor
+ *                               will be displayed for the device.
+ *
+ * An enumeration used to specify which extension events
+ * are desired for a particular widget.
+ */
 typedef enum
 {
   GDK_EXTENSION_EVENTS_NONE,
@@ -45,6 +55,18 @@ typedef enum
   GDK_EXTENSION_EVENTS_CURSOR
 } GdkExtensionMode;
 
+/**
+ * GdkInputSource:
+ * @GDK_SOURCE_MOUSE: the device is a mouse. (This will be reported for the core
+ *                    pointer, even if it is something else, such as a trackball.)
+ * @GDK_SOURCE_PEN: the device is a stylus of a graphics tablet or similar device.
+ * @GDK_SOURCE_ERASER: the device is an eraser. Typically, this would be the other end
+ *                     of a stylus on a graphics tablet.
+ * @GDK_SOURCE_CURSOR: the device is a graphics tablet "puck" or similar device.
+ * @GDK_SOURCE_KEYBOARD: the device is a keyboard.
+ *
+ * An enumeration describing the type of an input device in general terms.
+ */
 typedef enum
 {
   GDK_SOURCE_MOUSE,
@@ -54,6 +76,18 @@ typedef enum
   GDK_SOURCE_KEYBOARD
 } GdkInputSource;
 
+/**
+ * GdkInputMode:
+ * @GDK_MODE_DISABLED: the device is disabled and will not report any events.
+ * @GDK_MODE_SCREEN: the device is enabled. The device's coordinate space
+ *                   maps to the entire screen.
+ * @GDK_MODE_WINDOW: the device is enabled. The device's coordinate space
+ *                   is mapped to a single window. The manner in which this window
+ *                   is chosen is undefined, but it will typically be the same
+ *                   way in which the focus window for key events is determined.
+ *
+ * An enumeration that describes the mode of an input device.
+ */
 typedef enum
 {
   GDK_MODE_DISABLED,
@@ -61,6 +95,21 @@ typedef enum
   GDK_MODE_WINDOW
 } GdkInputMode;
 
+/**
+ * GdkAxisUse:
+ * @GDK_AXIS_IGNORE: the axis is ignored.
+ * @GDK_AXIS_X: the axis is used as the x axis.
+ * @GDK_AXIS_Y: the axis is used as the y axis.
+ * @GDK_AXIS_PRESSURE: the axis is used for pressure information.
+ * @GDK_AXIS_XTILT: the axis is used for x tilt information.
+ * @GDK_AXIS_YTILT: the axis is used for x tilt information.
+ * @GDK_AXIS_WHEEL: the axis is used for wheel information.
+ * @GDK_AXIS_LAST: a constant equal to the numerically highest axis value.
+ *
+ * An enumeration describing the way in which a device
+ * axis (valuator) maps onto the predefined valuator
+ * types that GTK+ understands.
+ */
 typedef enum
 {
   GDK_AXIS_IGNORE,
@@ -73,18 +122,46 @@ typedef enum
   GDK_AXIS_LAST
 } GdkAxisUse;
 
+/**
+ * GdkDeviceType:
+ * @GDK_DEVICE_TYPE_MASTER: Device is a master (or virtual) device. There will
+ *                          be an associated focus indicator on the screen.
+ * @GDK_DEVICE_TYPE_SLAVE: Device is a slave (or physical) device.
+ * @GDK_DEVICE_TYPE_FLOATING: Device is a physical device, currently not attached to
+ *                            any virtual device.
+ *
+ * Indicates the device type.
+ */
 typedef enum {
   GDK_DEVICE_TYPE_MASTER,
   GDK_DEVICE_TYPE_SLAVE,
   GDK_DEVICE_TYPE_FLOATING
 } GdkDeviceType;
 
+/**
+ * GdkDeviceKey:
+ * @keyval: the keyval to generate when the macro button is pressed.
+ *          If this is 0, no keypress will be generated.
+ * @modifiers: the modifiers set for the generated key event.
+ *
+ * The <structname>GdkDeviceKey</structname> structure contains information
+ * about the mapping of one device macro button onto a normal X key event.
+ */
 struct _GdkDeviceKey
 {
   guint keyval;
   GdkModifierType modifiers;
 };
 
+/**
+ * GdkDeviceAxis:
+ * @use: specifies how the axis is used.
+ * @min: the minimal value that will be reported by this axis.
+ * @max: the maximal value that will be reported by this axis.
+ *
+ * The <structname>GdkDeviceAxis</structname> structure contains information
+ * about the range and mapping of a device axis.
+ */
 struct _GdkDeviceAxis
 {
   GdkAxisUse use;
@@ -97,6 +174,13 @@ struct _GdkDeviceAxis
  */
 #define GDK_MAX_TIMECOORD_AXES 128
 
+/**
+ * GdkTimeCoord:
+ * @time: The timestamp for this event.
+ * @axes: the values of the device's axes.
+ *
+ * The #GdkTimeCoord structure stores a single event in a motion history.
+ */
 struct _GdkTimeCoord
 {
   guint32 time;
diff --git a/gdk/gdkdevicemanager.c b/gdk/gdkdevicemanager.c
index 8ecc3c0..aa6fa26 100644
--- a/gdk/gdkdevicemanager.c
+++ b/gdk/gdkdevicemanager.c
@@ -23,6 +23,69 @@
 #include "gdkinternals.h"
 #include "gdkalias.h"
 
+/**
+ * SECTION:gdkdevicemanager
+ * @Short_description: Functions for handling input devices
+ * @Long_description: In addition to a single pointer and keyboard for user interface input, GDK
+ *                    contains support for a variety of input devices, including graphics tablets,
+ *                    touchscreens and multiple pointers/keyboards interacting simultaneously with
+ *                    the user interface. Under X, the support for multiple input devices is done
+ *                    through the <firstterm>XInput 2</firstterm> extension, which also supports
+ *                    additional features such as sub-pixel positioning information and additional
+ *                    device-dependent information.
+ * @Title: GdkDeviceManager
+ * @See_also: #GdkDevice, #GdkEvent, gdk_enable_multidevice()
+ *
+ * By default, GDK supports the traditional single keyboard/pointer input scheme (Plus additional
+ * special input devices such as tablets. In short, backwards compatible with 2.X). Since version X.YZ,
+ * if gdk_enable_multidevice() is called before gdk_display_open() and the platform supports it, GDK
+ * will be aware of multiple keyboard/pointer pairs interacting simultaneously with the user interface.
+ *
+ * Conceptually, in multidevice mode there are 2 device types, virtual devices (or master devices)
+ * are represented by the pointer cursors and keyboard foci that are seen on the screen. physical
+ * devices (or slave devices) represent the hardware that is controlling the virtual devices, and
+ * thus has no visible cursor on the screen.
+ *
+ * Virtual devices are always paired, there is a keyboard device for every pointer device,
+ * associations between devices may be inspected through gdk_device_get_associated_device().
+ *
+ * There may be several virtual devices, and several physical devices could be controlling each of
+ * these virtual devices. Physical devices may also be "floating", which means they are not attached
+ * to any virtual device.
+ *
+ * By default, GDK will automatically listen for events coming from all master devices, setting the
+ * #GdkDevice for all events coming from input devices
+ * <footnote>
+ *   Events containing device information are #GDK_MOTION_NOTIFY, #GDK_BUTTON_PRESS, #GDK_2BUTTON_PRESS,
+ *   #GDK_3BUTTON_PRESS, #GDK_BUTTON_RELEASE, #GDK_SCROLL, #GDK_KEY_PRESS, #GDK_KEY_RELEASE,
+ *   #GDK_ENTER_NOTIFY, #GDK_LEAVE_NOTIFY, #GDK_FOCUS_CHANGE, #GDK_PROXIMITY_IN, #GDK_PROXIMITY_OUT,
+ *   #GDK_DRAG_ENTER, #GDK_DRAG_LEAVE, #GDK_DRAG_MOTION, #GDK_DRAG_STATUS, #GDK_DROP_START,
+ *   #GDK_DROP_FINISHED and #GDK_GRAB_BROKEN.
+ * </footnote>
+ * , although gdk_window_set_support_multidevice() has to be called on #GdkWindow<!-- --> in order to
+ * support additional features of multiple pointer interaction, such as multiple, per-device enter/leave
+ * events. The default setting will emit just one enter/leave event pair for all devices on the window.
+ * See gdk_window_set_support_multidevice() documentation for more information.
+ *
+ * In order to listen for events coming from other than a virtual device, gdk_window_set_device_events()
+ * must be called. Generally, this function can be used to modify the event mask for any given device.
+ *
+ * Input devices may also provide additional information besides X/Y. For example, graphics tablets may
+ * also provide pressure and X/Y tilt information. This information is device-dependent, and may be
+ * queried through gdk_device_get_axis(). In multidevice mode, virtual devices will change axes in order
+ * to always represent the physical device that is routing events through it. Whenever the physical device
+ * changes, the #GdkDevice:n-axes property will be notified, and gdk_device_list_axes() will return the
+ * new device axes.
+ *
+ * Devices may also have associated <firstterm>keys</firstterm> or macro buttons. Such keys can be
+ * globally set to map into normal X keyboard events. The mapping is set using gdk_device_set_key().
+ *
+ * In order to query the device hierarchy and be aware of changes in the device hierarchy (such as
+ * virtual devices being created or removed, or physical devices being plugged or unplugged), GDK
+ * provides #GdkDeviceManager. On X11, multidevice support is implemented through XInput 2. If
+ * gdk_enable_multidevice() is called, the XInput 2.x #GdkDeviceManager implementation will be used
+ * as input source, else either the core or XInput 1.x implementations will be used.
+ */
 
 static void gdk_device_manager_set_property (GObject      *object,
                                              guint         prop_id,
@@ -100,7 +163,7 @@ gdk_device_manager_class_init (GdkDeviceManagerClass *klass)
    * @device_manager: the object on which the signal is emitted
    * @device: the just removed #GdkDevice.
    *
-   * The ::device-added signal is emitted either when a master
+   * The ::device-removed signal is emitted either when a master
    * pointer is removed, or when a slave (Hardware) input device
    * is unplugged.
    */
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index c9dc514..44e11a2 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -1716,6 +1716,15 @@ gdk_display_pointer_is_grabbed (GdkDisplay *display)
   return FALSE;
 }
 
+/**
+ * gdk_display_device_is_grabbed:
+ * @display: a #GdkDisplay
+ * @device: a #GdkDevice
+ *
+ * Returns %TRUE if there is an ongoing grab on @device for @display.
+ *
+ * Returns: %TRUE if there is a grab in effect for @device.
+ **/
 gboolean
 gdk_display_device_is_grabbed (GdkDisplay *display,
                                GdkDevice  *device)
diff --git a/gdk/gdkdisplay.h b/gdk/gdkdisplay.h
index 7b06f66..f57fa49 100644
--- a/gdk/gdkdisplay.h
+++ b/gdk/gdkdisplay.h
@@ -150,6 +150,24 @@ struct _GdkDisplayPointerHooks
 				    gint            *win_y);
 };
 
+/**
+ * GdkDisplayDeviceHooks:
+ * @get_device_state: Obtains the current position and modifier state for
+ * @device. The position is given in coordinates relative to the window
+ * containing the pointer, which is returned in @window.
+ * @window_get_device_position: Obtains the window underneath the device
+ * position. Current device position and modifier state are returned in
+ * @x, @y and @mask. The position is given in coordinates relative to
+ * @window.
+ * @window_at_device_position: Obtains the window underneath the device
+ * position, returning the location of that window in @win_x, @win_y.
+ * Returns %NULL if the window under the mouse pointer is not known to
+ * GDK (for example, belongs to another application).
+ *
+ * A table of pointers to functions for getting quantities related to
+ * the current device position. Each #GdkDisplay has a table of this type,
+ * which can be set using gdk_display_set_device_hooks().
+ */
 struct _GdkDisplayDeviceHooks
 {
   void (* get_device_state)                  (GdkDisplay       *display,
diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c
index 1541fa3..fbadb3d 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -920,6 +920,15 @@ gdk_event_get_axis (const GdkEvent *event,
   return gdk_device_get_axis (device, axes, axis_use, value);
 }
 
+/**
+ * gdk_event_set_device:
+ * @event: a #GdkEvent
+ * @device: a #GdkDevice
+ *
+ * Sets the device for @event to @device. The event must
+ * have been allocated by GTK+, for instance, by
+ * gdk_event_copy().
+ **/
 void
 gdk_event_set_device (GdkEvent  *event,
                       GdkDevice *device)
@@ -1042,6 +1051,17 @@ gdk_events_get_axis_distances (GdkEvent *event1,
   return TRUE;
 }
 
+/**
+ * gdk_events_get_distance:
+ * @event1: first #GdkEvent
+ * @event2: second #GdkEvent
+ * @distance: return location for the distance
+ *
+ * If both events have X/Y information, the distance between both coordinates
+ * (as in a straight line going from @event1 to @event2) will be returned.
+ *
+ * Returns: %TRUE if the distance could be calculated.
+ **/
 gboolean
 gdk_events_get_distance (GdkEvent *event1,
                          GdkEvent *event2,
@@ -1052,6 +1072,19 @@ gdk_events_get_distance (GdkEvent *event1,
                                         distance);
 }
 
+/**
+ * gdk_events_get_angle:
+ * @event1: first #GdkEvent
+ * @event2: second #GdkEvent
+ * @angle: return location for the relative angle between both events
+ *
+ * If both events contain X/Y information, this function will return %TRUE
+ * and return in @angle the relative angle from @event1 to @event2. The rotation
+ * direction for positive angles is from the positive X axis towards the positive
+ * Y axis.
+ *
+ * Returns: %TRUE if the angle could be calculated.
+ **/
 gboolean
 gdk_events_get_angle (GdkEvent *event1,
                       GdkEvent *event2,
@@ -1081,6 +1114,18 @@ gdk_events_get_angle (GdkEvent *event1,
   return TRUE;
 }
 
+/**
+ * gdk_events_get_center:
+ * @event1: first #GdkEvent
+ * @event2: second #GdkEvent
+ * @x: return location for the X coordinate of the center
+ * @y: return location for the Y coordinate of the center
+ *
+ * If both events contain X/Y information, the center of both coordinates
+ * will be returned in @x and @y.
+ *
+ * Returns: %TRUE if the center could be calculated.
+ **/
 gboolean
 gdk_events_get_center (GdkEvent *event1,
                        GdkEvent *event2,
diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h
index 4082a47..e619d13 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -181,6 +181,14 @@ typedef enum
   GDK_GRAB_FROZEN          = 4
 } GdkGrabStatus;
 
+/**
+ * GdkGrabOwnership:
+ * @GDK_OWNERSHIP_NONE: All other devices' events are allowed.
+ * @GDK_OWNERSHIP_WINDOW: Other devices' events are blocked for the grab window.
+ * @GDK_OWNERSHIP_APPLICATION: Other devices' events are blocked for the whole application.
+ *
+ * Defines how device grabs interact with other devices.
+ */
 typedef enum
 {
   GDK_OWNERSHIP_NONE,
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index fca0caa..9cbc90d 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -9508,7 +9508,7 @@ gdk_window_beep (GdkWindow *window)
  * This function will enable multidevice features in @window.
  *
  * Multidevice aware windows will need to handle properly multiple,
- * per device enter/leave events and grab ownerships.
+ * per device enter/leave events, device grabs and grab ownerships.
  **/
 void
 gdk_window_set_support_multidevice (GdkWindow *window,
diff --git a/gdk/x11/gdkdnd-x11.c b/gdk/x11/gdkdnd-x11.c
index 96dccb8..97168d4 100644
--- a/gdk/x11/gdkdnd-x11.c
+++ b/gdk/x11/gdkdnd-x11.c
@@ -246,6 +246,14 @@ gdk_drag_context_unref (GdkDragContext *context)
   g_object_unref (context);
 }
 
+/**
+ * gdk_drag_context_set_device:
+ * @context: a #GdkDragContext
+ * @device: a #GdkDevice
+ *
+ * Associates a #GdkDevice to @context, so all Drag and Drop events
+ * for @context are emitted as if they came from this device.
+ **/
 void
 gdk_drag_context_set_device (GdkDragContext *context,
                              GdkDevice      *device)
@@ -267,6 +275,14 @@ gdk_drag_context_set_device (GdkDragContext *context,
     private->device = g_object_ref (device);
 }
 
+/**
+ * gdk_drag_context_get_device:
+ * @context: a #GdkDragContext
+ *
+ * Returns the #GdkDevice associated to the drag context.
+ *
+ * Returns: The #GdkDevice associated to @context.
+ **/
 GdkDevice *
 gdk_drag_context_get_device (GdkDragContext *context)
 {
diff --git a/gdk/x11/gdkinput.c b/gdk/x11/gdkinput.c
index 8348ffa..199a259 100644
--- a/gdk/x11/gdkinput.c
+++ b/gdk/x11/gdkinput.c
@@ -132,9 +132,19 @@ unset_extension_events (GdkWindow *window)
   window_private->extension_events = 0;
 }
 
+/**
+ * gdk_input_set_extension_events:
+ * @window: a #GdkWindow.
+ * @mask: the event mask
+ * @mode: the type of extension events that are desired.
+ *
+ * Turns extension events on or off for a particular window,
+ * and specifies the event mask for extension events.
+ **/
 void
-gdk_input_set_extension_events (GdkWindow *window, gint mask,
-				GdkExtensionMode mode)
+gdk_input_set_extension_events (GdkWindow        *window,
+                                gint              mask,
+				GdkExtensionMode  mode)
 {
   GdkWindowObject *window_private;
   GdkWindowObject *impl_window;
diff --git a/gtk/gtkdevicegroup.c b/gtk/gtkdevicegroup.c
index 0f4b531..fe5c431 100644
--- a/gtk/gtkdevicegroup.c
+++ b/gtk/gtkdevicegroup.c
@@ -21,6 +21,20 @@
 #include "gtkintl.h"
 #include "gtkdevicegroup.h"
 
+/**
+ * SECTION:gtkdevicegroup
+ * @Short_description: Group of input devices for multidevice events.
+ * @Title: Device groups
+ * @See_also: #GtkMultiDeviceEvent
+ *
+ * #GtkDeviceGroup defines a group of devices, they are created through
+ * gtk_widget_create_device_group() and destroyed through
+ * gtk_widget_remove_device_group(). Device groups are used by its
+ * corresponding #GtkWidget in order to issue #GtkMultiDeviceEvent<!-- -->s
+ * whenever any of the contained devices emits a #GDK_MOTION_NOTIFY
+ * event, or any device enters or leaves the group.
+ */
+
 typedef struct GtkDeviceGroupPrivate GtkDeviceGroupPrivate;
 
 struct GtkDeviceGroupPrivate
@@ -53,6 +67,14 @@ gtk_device_group_class_init (GtkDeviceGroupClass *klass)
 
   object_class->finalize = gtk_device_group_finalize;
 
+  /**
+   * GtkDeviceGroup::device-added:
+   * @device_group: the object that received the signal
+   * @device: the device that was just added
+   *
+   * This signal is emitted right after a #GdkDevice is added
+   * to @device_group.
+   */
   signals[DEVICE_ADDED] =
     g_signal_new (I_("device-added"),
                   G_TYPE_FROM_CLASS (object_class),
@@ -61,6 +83,14 @@ gtk_device_group_class_init (GtkDeviceGroupClass *klass)
                   NULL, NULL,
                   g_cclosure_marshal_VOID__OBJECT,
                   G_TYPE_NONE, 1, GDK_TYPE_DEVICE);
+  /**
+   * GtkDeviceGroup::device-removed:
+   * @device_group: the object that received the signal
+   * @device: the device that was just removed
+   *
+   * This signal is emitted right after a #GdkDevice is removed
+   * from @device_group.
+   */
   signals[DEVICE_REMOVED] =
     g_signal_new (I_("device-removed"),
                   G_TYPE_FROM_CLASS (object_class),
@@ -91,6 +121,15 @@ gtk_device_group_finalize (GObject *object)
   G_OBJECT_CLASS (gtk_device_group_parent_class)->finalize (object);
 }
 
+/**
+ * gtk_device_group_add_device:
+ * @group: a #GtkDeviceGroup
+ * @device: a #GdkDevice
+ *
+ * Adds @device to @group, so events coming from this device will
+ * trigger #GtkWidget::multidevice-event<!-- -->s for @group. Adding
+ * devices with source %GDK_SOURCE_KEYBOARD is not allowed.
+ **/
 void
 gtk_device_group_add_device (GtkDeviceGroup *group,
                              GdkDevice      *device)
@@ -99,6 +138,7 @@ gtk_device_group_add_device (GtkDeviceGroup *group,
 
   g_return_if_fail (GTK_IS_DEVICE_GROUP (group));
   g_return_if_fail (GDK_IS_DEVICE (device));
+  g_return_if_fail (device->source != GDK_SOURCE_KEYBOARD);
 
   priv = GTK_DEVICE_GROUP_GET_PRIVATE (group);
 
@@ -111,6 +151,13 @@ gtk_device_group_add_device (GtkDeviceGroup *group,
   g_signal_emit (group, signals[DEVICE_ADDED], 0, device);
 }
 
+/**
+ * gtk_device_group_remove_device:
+ * @group: a #GtkDeviceGroup
+ * @device: a #GdkDevice
+ *
+ * Removes @device from @group, if it was there.
+ **/
 void
 gtk_device_group_remove_device (GtkDeviceGroup *group,
                                 GdkDevice      *device)
@@ -136,6 +183,15 @@ gtk_device_group_remove_device (GtkDeviceGroup *group,
   g_list_free_1 (dev);
 }
 
+/**
+ * gtk_device_group_get_devices:
+ * @group: a #GtkDeviceGroup
+ *
+ * Returns a #GList of #GdkDevices with the devices contained in @group.
+ *
+ * Returns: a list of #GdkDevices. This list and its elements are owned
+ *          by group, and must not be freed or unref'ed.
+ **/
 GList *
 gtk_device_group_get_devices (GtkDeviceGroup *group)
 {
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index 05a06aa..0e234c6 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -1406,8 +1406,9 @@ popup_grab_on_window (GdkWindow *window,
 }
 
 /**
- * gtk_menu_popup:
+ * gtk_menu_popup_for_device:
  * @menu: a #GtkMenu.
+ * @device: a #GdkDevice
  * @parent_menu_shell: the menu shell containing the triggering menu item, or %NULL
  * @parent_menu_item: the menu item whose activation triggered the popup, or %NULL
  * @func: a user supplied function used to position the menu, or %NULL
@@ -1417,9 +1418,9 @@ popup_grab_on_window (GdkWindow *window,
  *
  * Displays a menu and makes it available for selection.  Applications can use
  * this function to display context-sensitive menus, and will typically supply
- * %NULL for the @parent_menu_shell, @parent_menu_item, @func and @data 
+ * %NULL for the @parent_menu_shell, @parent_menu_item, @func and @data
  * parameters. The default menu positioning function will position the menu
- * at the current mouse cursor position.
+ * at the current position of @device (or its corresponding pointer).
  *
  * The @button parameter should be the mouse button pressed to initiate
  * the menu popup. If the menu popup was initiated by something other than
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 81eee30..5dfcf49 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -2387,6 +2387,18 @@ gtk_widget_class_init (GtkWidgetClass *klass)
 		  _gtk_marshal_BOOLEAN__UINT,
                   G_TYPE_BOOLEAN, 1, G_TYPE_UINT);
 
+  /**
+   * GtkWidget::multidevice-event:
+   * @widget: the object which received the signal
+   * @device_group: the #GtkDeviceGroup that was updated by a
+   *                device event
+   * @event: a #GtkMultiDeviceEvent containing event information
+   *         for all devices in @device_group.
+   *
+   * This signal is emitted right after an input device that is
+   * contained in @device_group emits one event, or whenever a
+   * #GdkDevice is added or removed from @device_group.
+   */
   widget_signals[MULTIDEVICE_EVENT] =
     g_signal_new (I_("multidevice-event"),
                   G_TYPE_FROM_CLASS (gobject_class),
@@ -11323,6 +11335,16 @@ gtk_widget_get_window (GtkWidget *widget)
   return widget->window;
 }
 
+/**
+ * gtk_widget_set_support_multidevice:
+ * @widget: a #GtkWidget
+ * @support_multidevice: %TRUE to support input from multiple devices.
+ *
+ * Enables or disables multiple pointer awareness. If this setting is %TRUE,
+ * @widget will start receiving multiple, per device enter/leave events. Note
+ * that if custom #GdkWindow<!-- -->s are created in #GtkWidget::realize,
+ * gdk_window_set_support_multidevice() will have to be called manually on them.
+ **/
 void
 gtk_widget_set_support_multidevice (GtkWidget *widget,
                                     gboolean   support_multidevice)
@@ -11472,6 +11494,20 @@ free_multidevice_data (GtkMultiDeviceData *data)
   g_slice_free (GtkMultiDeviceData, data);
 }
 
+/**
+ * gtk_widget_create_device_group:
+ * @widget: a #GtkWidget
+ *
+ * Creates a new #GtkDeviceGroup for @widget. devices can be added
+ * later through gtk_device_group_add_device(). Note that
+ * #GdkDevice<!-- -->s can only pertain to one #GtkDeviceGroup for a
+ * given #GtkWidget, so adding it to a new group will remove it from
+ * its previous one.
+ *
+ * Returns: a newly created #GtkDeviceGroup. This object is owned by
+ *          @widget and must be destroyed through
+ *          gtk_widget_remove_device_group().
+ **/
 GtkDeviceGroup *
 gtk_widget_create_device_group (GtkWidget *widget)
 {
@@ -11508,6 +11544,14 @@ gtk_widget_create_device_group (GtkWidget *widget)
   return group;
 }
 
+/**
+ * gtk_widget_remove_device_group:
+ * @widget: a #GtkWidget
+ * @group: a #GtkDeviceGroup
+ *
+ * If @group pertains to @widget, @group will be destroyed so no further
+ * #GtkWidget::multidevice-event<!-- -->s are emitted for it.
+ **/
 void
 gtk_widget_remove_device_group (GtkWidget      *widget,
                                 GtkDeviceGroup *group)
@@ -11543,6 +11587,16 @@ gtk_widget_remove_device_group (GtkWidget      *widget,
   g_list_free_1 (g);
 }
 
+/**
+ * gtk_widget_get_group_for_device:
+ * @widget: a #GtkWidget
+ * @device: a #GdkDevice
+ *
+ * Returns the #GtkDeviceGroup containing the #GdkDevice, or %NULL if
+ * there is none.
+ *
+ * Returns: a #GtkDeviceGroup, or %NULL.
+ **/
 GtkDeviceGroup *
 gtk_widget_get_group_for_device (GtkWidget *widget,
                                  GdkDevice *device)
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index 7464198..74c5b49 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -755,6 +755,16 @@ struct _GtkWidgetClass
   void (*_gtk_reserved7) (void);
 };
 
+/**
+ * GtkMultiDeviceEventType:
+ * @GTK_EVENT_DEVICE_ADDED: A device was added to the device group.
+ * @GTK_EVENT_DEVICE_REMOVED: A device was removed from the device group.
+ * @GTK_EVENT_DEVICE_UPDATED: A device in the device group has updated its
+ *                            state.
+ *
+ * Provides a hint about the change that initiated the
+ * #GtkWidget::multidevice-event.
+ */
 typedef enum
 {
   GTK_EVENT_DEVICE_ADDED,
@@ -762,6 +772,17 @@ typedef enum
   GTK_EVENT_DEVICE_UPDATED
 } GtkMultiDeviceEventType;
 
+/**
+ * GtkMultiDeviceEvent:
+ * @type: the event type.
+ * @n_events: number of device events contained in this #GtkMultiDeviceEvent
+ * @events: an array of #GdkEventMotion structs.
+ * @updated_event: latest updated event, or %NULL if @type is %GDK_EVENT_DEVICE_REMOVED.
+ * @updated_device: device that triggered the event.
+ *
+ * The #GtkMultiDeviceEvent struct contains information about latest state of
+ * multiple device pointers. These devices are contained in a #GtkDeviceGroup.
+ */
 struct _GtkMultiDeviceEvent
 {
   GtkMultiDeviceEventType type;