Fix up GDK docs

docs/reference/gdk/Makefile.am

@@ -26,7 +26,7 @@ IGNORE_HFILES=			\
 	gdkkeysyms.h		\
 	gdkinternals.h		\
 	gdkprivate.h		\
-	gdkpoly-generic.h	\
+	gdk*private.h		\
 	keyname-table.h		\
 	win32			\
 	x11			\
@@ -58,7 +58,6 @@ content_files = 		\
 # Images to copy into HTML directory
 HTML_IMAGES = 				\
 	images/rotated-text.png		\
-					\
 	images/X_cursor.png		\
 	images/arrow.png		\
 	images/based_arrow_down.png	\

docs/reference/gdk/gdk-docs.sgml

@@ -20,6 +20,8 @@
     <xi:include href="multihead.sgml" />
     <xi:include href="xml/gdkdisplay.xml" />
     <xi:include href="xml/gdkdisplaymanager.xml" />
+    <xi:include href="xml/gdkdevice.xml" />
+    <xi:include href="xml/gdkdevicemanager.xml" />
     <xi:include href="xml/gdkscreen.xml" />
     <xi:include href="xml/regions.xml" />
     <xi:include href="xml/pixbufs.xml" />
@@ -35,7 +37,6 @@
     <xi:include href="xml/dnd.xml" />
     <xi:include href="xml/properties.xml" />
     <xi:include href="xml/threads.xml" />
-    <xi:include href="xml/gdkdevicemanager.xml" />
     <xi:include href="xml/pango_interaction.xml" />
     <xi:include href="xml/cairo_interaction.xml" />
     <xi:include href="xml/x_interaction.xml" />

docs/reference/gdk/gdk3-sections.txt

@@ -119,11 +119,13 @@ gdk_display_is_closed
 gdk_display_get_event
 gdk_display_peek_event
 gdk_display_put_event
+gdk_display_has_pending
 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_list_devices
 gdk_display_get_window_at_pointer
 gdk_display_get_window_at_device_position
 GdkDisplayPointerHooks
@@ -143,6 +145,9 @@ gdk_display_store_clipboard
 gdk_display_supports_shapes
 gdk_display_supports_input_shapes
 gdk_display_supports_composite
+gdk_display_get_app_launch_context
+gdk_display_notify_startup_complete
+
 <SUBSECTION Standard>
 GDK_DISPLAY
 GDK_DISPLAY_OBJECT
@@ -166,6 +171,8 @@ gdk_display_manager_get
 gdk_display_manager_get_default_display
 gdk_display_manager_set_default_display
 gdk_display_manager_list_displays
+gdk_display_manager_open_display
+
 <SUBSECTION Standard>
 GDK_DISPLAY_MANAGER
 GDK_DISPLAY_MANAGER_CLASS
@@ -664,19 +671,14 @@ gdk_keymap_get_type
 </SECTION>
 
 <SECTION>
-<TITLE>GdkDeviceManager</TITLE>
+<TITLE>GdkDevice</TITLE>
-<FILE>gdkdevicemanager</FILE>
+<FILE>gdkdevice</FILE>
-GdkDeviceManager
 GdkDevice
-GdkDeviceType
 GdkInputSource
 GdkInputMode
 GdkAxisUse
+GdkDeviceType
 GdkGrabOwnership
-gdk_disable_multidevice
-gdk_device_manager_get_display
-gdk_device_manager_list_devices
-gdk_device_manager_get_client_pointer
 
 <SUBSECTION>
 gdk_device_get_name
@@ -689,6 +691,7 @@ gdk_device_get_key
 gdk_device_set_axis_use
 gdk_device_get_axis_use
 gdk_device_get_associated_device
+gdk_device_list_slave_devices
 gdk_device_get_device_type
 gdk_device_get_display
 gdk_device_get_has_cursor
@@ -716,12 +719,6 @@ 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
@@ -731,13 +728,33 @@ 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>
 
+<SECTION>
+<TITLE>GdkDeviceManager</TITLE>
+<FILE>gdkdevicemanager</FILE>
+GdkDeviceManager
+gdk_disable_multidevice
+gdk_device_manager_get_display
+gdk_device_manager_list_devices
+gdk_device_manager_get_client_pointer
+
+<SUBSECTION Standard>
+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
+
+<SUBSECTION Private>
+GdkDeviceManagerClass
+gdk_device_manager_get_type
+</SECTION>
+
 <SECTION>
 <TITLE>Events</TITLE>
 <FILE>events</FILE>
@@ -747,7 +764,6 @@ GDK_CURRENT_TIME
 GDK_PRIORITY_EVENTS
 GDK_PRIORITY_REDRAW
 
-
 <SUBSECTION>
 gdk_events_pending
 gdk_event_peek
@@ -783,6 +799,8 @@ gdk_event_set_screen
 gdk_event_get_screen
 gdk_event_get_device
 gdk_event_set_device
+gdk_event_get_source_device
+gdk_event_set_source_device
 
 <SUBSECTION>
 gdk_setting_get
@@ -872,27 +890,31 @@ gdk_cursor_get_type
 <SECTION>
 <TITLE>Drag and Drop</TITLE>
 <FILE>dnd</FILE>
+GdkDragContext
 gdk_drag_get_selection
 gdk_drag_abort
 gdk_drop_reply
 gdk_drag_drop
 gdk_drag_find_window_for_screen
-gdk_drag_context_get_source_window
 gdk_drag_begin
+gdk_drag_begin_for_device
 gdk_drag_motion
 gdk_drop_finish
 gdk_drag_get_protocol_for_display
 GdkDragProtocol
-GdkDragContext
 GdkDragAction
 gdk_drag_status
 gdk_drag_drop_succeeded
+
 gdk_drag_context_get_actions
 gdk_drag_context_get_suggested_action
 gdk_drag_context_get_selected_action
 gdk_drag_context_list_targets
 gdk_drag_context_get_device
 gdk_drag_context_set_device
+gdk_drag_context_get_source_window
+gdk_drag_context_get_dest_window
+gdk_drag_context_get_protocol
 
 <SUBSECTION Standard>
 GDK_DRAG_CONTEXT
@@ -968,6 +990,24 @@ gdk_x11_free_text_list
 gdk_x11_display_string_to_compound_text
 gdk_x11_display_utf8_to_compound_text
 gdk_x11_free_compound_text
+
+<SUBSECTION Private>
+gdk_x11_app_launch_context_get_type
+gdk_x11_cursor_get_type
+gdk_x11_device_core_get_type
+gdk_x11_device_manager_core_get_type
+gdk_x11_device_manager_xi2_get_type
+gdk_x11_device_manager_xi_get_type
+gdk_x11_device_xi2_get_type
+gdk_x11_device_xi_get_type
+gdk_x11_display_get_type
+gdk_x11_display_manager_get_type
+gdk_x11_drag_context_get_type
+gdk_x11_keymap_get_type
+gdk_x11_screen_get_type
+gdk_x11_visual_get_type
+gdk_x11_window_get_type
+gdk_window_impl_x11_get_type
 </SECTION>
 
 <SECTION>

docs/reference/gdk/gdk3.types

@@ -1,9 +1,13 @@
 #include <gdk/gdk.h>
 
-gdk_display_get_type
+gdk_app_launch_context_get_type
-gdk_display_manager_get_type
+gdk_cursor_get_type
-gdk_screen_get_type
-gdk_window_get_type
-gdk_keymap_get_type
 gdk_device_get_type
 gdk_device_manager_get_type
+gdk_display_get_type
+gdk_display_manager_get_type
+gdk_drag_context_get_type
+gdk_keymap_get_type
+gdk_screen_get_type
+gdk_visual_get_type
+gdk_window_get_type

gdk/gdk.c

@@ -58,9 +58,7 @@
  * Since GDK may be configured with multiple backends, an additional
  * runtime check for the used backend is recommended:
  *
- * <example>
+ * |[
- * <title>Backend-specific code</title>
- * <programlisting>
  * #ifdef GDK_WINDOWING_X11
  *   if (GDK_IS_X11_DISPLAY (display))
  *     {
@@ -76,8 +74,7 @@
  *   else
  * #endif
  *   g_error ("Unsupported GDK backend");
- * </programlisting>
+ * ]|
- * </example>
  */
 
 /**
@@ -1091,7 +1088,7 @@ gdk_set_program_class (const char *program_class)
  * any way and doesn't observe the presence of XInput 2.
  *
  * Since: 3.0
- **/
+ */
 void
 gdk_disable_multidevice (void)
 {

gdk/gdkdevice.c

@@ -24,6 +24,19 @@
 #include "gdkinternals.h"
 #include "gdkintl.h"
 
+/**
+ * SECTION:gdkdevice
+ * @Short_description: Object representing an input device
+ * @Title: GdkDevice
+ * @See_also: #GdkDeviceManager
+ *
+ * The #GdkDevice object represents a single input device.
+ *
+ * See the #GdkDeviceManager documentation for more information
+ * about the various kinds of master and slave devices, and their
+ * relationships.
+ */
+
 typedef struct _GdkAxisInfo GdkAxisInfo;
 
 struct _GdkAxisInfo

gdk/gdkdevicemanager.c

@@ -27,66 +27,82 @@
 /**
  * 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_disable_multidevice()
+ * @See_also: #GdkDevice, #GdkEvent
  *
- * By default, and if the platform supports it, GDK is aware of multiple keyboard/pointer pairs
+ * In addition to a single pointer and keyboard for user interface input,
- * and multitouch devices, this behavior can be changed by calling gdk_disable_multidevice()
+ * GDK contains support for a variety of input devices, including graphics
- * before gdk_display_open(), although there would be rarely a reason to do that. For a widget
+ * tablets, touchscreens and multiple pointers/keyboards interacting
- * or window to be dealt as multipointer aware, gdk_window_set_support_multidevice() or
+ * 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.
+ *
+ * By default, and if the platform supports it, GDK is aware of multiple
+ * keyboard/pointer pairs and multitouch devices, this behavior can be
+ * changed by calling gdk_disable_multidevice() before gdk_display_open(),
+ * although there would be rarely a reason to do that. For a widget or
+ * window to be dealt as multipointer aware,
+ * gdk_window_set_support_multidevice() or
  * gtk_widget_set_support_multidevice() must have been called on it.
  *
- * Conceptually, in multidevice mode there are 2 device types, virtual devices (or master devices)
+ * Conceptually, in multidevice mode there are 2 device types, virtual
- * are represented by the pointer cursors and keyboard foci that are seen on the screen. physical
+ * devices (or master devices) are represented by the pointer cursors
- * devices (or slave devices) represent the hardware that is controlling the virtual devices, and
+ * and keyboard foci that are seen on the screen. Physical devices (or
- * thus has no visible cursor on the screen.
+ * 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,
+ * Virtual devices are always paired, there is a keyboard device for every
- * associations between devices may be inspected through gdk_device_get_associated_device().
+ * 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
+ * There may be several virtual devices, and several physical devices could
- * these virtual devices. Physical devices may also be "floating", which means they are not attached
+ * be controlling each of these virtual devices. Physical devices may also
- * to any virtual device.
+ * 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
+ * By default, GDK will automatically listen for events coming from all
- * #GdkDevice for all events coming from input devices
+ * 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,
+ * Events containing device information are #GDK_MOTION_NOTIFY,
- *   #GDK_3BUTTON_PRESS, #GDK_BUTTON_RELEASE, #GDK_SCROLL, #GDK_KEY_PRESS, #GDK_KEY_RELEASE,
+ * #GDK_BUTTON_PRESS, #GDK_2BUTTON_PRESS, #GDK_3BUTTON_PRESS,
- *   #GDK_ENTER_NOTIFY, #GDK_LEAVE_NOTIFY, #GDK_FOCUS_CHANGE, #GDK_PROXIMITY_IN, #GDK_PROXIMITY_OUT,
+ * #GDK_BUTTON_RELEASE, #GDK_SCROLL, #GDK_KEY_PRESS, #GDK_KEY_RELEASE,
- *   #GDK_DRAG_ENTER, #GDK_DRAG_LEAVE, #GDK_DRAG_MOTION, #GDK_DRAG_STATUS, #GDK_DROP_START,
+ * #GDK_ENTER_NOTIFY, #GDK_LEAVE_NOTIFY, #GDK_FOCUS_CHANGE,
- *   #GDK_DROP_FINISHED and #GDK_GRAB_BROKEN.
+ * #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
+ * although gdk_window_set_support_multidevice() has to be called on
- * support additional features of multiple pointer interaction, such as multiple, per-device enter/leave
+ * #GdkWindows in order to support additional features of multiple pointer
- * events. The default setting will emit just one enter/leave event pair for all devices on the window.
+ * interaction, such as multiple, per-device enter/leave events. The default
- * See gdk_window_set_support_multidevice() documentation for more information.
+ * 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()
+ * In order to listen for events coming from other than a virtual device,
- * must be called. Generally, this function can be used to modify the event mask for any given 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
+ * Input devices may also provide additional information besides X/Y.
- * also provide pressure and X/Y tilt information. This information is device-dependent, and may be
+ * For example, graphics tablets may also provide pressure and X/Y tilt
- * queried through gdk_device_get_axis(). In multidevice mode, virtual devices will change axes in order
+ * information. This information is device-dependent, and may be
- * to always represent the physical device that is routing events through it. Whenever the physical device
+ * queried through gdk_device_get_axis(). In multidevice mode, virtual
- * changes, the #GdkDevice:n-axes property will be notified, and gdk_device_list_axes() will return the
+ * devices will change axes in order to always represent the physical
- * new device axes.
+ * 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
+ * Devices may also have associated <firstterm>keys</firstterm> or
- * globally set to map into normal X keyboard events. The mapping is set using gdk_device_set_key().
+ * 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
+ * In order to query the device hierarchy and be aware of changes in the
- * virtual devices being created or removed, or physical devices being plugged or unplugged), GDK
+ * device hierarchy (such as virtual devices being created or removed, or
- * provides #GdkDeviceManager. On X11, multidevice support is implemented through XInput 2. Unless
+ * physical devices being plugged or unplugged), GDK provides
- * gdk_disable_multidevice() is called, the XInput 2.x #GdkDeviceManager implementation will be used
+ * #GdkDeviceManager. On X11, multidevice support is implemented through
- * as input source, else either the core or XInput 1.x implementations will be used.
+ * XInput 2. Unless gdk_disable_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,

gdk/gdkdevicemanagerprivate.h

@@ -36,6 +36,7 @@ struct _GdkDeviceManager
 {
   GObject parent_instance;
 
+  /*< private >*/
   GdkDisplay *display;
 };
 

gdk/gdkdisplay.c

@@ -2271,8 +2271,8 @@ gdk_drag_get_protocol_for_display (GdkDisplay      *display,
  *
  * Opens a display.
  *
- * Return value: (transfer none): a #GdkDisplay, or %NULL if the display
+ * Return value: (transfer none): a #GdkDisplay, or %NULL
- *               could not be opened.
+ *     if the display could not be opened
  *
  * Since: 2.2
  */
@@ -2282,6 +2282,17 @@ gdk_display_open (const gchar *display_name)
   return gdk_display_manager_open_display (gdk_display_manager_get (), display_name);
 }
 
+/**
+ * gdk_display_has_pending:
+ * @display: a #GdkDisplay
+ *
+ * Returns whether the display has events that are waiting
+ * to be processed.
+ *
+ * Returns: %TRUE if there are events ready to be processed.
+ *
+ * Since: 3.0
+ */
 gboolean
 gdk_display_has_pending (GdkDisplay *display)
 {
@@ -2437,16 +2448,16 @@ gdk_notify_startup_complete (void)
 
 /**
  * gdk_notify_startup_complete_with_id:
- * @startup_id: a startup-notification identifier, for which notification
+ * @startup_id: a startup-notification identifier, for which
- *              process should be completed
+ *     notification process should be completed
  *
- * Indicates to the GUI environment that the application has finished
+ * Indicates to the GUI environment that the application has
- * loading, using a given identifier.
+ * finished loading, using a given identifier.
  *
- * GTK+ will call this function automatically for #GtkWindow with custom
+ * GTK+ will call this function automatically for #GtkWindow
- * startup-notification identifier unless
+ * with custom startup-notification identifier unless
- * gtk_window_set_auto_startup_notification() is called to disable
+ * gtk_window_set_auto_startup_notification() is called to
- * that feature.
+ * disable that feature.
  *
  * Since: 2.12
  */
@@ -2460,6 +2471,22 @@ gdk_notify_startup_complete_with_id (const gchar* startup_id)
     gdk_display_notify_startup_complete (display, startup_id);
 }
 
+/**
+ * gdk_display_notify_startup_complete:
+ * @display: a #GdkDisplay
+ * @startup_id: a startup-notification identifier, for which
+ *     notification process should be completed
+ *
+ * Indicates to the GUI environment that the application has
+ * finished loading, using a given identifier.
+ *
+ * GTK+ will call this function automatically for #GtkWindow
+ * with custom startup-notification identifier unless
+ * gtk_window_set_auto_startup_notification() is called to
+ * disable that feature.
+ *
+ * Since: 3.0
+ */
 void
 gdk_display_notify_startup_complete (GdkDisplay  *display,
                                      const gchar *startup_id)

gdk/gdkdisplay.h

@@ -173,7 +173,7 @@ void gdk_display_set_double_click_distance (GdkDisplay   *display,
 GdkDisplay *gdk_display_get_default (void);
 
 #ifndef GDK_MULTIDEVICE_SAFE
-
+#ifndef GDK_DISABLE_DEPRECATED
 void             gdk_display_get_pointer           (GdkDisplay             *display,
                                                     GdkScreen             **screen,
                                                     gint                   *x,
@@ -186,6 +186,9 @@ void             gdk_display_warp_pointer          (GdkDisplay             *disp
                                                     GdkScreen              *screen,
                                                     gint                   x,
                                                     gint                   y);
+GdkDisplayPointerHooks *gdk_display_set_pointer_hooks (GdkDisplay                   *display,
+                                                       const GdkDisplayPointerHooks *new_hooks);
+#endif /* GDK_DISABLE_DEPRECATED */
 #endif /* GDK_MULTIDEVICE_SAFE */
 
 void             gdk_display_get_device_state              (GdkDisplay            *display,
@@ -199,11 +202,6 @@ GdkWindow *      gdk_display_get_window_at_device_position (GdkDisplay
                                                             gint                  *win_x,
                                                             gint                  *win_y);
 
-#ifndef GDK_MULTIDEVICE_SAFE
-GdkDisplayPointerHooks *gdk_display_set_pointer_hooks (GdkDisplay                   *display,
-                                                       const GdkDisplayPointerHooks *new_hooks);
-#endif /* GDK_MULTIDEVICE_SAFE */
-
 GdkDisplayDeviceHooks *gdk_display_set_device_hooks (GdkDisplay                  *display,
                                                      const GdkDisplayDeviceHooks *new_hooks);
 

gdk/gdkdisplaymanager.c

@@ -298,6 +298,18 @@ gdk_display_manager_list_displays (GdkDisplayManager *manager)
   return GDK_DISPLAY_MANAGER_GET_CLASS (manager)->list_displays (manager);
 }
 
+/**
+ * gdk_display_manager_open_display:
+ * @manager: a #GdkDisplayManager
+ * @name: the name of the display to open
+ *
+ * Opens a display.
+ *
+ * Return value: (transfer none): a #GdkDisplay, or %NULL
+ *     if the display could not be opened
+ *
+ * Since: 3.0
+ */
 GdkDisplay *
 gdk_display_manager_open_display (GdkDisplayManager *manager,
                                   const gchar       *name)

gdk/gdkdndprivate.h

@@ -69,6 +69,7 @@ struct _GdkDragContextClass {
 struct _GdkDragContext {
   GObject parent_instance;
 
+  /*< private >*/
   GdkDragProtocol protocol;
 
   gboolean is_source;

gdk/gdkmain.h

@@ -50,8 +50,6 @@ gboolean              gdk_init_check                      (gint           *argc,
 void                  gdk_add_option_entries_libgtk_only  (GOptionGroup   *group);
 void                  gdk_pre_parse_libgtk_only           (void);
 
-void                  gdk_enable_multidevice              (void);
-
 G_CONST_RETURN gchar *gdk_get_program_class               (void);
 void                  gdk_set_program_class               (const gchar    *program_class);
 
@@ -96,9 +94,11 @@ GdkGrabStatus gdk_keyboard_grab      (GdkWindow    *window,
 #ifndef GDK_MULTIHEAD_SAFE
 
 #ifndef GDK_MULTIDEVICE_SAFE
+#ifndef GDK_DISABLE_DEPRECATED
 void          gdk_pointer_ungrab     (guint32       time_);
 void          gdk_keyboard_ungrab    (guint32       time_);
 gboolean      gdk_pointer_is_grabbed (void);
+#endif /* GDK_DISABLE_DEPRECATED */
 #endif /* GDK_MULTIDEVICE_SAFE */
 
 gint gdk_screen_width  (void) G_GNUC_CONST;

gdk/gdkvisual.c

@@ -32,25 +32,26 @@
  * @Short_description: Low-level display hardware information
  * @Title: Visuals
  *
- * A #GdkVisual describes a particular video hardware display format. It includes
+ * A #GdkVisual describes a particular video hardware display format.
- * information about the number of bits used for each color, the way the bits are
+ * It includes information about the number of bits used for each color,
- * translated into an RGB value for display, and the way the bits are stored in
+ * the way the bits are translated into an RGB value for display, and
- * memory. For example, a piece of display hardware might support 24-bit color,
+ * the way the bits are stored in memory. For example, a piece of display
- * 16-bit color, or 8-bit color; meaning 24/16/8-bit pixel sizes. For a given
+ * hardware might support 24-bit color, 16-bit color, or 8-bit color;
- * pixel size, pixels can be in different formats; for example the "red" element
+ * meaning 24/16/8-bit pixel sizes. For a given pixel size, pixels can
- * of an RGB pixel may be in the top 8 bits of the pixel, or may be in the lower
+ * be in different formats; for example the "red" element of an RGB pixel
- * 4 bits.
+ * may be in the top 8 bits of the pixel, or may be in the lower 4 bits.
  *
  * There are several standard visuals. The visual returned by
  * gdk_screen_get_system_visual() is the system's default visual.
  *
- * A number of functions are provided for determining the "best" available visual.
+ * A number of functions are provided for determining the "best" available
- * For the purposes of making this determination, higher bit depths are considered
+ * visual. For the purposes of making this determination, higher bit depths
- * better, and for visuals of the same bit depth, %GDK_VISUAL_PSEUDO_COLOR is
+ * are considered better, and for visuals of the same bit depth,
- * preferred at 8bpp, otherwise, the visual types are ranked in the order of
+ * %GDK_VISUAL_PSEUDO_COLOR is preferred at 8bpp, otherwise, the visual
- * (highest to lowest) %GDK_VISUAL_DIRECT_COLOR, %GDK_VISUAL_TRUE_COLOR,
+ * types are ranked in the order of(highest to lowest)
- * %GDK_VISUAL_PSEUDO_COLOR, %GDK_VISUAL_STATIC_COLOR, %GDK_VISUAL_GRAYSCALE,
+ * %GDK_VISUAL_DIRECT_COLOR, %GDK_VISUAL_TRUE_COLOR,
- * then %GDK_VISUAL_STATIC_GRAY.
+ * %GDK_VISUAL_PSEUDO_COLOR, %GDK_VISUAL_STATIC_COLOR,
+ * %GDK_VISUAL_GRAYSCALE, then %GDK_VISUAL_STATIC_GRAY.
  */
 
 G_DEFINE_TYPE (GdkVisual, gdk_visual, G_TYPE_OBJECT)
@@ -87,7 +88,7 @@ gdk_visual_class_init (GdkVisualClass *visual_class)
  *
  * Return value: (transfer container) (element-type GdkVisual):
  *     a list of visuals; the list must be freed, but not its contents
- **/
+ */
 GList*
 gdk_list_visuals (void)
 {
@@ -102,7 +103,7 @@ gdk_list_visuals (void)
  * The return value should not be freed.
  *
  * Return value: (transfer none): system visual
- **/
+ */
 GdkVisual*
 gdk_visual_get_system (void)
 {
@@ -117,7 +118,7 @@ gdk_visual_get_system (void)
  * per pixel.
  *
  * Return value: best available depth
- **/
+ */
 gint
 gdk_visual_get_best_depth (void)
 {
@@ -132,7 +133,7 @@ gdk_visual_get_best_depth (void)
  * Return the best available visual type for the default GDK screen.
  *
  * Return value: best visual type
- **/
+ */
 GdkVisualType
 gdk_visual_get_best_type (void)
 {
@@ -148,7 +149,7 @@ gdk_visual_get_best_type (void)
  * GDK screen. The return value should not be freed.
  *
  * Return value: (transfer none): best visual
- **/
+ */
 GdkVisual*
 gdk_visual_get_best (void)
 {
@@ -163,11 +164,11 @@ gdk_visual_get_best (void)
  *
  * Get the best visual with depth @depth for the default GDK screen.
  * Color visuals and visuals with mutable colormaps are preferred
- * over grayscale or fixed-colormap visuals. The return value should not
+ * over grayscale or fixed-colormap visuals. The return value should
- * be freed. %NULL may be returned if no visual supports @depth.
+ * not be freed. %NULL may be returned if no visual supports @depth.
  *
  * Return value: (transfer none): best visual for the given depth
- **/
+ */
 GdkVisual*
 gdk_visual_get_best_with_depth (gint depth)
 {
@@ -186,7 +187,7 @@ gdk_visual_get_best_with_depth (gint depth)
  * @visual_type.
  *
  * Return value: (transfer none): best visual of the given type
- **/
+ */
 GdkVisual*
 gdk_visual_get_best_with_type (GdkVisualType visual_type)
 {
@@ -201,11 +202,12 @@ gdk_visual_get_best_with_type (GdkVisualType visual_type)
  * @depth: a bit depth
  * @visual_type: a visual type
  *
- * Combines gdk_visual_get_best_with_depth() and gdk_visual_get_best_with_type().
+ * Combines gdk_visual_get_best_with_depth() and
+ * gdk_visual_get_best_with_type().
  *
  * Return value: (transfer none): best visual with both @depth and
  *     @visual_type, or %NULL if none
- **/
+ */
 GdkVisual*
 gdk_visual_get_best_with_both (gint          depth,
 			       GdkVisualType visual_type)
@@ -226,8 +228,7 @@ gdk_visual_get_best_with_both (gint          depth,
  * visual, removing duplicates.
  *
  * The array returned by this function should not be freed.
- *
+ */
- **/
 void
 gdk_query_depths (gint **depths,
                   gint  *count)
@@ -248,7 +249,7 @@ gdk_query_depths  (gint **depths,
  * visual, removing duplicates.
  *
  * The array returned by this function should not be freed.
- **/
+ */
 void
 gdk_query_visual_types (GdkVisualType **visual_types,
                         gint           *count)
@@ -350,10 +351,10 @@ gdk_visual_get_bits_per_rgb (GdkVisual *visual)
 
 /**
  * gdk_visual_get_red_pixel_details:
- * @visual: A #GdkVisual.
+ * @visual: A #GdkVisual
- * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL.
+ * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL
- * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL.
+ * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
- * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL.
+ * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
  *
  * Obtains values that are needed to calculate red pixel values in TrueColor
  * and DirectColor. The "mask" is the significant bits within the pixel.
@@ -384,9 +385,9 @@ gdk_visual_get_red_pixel_details (GdkVisual *visual,
 /**
  * gdk_visual_get_green_pixel_details:
  * @visual: a #GdkVisual
- * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL.
+ * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL
- * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL.
+ * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
- * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL.
+ * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
  *
  * Obtains values that are needed to calculate green pixel values in TrueColor
  * and DirectColor. The "mask" is the significant bits within the pixel.
@@ -417,9 +418,9 @@ gdk_visual_get_green_pixel_details (GdkVisual *visual,
 /**
  * gdk_visual_get_blue_pixel_details:
  * @visual: a #GdkVisual
- * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL.
+ * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL
- * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL.
+ * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
- * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL.
+ * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
  *
  * Obtains values that are needed to calculate blue pixel values in TrueColor
  * and DirectColor. The "mask" is the significant bits within the pixel.

gdk/gdkvisualprivate.h

@@ -34,6 +34,7 @@ struct _GdkVisual
 {
   GObject parent_instance;
 
+  /*< private >*/
   GdkVisualType type;
   gint depth;
   GdkByteOrder byte_order;

gdk/gdkwindow.c

@@ -10670,13 +10670,16 @@ gdk_window_register_dnd (GdkWindow *window)
  * gdk_drag_begin:
  * @window: the source window for this drag.
  * @targets: (transfer none) (element-type GdkAtom): the offered targets,
- *     as list of #GdkAtom<!-- -->s
+ *     as list of #GdkAtoms
  *
  * Starts a drag and creates a new drag context for it.
+ * This function assumes that the drag is controlled by the
+ * client pointer device, use gdk_drag_begin_for_device() to
+ * begin a drag with a different device.
  *
  * This function is called by the drag source.
  *
- * Return value: (transfer full): a newly created #GdkDragContext.
+ * Return value: (transfer full): a newly created #GdkDragContext
  */
 GdkDragContext *
 gdk_drag_begin (GdkWindow     *window,
@@ -10691,6 +10694,19 @@ gdk_drag_begin (GdkWindow     *window,
   return gdk_drag_begin_for_device (window, device, targets);
 }
 
+/**
+ * gdk_drag_begin_for_device:
+ * @window: the source window for this drag
+ * @device: the device that controls this drag
+ * @targets: (transfer none) (element-type GdkAtom): the offered targets,
+ *     as list of #GdkAtoms
+ *
+ * Starts a drag and creates a new drag context for it.
+ *
+ * This function is called by the drag source.
+ *
+ * Return value: (transfer full): a newly created #GdkDragContext
+ */
 GdkDragContext *
 gdk_drag_begin_for_device (GdkWindow     *window,
                            GdkDevice     *device,

gdk/x11/gdkmain-x11.c

@@ -48,6 +48,40 @@
 #include <X11/XKBlib.h>
 #endif
 
+/**
+ * SECTION:x_interaction
+ * @Short_description: X backend-specific functions
+ * @Title: X Window System Interaction
+ *
+ * The functions in this section are specific to the GDK X11 backend.
+ * To use them, you need to include the <literal>&lt;gdk/gdkx.h&gt;</literal>
+ * header and use the X11-specific pkg-config files to build your
+ * application (either <literal>gdk-x11-3.0</literal> or
+ * <literal>gtk+-x11-3.0</literal>).
+ *
+ * To make your code compile with other GDK backends, guard backend-specific
+ * calls by an ifdef as follows. Since GDK may be built with multiple
+ * backends, you should also check for the backend that is in use (e.g. by
+ * using the GDK_IS_X11_DISPLAY() macro).
+ * |[
+ * #ifdef GDK_WINDOWING_X11
+ *   if (GDK_IS_X11_DISPLAY (display))
+ *     {
+ *       /&ast; make X11-specific calls here &ast;/
+ *     }
+ *   else
+ * #endif
+ * #ifdef GDK_WINDOWING_QUARTZ
+ *   if (GDK_IS_QUARTZ_DISPLAY (display))
+ *     {
+ *       /&ast; make Quartz-specific calls here &ast/
+ *     }
+ *   else
+ * #endif
+ *   g_error ("Unsupported GDK backend");
+ * ]|
+ */
+
 typedef struct _GdkPredicate GdkPredicate;
 
 struct _GdkPredicate

gdk/x11/gdkx.h

@@ -32,27 +32,6 @@
 #include <X11/Xlib.h>
 #include <X11/Xutil.h>
 
-/**
- * SECTION:x_interaction
- * @Short_description: X backend-specific functions
- * @Title: X Window System Interaction
- *
- * The functions in this section are specific to the GDK X11 backend.
- * To use them, you need to include the <literal>&lt;gdk/gdkx.h&gt;</literal>
- * header and use the X11-specific pkg-config files to build your
- * application (either <literal>gdk-x11-3.0</literal> or
- * <literal>gtk+-x11-3.0</literal>).
- *
- * To make your code compile with other GDK backends, guard backend-specific
- * calls by an ifdef as follows:
- * <informalexample><programlisting>
- * #ifdef GDK_WINDOWING_X11
- *   /<!---->* X11-specific calls here... *<!---->/
- * #endif
- * </programlisting></informalexample>
- */
-
-
 #define __GDKX_H_INSIDE__
 
 #include <gdk/x11/gdkx11applaunchcontext.h>

gdk/x11/gdkx11screen.h

@@ -64,10 +64,10 @@ gint     gdk_x11_get_default_screen       (void);
 #endif
 
 /**
- * GDK_DISPLAY_XDISPLAY:
+ * GDK_SCREEN_XDISPLAY:
- * @display: a #GdkDisplay.
+ * @screen: a #GdkScreen
  *
- * Returns the display of a #GdkDisplay.
+ * Returns the display of a X11 #GdkScreen.
  *
  * Returns: an Xlib <type>Display*</type>
  */
@@ -77,9 +77,9 @@ gint     gdk_x11_get_default_screen       (void);
  * GDK_SCREEN_XSCREEN:
  * @screen: a #GdkScreen
  *
- * Returns the screen of a #GdkScreen.
+ * Returns the screen of a X11 #GdkScreen.
  *
- * Returns: an Xlib <type>Screen*</type>.
+ * Returns: an Xlib <type>Screen*</type>
  */
 #define GDK_SCREEN_XSCREEN(screen) (gdk_x11_screen_get_xscreen (screen))
 
@@ -87,14 +87,12 @@ gint     gdk_x11_get_default_screen       (void);
  * GDK_SCREEN_XNUMBER:
  * @screen: a #GdkScreen
  *
- * Returns the index of a #GdkScreen.
+ * Returns the index of a X11 #GdkScreen.
  *
- * Returns: the position of @screen among the screens of
+ * Returns: the position of @screen among the screens of its display
- *  its display.
  */
 #define GDK_SCREEN_XNUMBER(screen) (gdk_x11_screen_get_screen_number (screen))
 
-/* returns TRUE if we support the given WM spec feature */
 gboolean gdk_x11_screen_supports_net_wm_hint (GdkScreen *screen,
                                               GdkAtom    property);