[gtk+/xi2] xi2: Add Since/Deprecated to all relevant functions.

[Carlos Garnacho <carlosg src gnome org>]

commit 657c4bce7e26883bc60eacbd0764b60294d5b2f7
Author: Carlos Garnacho <carlosg gnome org>
Date:   Fri May 21 12:28:05 2010 +0200

    xi2: Add Since/Deprecated to all relevant functions.

 gdk/gdk.c                |    2 +
 gdk/gdkdevice.c          |   32 +++++++++++++
 gdk/gdkdevicemanager.c   |    6 ++-
 gdk/gdkdisplay.c         |   44 +++++++++++++++++-
 gdk/gdkevents.c          |   10 ++++
 gdk/gdkwindow.c          |  113 +++++++++++++++++++++++++++++++++++++---------
 gdk/x11/gdkdisplay-x11.c |    2 +
 gdk/x11/gdkinput.c       |    4 ++
 gdk/x11/gdkwindow-x11.c  |    4 ++
 gtk/gtkcombobox.c        |    2 +
 gtk/gtkdevicegroup.c     |    6 +++
 gtk/gtkmain.c            |    4 ++
 gtk/gtkmenu.c            |    2 +
 gtk/gtkwidget.c          |   12 +++++
 14 files changed, 218 insertions(+), 25 deletions(-)
---
diff --git a/gdk/gdk.c b/gdk/gdk.c
index 3d0459f..1b7e714 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -793,6 +793,8 @@ gdk_set_program_class (const char *program_class)
  * Enables multidevice support in GDK. Note that individual
  * #GdkWindow<!-- -->s still need to explicitly enable multidevice
  * awareness through gdk_window_set_support_multidevice().
+ *
+ * Since: 3.0
  **/
 void
 gdk_enable_multidevice (void)
diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index bba2786..a19e3dc 100644
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -91,6 +91,8 @@ gdk_device_class_init (GdkDeviceClass *klass)
    * GdkDevice:display:
    *
    * The #GdkDisplay the #GdkDevice pertains to.
+   *
+   * Since: 3.0
    */
   g_object_class_install_property (object_class,
 				   PROP_DISPLAY,
@@ -104,6 +106,8 @@ gdk_device_class_init (GdkDeviceClass *klass)
    * GdkDevice:device-manager:
    *
    * The #GdkDeviceManager the #GdkDevice pertains to.
+   *
+   * Since: 3.0
    */
   g_object_class_install_property (object_class,
 				   PROP_DEVICE_MANAGER,
@@ -117,6 +121,8 @@ gdk_device_class_init (GdkDeviceClass *klass)
    * GdkDevice:name:
    *
    * The device name.
+   *
+   * Since: 3.0
    */
   g_object_class_install_property (object_class,
 				   PROP_NAME,
@@ -130,6 +136,8 @@ gdk_device_class_init (GdkDeviceClass *klass)
    * GdkDevice:type:
    *
    * Device role in the device manager.
+   *
+   * Since: 3.0
    */
   g_object_class_install_property (object_class,
                                    PROP_TYPE,
@@ -145,6 +153,8 @@ gdk_device_class_init (GdkDeviceClass *klass)
    *
    * Associated pointer or keyboard to this device, if any. Devices of type #GDK_DEVICE_TYPE_MASTER
    * always come in keyboard/pointer pairs. Other device types will have a %NULL associated device.
+   *
+   * Since: 3.0
    */
   g_object_class_install_property (object_class,
 				   PROP_ASSOCIATED_DEVICE,
@@ -157,6 +167,8 @@ gdk_device_class_init (GdkDeviceClass *klass)
    * GdkDevice:input-source:
    *
    * Source type for the device.
+   *
+   * Since: 3.0
    */
   g_object_class_install_property (object_class,
 				   PROP_INPUT_SOURCE,
@@ -171,6 +183,8 @@ gdk_device_class_init (GdkDeviceClass *klass)
    * GdkDevice:input-mode:
    *
    * Input mode for the device.
+   *
+   * Since: 3.0
    */
   g_object_class_install_property (object_class,
                                    PROP_INPUT_MODE,
@@ -185,6 +199,8 @@ gdk_device_class_init (GdkDeviceClass *klass)
    *
    * Whether the device is represented by a cursor on the screen. Devices of type
    * %GDK_DEVICE_TYPE_MASTER will have %TRUE here.
+   *
+   * Since: 3.0
    */
   g_object_class_install_property (object_class,
 				   PROP_HAS_CURSOR,
@@ -198,6 +214,8 @@ gdk_device_class_init (GdkDeviceClass *klass)
    * GdkDevice:n-axes:
    *
    * Number of axes in the device.
+   *
+   * Since: 3.0
    */
   g_object_class_install_property (object_class,
 				   PROP_N_AXES,
@@ -696,6 +714,8 @@ gdk_device_set_axis_use (GdkDevice   *device,
  *
  * Returns: a #GdkDisplay. This memory is owned by GTK+,
  *          and must not be freed or unreffed.
+ *
+ * Since: 3.0
  **/
 GdkDisplay *
 gdk_device_get_display (GdkDevice *device)
@@ -724,6 +744,8 @@ gdk_device_get_display (GdkDevice *device)
  * returned, as there is no associated device.
  *
  * Returns: The associated device, or %NULL
+ *
+ * Since: 3.0
  **/
 GdkDevice *
 gdk_device_get_associated_device (GdkDevice *device)
@@ -768,6 +790,8 @@ _gdk_device_set_associated_device (GdkDevice *device,
  * Returns the device type for @device.
  *
  * Returns: the #GdkDeviceType for @device.
+ *
+ * Since: 3.0
  **/
 GdkDeviceType
 gdk_device_get_device_type (GdkDevice *device)
@@ -788,6 +812,8 @@ gdk_device_get_device_type (GdkDevice *device)
  * Returns the number of axes the device currently has.
  *
  * Returns: the number of axes.
+ *
+ * Since: 3.0
  **/
 guint
 gdk_device_get_n_axes (GdkDevice *device)
@@ -805,6 +831,8 @@ gdk_device_get_n_axes (GdkDevice *device)
  * the axes that @device currently has.
  *
  * Returns: A #GList of #GdkAtom<!-- -->s, free with g_list_free().
+ *
+ * Since: 3.0
  **/
 GList *
 gdk_device_list_axes (GdkDevice *device)
@@ -838,6 +866,8 @@ gdk_device_list_axes (GdkDevice *device)
  * by gdk_device_list_axes()
  *
  * Returns: %TRUE if the given axis use was found, otherwise %FALSE.
+ *
+ * Since: 3.0
  **/
 gboolean
 gdk_device_get_axis_value (GdkDevice *device,
@@ -980,6 +1010,8 @@ get_native_grab_event_mask (GdkEventMask grab_mask)
  * events that are emitted when the grab ends unvoluntarily.
  *
  * Returns: %GDK_GRAB_SUCCESS if the grab was successful.
+ *
+ * Since: 3.0
  **/
 GdkGrabStatus
 gdk_device_grab (GdkDevice        *device,
diff --git a/gdk/gdkdevicemanager.c b/gdk/gdkdevicemanager.c
index aa6fa26..260fb8a 100644
--- a/gdk/gdkdevicemanager.c
+++ b/gdk/gdkdevicemanager.c
@@ -37,7 +37,7 @@
  * @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,
+ * special input devices such as tablets. In short, backwards compatible with 2.X). Since version 3.0,
  * 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.
  *
@@ -258,6 +258,8 @@ gdk_device_manager_get_property (GObject      *object,
  *
  * Returns: the #GdkDisplay to which @device_manager is
  *          associated to, or #NULL.
+ *
+ * Since: 3.0
  **/
 GdkDisplay *
 gdk_device_manager_get_display (GdkDeviceManager *device_manager)
@@ -282,6 +284,8 @@ gdk_device_manager_get_display (GdkDeviceManager *device_manager)
  * Returns: a list of #GdkDevice<!-- -->s. The returned list must be
  *          freed with g_list_free (). The list elements are owned by
  *          GTK+ and must not be freed or unreffed.
+ *
+ * Since: 3.0
  **/
 GList *
 gdk_device_manager_list_devices (GdkDeviceManager *device_manager,
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index eb764b0..de65dc6 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -416,6 +416,9 @@ gdk_display_put_event (GdkDisplay     *display,
  * Release any pointer grab.
  *
  * Since: 2.2
+ *
+ * Deprecated: 3.0. Use gdk_device_ungrab(), together with gdk_device_grab()
+ *             instead.
  */
 void
 gdk_display_pointer_ungrab (GdkDisplay *display,
@@ -452,6 +455,9 @@ gdk_display_pointer_ungrab (GdkDisplay *display,
  *
  * Ungrabs the pointer on the default display, if it is grabbed by this 
  * application.
+ *
+ * Deprecated: 3.0. Use gdk_device_ungrab(), together with gdk_device_grab()
+ *             instead.
  **/
 void
 gdk_pointer_ungrab (guint32 time)
@@ -467,8 +473,10 @@ gdk_pointer_ungrab (guint32 time)
  *
  * Note that this does not take the inmplicit pointer grab on button
  * presses into account.
-
- * Return value: %TRUE if the pointer is currently grabbed by this application.* 
+ *
+ * Return value: %TRUE if the pointer is currently grabbed by this application.
+ *
+ * Deprecated: 3.0. Use gdk_display_device_is_grabbed() instead.
  **/
 gboolean
 gdk_pointer_is_grabbed (void)
@@ -484,6 +492,9 @@ gdk_pointer_is_grabbed (void)
  * Release any keyboard grab
  *
  * Since: 2.2
+ *
+ * Deprecated: 3.0. Use gdk_device_ungrab(), together with gdk_device_grab()
+ *             instead.
  */
 void
 gdk_display_keyboard_ungrab (GdkDisplay *display,
@@ -520,6 +531,9 @@ gdk_display_keyboard_ungrab (GdkDisplay *display,
  * 
  * Ungrabs the keyboard on the default display, if it is grabbed by this 
  * application.
+ *
+ * Deprecated: 3.0. Use gdk_device_ungrab(), together with gdk_device_grab()
+ *             instead.
  **/
 void
 gdk_keyboard_ungrab (guint32 time)
@@ -587,6 +601,10 @@ gdk_event_send_clientmessage_toall (GdkEvent *event)
  * 
  * Return value: the core pointer device; this is owned by the
  *   display and should not be freed.
+ *
+ * Deprecated: 3.0. Use gdk_display_get_device_manager() instead, or
+ *             gdk_event_get_device() if a #GdkEvent with pointer device
+ *             information is available.
  **/
 GdkDevice *
 gdk_device_get_core_pointer (void)
@@ -604,6 +622,10 @@ gdk_device_get_core_pointer (void)
  *   display and should not be freed.
  *
  * Since: 2.2
+ *
+ * Deprecated: 3.0. Use gdk_display_get_device_manager() instead, or
+ *             gdk_event_get_device() if a #GdkEvent with device
+ *             information is available.
  **/
 GdkDevice *
 gdk_display_get_core_pointer (GdkDisplay *display)
@@ -693,6 +715,8 @@ _gdk_display_enable_motion_hints (GdkDisplay *display,
  * @mask: location to store current modifier mask for @device, or %NULL.
  *
  * Gets the current location and state of @device for a given display.
+ *
+ * Since: 3.0
  **/
 void
 gdk_display_get_device_state (GdkDisplay       *display,
@@ -732,6 +756,8 @@ gdk_display_get_device_state (GdkDisplay       *display,
  * %NULL if the window tree under @device is not known to GDK (for example, belongs to another application).
  *
  * Returns: the #GdkWindow under the device position, or %NULL.
+ *
+ * Since: 3.0
  **/
 GdkWindow *
 gdk_display_get_window_at_device_position (GdkDisplay *display,
@@ -766,6 +792,8 @@ gdk_display_get_window_at_device_position (GdkDisplay *display,
  * an event recorder. Applications should never have any reason to use this facility.
  *
  * Returns: The previous device hook table.
+ *
+ * Since: 3.0
  **/
 GdkDisplayDeviceHooks *
 gdk_display_set_device_hooks (GdkDisplay                  *display,
@@ -797,6 +825,8 @@ gdk_display_set_device_hooks (GdkDisplay                  *display,
  * mask for a given display.
  *
  * Since: 2.2
+ *
+ * Deprecated: 3.0. Use gdk_display_get_device_state() instead.
  **/
 void
 gdk_display_get_pointer (GdkDisplay      *display,
@@ -891,6 +921,8 @@ gdk_window_real_window_get_device_position (GdkDisplay       *display,
  * Returns: (transfer none): the window under the mouse pointer, or %NULL
  *
  * Since: 2.2
+ *
+ * Deprecated: 3.0. Use gdk_display_get_window_at_device_position() instead.
  **/
 GdkWindow *
 gdk_display_get_window_at_pointer (GdkDisplay *display,
@@ -983,6 +1015,8 @@ multihead_default_window_at_pointer (GdkDisplay *display,
  * Return value: the previous pointer hook table
  *
  * Since: 2.2
+ *
+ * Deprecated: 3.0. Use gdk_display_set_device_hooks() instead.
  **/
 GdkDisplayPointerHooks *
 gdk_display_set_pointer_hooks (GdkDisplay                   *display,
@@ -1083,6 +1117,8 @@ singlehead_default_window_at_pointer  (GdkScreen       *screen,
  * see gdk_display_set_pointer_hooks().
  * 
  * Return value: the previous pointer hook table
+ *
+ * Deprecated: 3.0. Use gdk_display_set_device_hooks() instead.
  **/
 GdkPointerHooks *
 gdk_set_pointer_hooks (const GdkPointerHooks *new_hooks)
@@ -1703,6 +1739,8 @@ gdk_device_grab_info_libgtk_only (GdkDisplay  *display,
  * Returns: %TRUE if an active X pointer grab is in effect
  *
  * Since: 2.2
+ *
+ * Deprecated: 3.0. Use gdk_display_device_is_grabbed() instead.
  */
 gboolean
 gdk_display_pointer_is_grabbed (GdkDisplay *display)
@@ -1762,6 +1800,8 @@ gdk_display_device_is_grabbed (GdkDisplay *display,
  *
  * Returns: A #GdkDeviceManager, or %NULL. This memory is
  *          owned by GDK and must not be freed or unreferenced.
+ *
+ * Since: 3.0
  **/
 GdkDeviceManager *
 gdk_display_get_device_manager (GdkDisplay *display)
diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c
index d7ea369..151ce86 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -929,6 +929,8 @@ gdk_event_get_axis (const GdkEvent *event,
  * Sets the device for @event to @device. The event must
  * have been allocated by GTK+, for instance, by
  * gdk_event_copy().
+ *
+ * Since: 3.0
  **/
 void
 gdk_event_set_device (GdkEvent  *event,
@@ -973,6 +975,8 @@ gdk_event_set_device (GdkEvent  *event,
  * it, else it will return %NULL.
  *
  * Returns: a #GdkDevice, or %NULL.
+ *
+ * Since: 3.0
  **/
 GdkDevice *
 gdk_event_get_device (const GdkEvent *event)
@@ -1084,6 +1088,8 @@ gdk_events_get_axis_distances (GdkEvent *event1,
  * (as in a straight line going from @event1 to @event2) will be returned.
  *
  * Returns: %TRUE if the distance could be calculated.
+ *
+ * Since: 3.0
  **/
 gboolean
 gdk_events_get_distance (GdkEvent *event1,
@@ -1107,6 +1113,8 @@ gdk_events_get_distance (GdkEvent *event1,
  * Y axis.
  *
  * Returns: %TRUE if the angle could be calculated.
+ *
+ * Since: 3.0
  **/
 gboolean
 gdk_events_get_angle (GdkEvent *event1,
@@ -1148,6 +1156,8 @@ gdk_events_get_angle (GdkEvent *event1,
  * will be returned in @x and @y.
  *
  * Returns: %TRUE if the center could be calculated.
+ *
+ * Since: 3.0
  **/
 gboolean
 gdk_events_get_center (GdkEvent *event1,
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index a8b07ca..3e178e7 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -6447,6 +6447,8 @@ gdk_window_constrain_size (GdkGeometry *geometry,
  * Return value: (transfer none): the window containing the pointer (as with
  * gdk_window_at_pointer()), or %NULL if the window containing the
  * pointer isn't known to GDK
+ *
+ * Deprecated: 3.0. Use gdk_window_get_device_position() instead.
  **/
 GdkWindow*
 gdk_window_get_pointer (GdkWindow	  *window,
@@ -6478,6 +6480,8 @@ gdk_window_get_pointer (GdkWindow	  *window,
  * Returns: The window underneath @device (as with
  * gdk_display_get_window_at_device_position()), or %NULL if the
  * window is not known to GDK.
+ *
+ * Since: 3.0
  **/
 GdkWindow *
 gdk_window_get_device_position (GdkWindow       *window,
@@ -6525,6 +6529,8 @@ gdk_window_get_device_position (GdkWindow       *window,
  * gdk_display_get_window_at_pointer() instead.
  *
  * Return value: (transfer none): window under the mouse pointer
+ *
+ * Deprecated: 3.0. Use gdk_display_get_window_at_device_position() instead.
  **/
 GdkWindow*
 gdk_window_at_pointer (gint *win_x,
@@ -7359,6 +7365,8 @@ gdk_window_get_events (GdkWindow *window)
  * including #GDK_BUTTON_PRESS_MASK means the window should report button
  * press events. The event mask is the bitwise OR of values from the
  * #GdkEventMask enumeration.
+ *
+ * Since: 3.0
  **/
 void
 gdk_window_set_device_events (GdkWindow    *window,
@@ -7427,6 +7435,8 @@ gdk_window_set_device_events (GdkWindow    *window,
  * Returns the event mask for @window corresponding to an specific device.
  *
  * Returns: device event mask for @window
+ *
+ * Since: 3.0
  **/
 GdkEventMask
 gdk_window_get_device_events (GdkWindow *window,
@@ -8267,6 +8277,8 @@ gdk_window_set_cursor (GdkWindow *window,
  * Returns: a #GdkCursor, or %NULL. The returned object is owned
  *   by the #GdkWindow and should not be unreferenced directly. Use
  *   gdk_window_set_cursor() to unset the cursor of the window
+ *
+ * Since: 3.0
  **/
 GdkCursor *
 gdk_window_get_device_cursor (GdkWindow *window,
@@ -8294,6 +8306,8 @@ gdk_window_get_device_cursor (GdkWindow *window,
  * %NULL for the @cursor argument to gdk_window_set_cursor() means that
  * @window will use the cursor of its parent window. Most windows should
  * use this default.
+ *
+ * Since: 3.0
  **/
 void
 gdk_window_set_device_cursor (GdkWindow *window,
@@ -9762,6 +9776,8 @@ gdk_window_beep (GdkWindow *window)
  *
  * Multidevice aware windows will need to handle properly multiple,
  * per device enter/leave events, device grabs and grab ownerships.
+ *
+ * Since: 3.0
  **/
 void
 gdk_window_set_support_multidevice (GdkWindow *window,
@@ -9790,6 +9806,8 @@ gdk_window_set_support_multidevice (GdkWindow *window,
  * devices.
  *
  * Returns: %TRUE if the window handles multidevice features.
+ *
+ * Since: 3.0
  **/
 gboolean
 gdk_window_get_support_multidevice (GdkWindow *window)
@@ -10336,28 +10354,55 @@ _gdk_display_set_window_under_pointer (GdkDisplay *display,
   _gdk_display_enable_motion_hints (display, device);
 }
 
-/*
- *--------------------------------------------------------------
- * gdk_pointer_grab
- *
- *   Grabs the pointer to a specific window
- *
- * Arguments:
- *   "window" is the window which will receive the grab
- *   "owner_events" specifies whether events will be reported as is,
- *     or relative to "window"
- *   "event_mask" masks only interesting events
- *   "confine_to" limits the cursor movement to the specified window
- *   "cursor" changes the cursor for the duration of the grab
- *   "time" specifies the time
- *
- * Results:
- *
- * Side effects:
- *   requires a corresponding call to gdk_pointer_ungrab
- *
- *--------------------------------------------------------------
- */
+/**
+ * gdk_pointer_grab:
+ * @window: the #GdkWindow which will own the grab (the grab window).
+ * @owner_events: if %FALSE then all pointer 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 as normal, but pointer events outside
+ *                this application are reported with respect to @window and only if selected by
+ *                @event_mask. In either mode, unreported events are discarded.
+ * @event_mask: specifies the event mask, which is used in accordance with
+ *              @owner_events. Note that only pointer events (i.e. button and motion events)
+ *              may be selected.
+ * @confine_to: If non-%NULL, the pointer will be confined to this
+ *              window during the grab. If the pointer is outside @confine_to, it will
+ *              automatically be moved to the closest edge of @confine_to and enter
+ *              and leave events will be generated as necessary.
+ * @cursor: the cursor to display while the grab is active. If this is %NULL then
+ *          the normal cursors are used for @window and its descendants, and the cursor
+ *          for @window is used for all other windows.
+ * @time_: the timestamp of the event which led to this pointer grab. This usually
+ *         comes from a #GdkEventButton struct, though %GDK_CURRENT_TIME can be used if
+ *         the time isn't known.
+ *
+ * Grabs the pointer (usually a mouse) so that all events are passed to this
+ * application until the pointer is ungrabbed with gdk_pointer_ungrab(), or
+ * the grab window becomes unviewable.
+ * This overrides any previous pointer grab by this client.
+ *
+ * Pointer grabs are used for operations which need complete control over mouse
+ * events, even if the mouse leaves the application.
+ * For example in GTK+ it is used for Drag and Drop, for dragging the handle in
+ * the #GtkHPaned and #GtkVPaned widgets, and for resizing columns in #GtkCList
+ * widgets.
+ *
+ * Note that if the event mask of an X window has selected both button press and
+ * button release events, then a button press event will cause an automatic
+ * pointer grab until the button is released.
+ * X does this automatically since most applications expect to receive button
+ * press and release events in pairs.
+ * It is equivalent to a pointer grab on the window with @owner_events set to
+ * %TRUE.
+ *
+ * If you set up anything at the time you take the grab that needs to be cleaned
+ * up when the grab ends, you should handle the #GdkEventGrabBroken events that
+ * are emitted when the grab ends unvoluntarily.
+ *
+ * Returns: %GDK_GRAB_SUCCESS if the grab was successful.
+ *
+ * Deprecated: 3.0. Use gdk_device_grab() instead.
+ **/
 GdkGrabStatus
 gdk_pointer_grab (GdkWindow *	  window,
 		  gboolean	  owner_events,
@@ -10453,6 +10498,30 @@ gdk_pointer_grab (GdkWindow *	  window,
   return res;
 }
 
+/**
+ * gdk_keyboard_grab:
+ * @window: the #GdkWindow which will own the grab (the grab window).
+ * @owner_events: if %FALSE then all keyboard events are reported with respect to
+ *                @window. If %TRUE then keyboard events for this application are
+ *                reported as normal, but keyboard events outside this application
+ *                are reported with respect to @window. Both key press and key
+ *                release events are always reported, independant of the event mask
+ *                set by the application.
+ * @time: a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is
+available.
+ *
+ * Grabs the keyboard so that all events are passed to this
+ * application until the keyboard is ungrabbed with gdk_keyboard_ungrab().
+ * This overrides any previous keyboard grab by this client.
+ *
+ * If you set up anything at the time you take the grab that needs to be cleaned
+ * up when the grab ends, you should handle the #GdkEventGrabBroken events that
+ * are emitted when the grab ends unvoluntarily.
+ *
+ * Returns: %GDK_GRAB_SUCCESS if the grab was successful.
+ *
+ * Deprecated: 3.0. Use gdk_device_grab() instead.
+ **/
 GdkGrabStatus
 gdk_keyboard_grab (GdkWindow *window,
 		   gboolean   owner_events,
diff --git a/gdk/x11/gdkdisplay-x11.c b/gdk/x11/gdkdisplay-x11.c
index 9066d20..6544716 100644
--- a/gdk/x11/gdkdisplay-x11.c
+++ b/gdk/x11/gdkdisplay-x11.c
@@ -1645,6 +1645,8 @@ device_ungrab_callback (GdkDisplay *display,
  * @time_: a timestap (e.g. %GDK_CURRENT_TIME).
  *
  * Release any grab on @device.
+ *
+ * Since: 3.0
  */
 void
 gdk_device_ungrab (GdkDevice  *device,
diff --git a/gdk/x11/gdkinput.c b/gdk/x11/gdkinput.c
index 199a259..2a83e3e 100644
--- a/gdk/x11/gdkinput.c
+++ b/gdk/x11/gdkinput.c
@@ -52,6 +52,8 @@ struct _GdkInputWindow
  * The list is statically allocated and should not be freed.
  *
  * Return value: a list of #GdkDevice
+ *
+ * Deprecated: 3.0. Use gdk_display_get_device_manager() instead.
  **/
 GList *
 gdk_devices_list (void)
@@ -140,6 +142,8 @@ unset_extension_events (GdkWindow *window)
  *
  * Turns extension events on or off for a particular window,
  * and specifies the event mask for extension events.
+ *
+ * Deprecated: 3.0. Use gdk_window_set_device_events() instead.
  **/
 void
 gdk_input_set_extension_events (GdkWindow        *window,
diff --git a/gdk/x11/gdkwindow-x11.c b/gdk/x11/gdkwindow-x11.c
index fad8d4f..1eedd43 100644
--- a/gdk/x11/gdkwindow-x11.c
+++ b/gdk/x11/gdkwindow-x11.c
@@ -3142,6 +3142,8 @@ gdk_window_x11_get_device_state (GdkWindow       *window,
  * for the color picker in the #GtkColorSelectionDialog.
  *
  * Since: 2.8
+ *
+ * Deprecated: 3.0. Use gdk_display_warp_device() instead.
  */ 
 void
 gdk_display_warp_pointer (GdkDisplay *display,
@@ -3177,6 +3179,8 @@ gdk_display_warp_pointer (GdkDisplay *display,
  * control of the user. This function was added to cover
  * some rare use cases like keyboard navigation support
  * for the color picker in the #GtkColorSelectionDialog.
+ *
+ * Since: 3.0
  **/
 void
 gdk_display_warp_device (GdkDisplay *display,
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index c6b930d..978e002 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -1918,6 +1918,8 @@ gtk_combo_box_popup (GtkComboBox *combo_box)
  * Pops up the menu or dropdown list of @combo_box, the popup window
  * will be grabbed so only @device and its associated pointer/keyboard
  * are the only #GdkDevice<!-- -->s able to send events to it.
+ *
+ * Since: 3.0
  **/
 void
 gtk_combo_box_popup_for_device (GtkComboBox *combo_box,
diff --git a/gtk/gtkdevicegroup.c b/gtk/gtkdevicegroup.c
index 1e0d659..ef9b0ee 100644
--- a/gtk/gtkdevicegroup.c
+++ b/gtk/gtkdevicegroup.c
@@ -130,6 +130,8 @@ gtk_device_group_finalize (GObject *object)
  * 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.
+ *
+ * Since: 3.0
  **/
 void
 gtk_device_group_add_device (GtkDeviceGroup *group,
@@ -158,6 +160,8 @@ gtk_device_group_add_device (GtkDeviceGroup *group,
  * @device: a #GdkDevice
  *
  * Removes @device from @group, if it was there.
+ *
+ * Since: 3.0
  **/
 void
 gtk_device_group_remove_device (GtkDeviceGroup *group,
@@ -192,6 +196,8 @@ gtk_device_group_remove_device (GtkDeviceGroup *group,
  *
  * Returns: a list of #GdkDevices. This list and its elements are owned
  *          by group, and must not be freed or unref'ed.
+ *
+ * Since: 3.0
  **/
 GList *
 gtk_device_group_get_devices (GtkDeviceGroup *group)
diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index 9cad827..ea54a4b 100644
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -1970,6 +1970,8 @@ gtk_grab_remove (GtkWidget *widget)
  * associated pointer or keyboard (if any) are delivered to @widget.
  * If the @block_others parameter is %TRUE, any other devices will be
  * unable to interact with @widget during the grab.
+ *
+ * Since: 3.0
  **/
 void
 gtk_device_grab_add (GtkWidget        *widget,
@@ -1998,6 +2000,8 @@ gtk_device_grab_add (GtkWidget        *widget,
  *
  * Removes a device grab from the given widget. You have to pair calls
  * to gtk_device_grab_add() and gtk_device_grab_remove().
+ *
+ * Since: 3.0
  **/
 void
 gtk_device_grab_remove (GtkWidget *widget,
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index b608e1a..e999994 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -1433,6 +1433,8 @@ popup_grab_on_window (GdkWindow *window,
  * a mouse click or key press) that caused the initiation of the popup.
  * Only if no such event is available, gtk_get_current_event_time() can
  * be used instead.
+ *
+ * Since: 3.0
  */
 void
 gtk_menu_popup_for_device (GtkMenu             *menu,
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 0ca59d1..15d6b44 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -2416,6 +2416,8 @@ gtk_widget_class_init (GtkWidgetClass *klass)
    * 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.
+   *
+   * Since: 3.0
    */
   widget_signals[MULTIDEVICE_EVENT] =
     g_signal_new (I_("multidevice-event"),
@@ -5787,6 +5789,8 @@ _gtk_widget_set_has_grab (GtkWidget *widget,
  *
  * Returns: %TRUE if there is an ongoing grab on @device
  *          by another #GtkWidget than @widget.
+ *
+ * Since: 3.0
  **/
 gboolean
 gtk_widget_device_is_shadowed (GtkWidget *widget,
@@ -11474,6 +11478,8 @@ gtk_widget_get_support_multidevice (GtkWidget *widget)
  * @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.
+ *
+ * Since: 3.0
  **/
 void
 gtk_widget_set_support_multidevice (GtkWidget *widget,
@@ -11637,6 +11643,8 @@ free_multidevice_data (GtkMultiDeviceData *data)
  * Returns: a newly created #GtkDeviceGroup. This object is owned by
  *          @widget and must be destroyed through
  *          gtk_widget_remove_device_group().
+ *
+ * Since: 3.0
  **/
 GtkDeviceGroup *
 gtk_widget_create_device_group (GtkWidget *widget)
@@ -11681,6 +11689,8 @@ gtk_widget_create_device_group (GtkWidget *widget)
  *
  * If @group pertains to @widget, @group will be destroyed so no further
  * #GtkWidget::multidevice-event<!-- -->s are emitted for it.
+ *
+ * Since: 3.0
  **/
 void
 gtk_widget_remove_device_group (GtkWidget      *widget,
@@ -11726,6 +11736,8 @@ gtk_widget_remove_device_group (GtkWidget      *widget,
  * there is none.
  *
  * Returns: a #GtkDeviceGroup, or %NULL.
+ *
+ * Since: 3.0
  **/
 GtkDeviceGroup *
 gtk_widget_get_group_for_device (GtkWidget *widget,