Fix up GDK docs

19 files changed, 410 insertions, 272 deletions

diff --git a/docs/reference/gdk/Makefile.am b/docs/reference/gdk/Makefile.am
index 136993caf5..f8441217c3 100644
--- a/docs/reference/gdk/Makefile.am
+++ b/docs/reference/gdk/Makefile.am
@@ -20,15 +20,15 @@ HFILE_GLOB=$(top_srcdir)/gdk/*.h $(top_srcdir)/gdk/x11/gdkx.h
 CFILE_GLOB=$(top_srcdir)/gdk/*.c
 
 # Header files to ignore when scanning
-IGNORE_HFILES=			\
+IGNORE_HFILES= 			\
 	gdkintl.h		\
 	gdkmarshalers.h		\
 	gdkkeysyms.h		\
 	gdkinternals.h		\
 	gdkprivate.h		\
-	gdkpoly-generic.h	\
+	gdk*private.h		\
 	keyname-table.h		\
-	win32 			\
+	win32			\
 	x11			\
 	quartz
 
@@ -38,10 +38,10 @@ EXTRA_HFILES=			\
 
 # CFLAGS and LDFLAGS for compiling scan program. Only needed
 # if $(DOC_MODULE).types is non-empty.
-INCLUDES = \
-	-I$(top_srcdir) 	\
-	-I$(top_builddir) 	\
-	-I$(top_builddir)/gdk 	\
+INCLUDES = 			\
+	-I$(top_srcdir)		\
+	-I$(top_builddir)	\
+	-I$(top_builddir)/gdk	\
 	$(GTK_DEBUG_FLAGS)	\
 	$(GDK_DEP_CFLAGS)
 
@@ -56,86 +56,85 @@ content_files = 		\
 	multihead.sgml
 
 # Images to copy into HTML directory
-HTML_IMAGES =				\
+HTML_IMAGES = 				\
 	images/rotated-text.png		\
-					\
-	images/X_cursor.png 		\
-	images/arrow.png 		\
-	images/based_arrow_down.png 	\
-	images/based_arrow_up.png 	\
-	images/boat.png 		\
-	images/bogosity.png 		\
-	images/bottom_left_corner.png 	\
-	images/bottom_right_corner.png 	\
-	images/bottom_side.png 		\
-	images/bottom_tee.png 		\
-	images/box_spiral.png 		\
-	images/center_ptr.png 		\
-	images/circle.png 		\
-	images/clock.png 		\
-	images/coffee_mug.png 		\
-	images/cross.png 		\
-	images/cross_reverse.png 	\
-	images/crosshair.png 		\
-	images/diamond_cross.png 	\
-	images/dot.png 			\
-	images/dotbox.png 		\
-	images/double_arrow.png 	\
-	images/draft_large.png 		\
-	images/draft_small.png 		\
-	images/draped_box.png 		\
-	images/exchange.png 		\
-	images/fleur.png 		\
-	images/gobbler.png 		\
-	images/gumby.png 		\
-	images/hand1.png 		\
-	images/hand2.png 		\
-	images/heart.png 		\
-	images/icon.png 		\
-	images/iron_cross.png 		\
-	images/left_ptr.png 		\
-	images/left_side.png 		\
-	images/left_tee.png 		\
-	images/leftbutton.png 		\
-	images/ll_angle.png 		\
-	images/lr_angle.png 		\
-	images/man.png 			\
-	images/middlebutton.png 	\
-	images/mouse.png 		\
-	images/pencil.png 		\
-	images/pirate.png 		\
-	images/plus.png 		\
-	images/question_arrow.png 	\
-	images/right_ptr.png 		\
-	images/right_side.png 		\
-	images/right_tee.png 		\
-	images/rightbutton.png 		\
-	images/rtl_logo.png 		\
-	images/sailboat.png 		\
-	images/sb_down_arrow.png 	\
-	images/sb_h_double_arrow.png 	\
-	images/sb_left_arrow.png 	\
-	images/sb_right_arrow.png 	\
-	images/sb_up_arrow.png 		\
-	images/sb_v_double_arrow.png 	\
-	images/shuttle.png 		\
-	images/sizing.png 		\
-	images/spider.png 		\
-	images/spraycan.png 		\
-	images/star.png 		\
-	images/target.png 		\
-	images/tcross.png 		\
-	images/top_left_arrow.png 	\
-	images/top_left_corner.png 	\
-	images/top_right_corner.png 	\
-	images/top_side.png 		\
-	images/top_tee.png 		\
-	images/trek.png 		\
-	images/ul_angle.png 		\
-	images/umbrella.png 		\
-	images/ur_angle.png 		\
-	images/watch.png 		\
-	images/xterm.png 
+	images/X_cursor.png		\
+	images/arrow.png		\
+	images/based_arrow_down.png	\
+	images/based_arrow_up.png	\
+	images/boat.png			\
+	images/bogosity.png		\
+	images/bottom_left_corner.png	\
+	images/bottom_right_corner.png	\
+	images/bottom_side.png		\
+	images/bottom_tee.png		\
+	images/box_spiral.png		\
+	images/center_ptr.png		\
+	images/circle.png		\
+	images/clock.png		\
+	images/coffee_mug.png		\
+	images/cross.png		\
+	images/cross_reverse.png	\
+	images/crosshair.png		\
+	images/diamond_cross.png	\
+	images/dot.png			\
+	images/dotbox.png		\
+	images/double_arrow.png		\
+	images/draft_large.png		\
+	images/draft_small.png		\
+	images/draped_box.png		\
+	images/exchange.png		\
+	images/fleur.png		\
+	images/gobbler.png		\
+	images/gumby.png		\
+	images/hand1.png		\
+	images/hand2.png		\
+	images/heart.png		\
+	images/icon.png			\
+	images/iron_cross.png		\
+	images/left_ptr.png		\
+	images/left_side.png		\
+	images/left_tee.png		\
+	images/leftbutton.png		\
+	images/ll_angle.png		\
+	images/lr_angle.png		\
+	images/man.png			\
+	images/middlebutton.png		\
+	images/mouse.png		\
+	images/pencil.png		\
+	images/pirate.png		\
+	images/plus.png			\
+	images/question_arrow.png	\
+	images/right_ptr.png		\
+	images/right_side.png		\
+	images/right_tee.png		\
+	images/rightbutton.png		\
+	images/rtl_logo.png		\
+	images/sailboat.png		\
+	images/sb_down_arrow.png	\
+	images/sb_h_double_arrow.png	\
+	images/sb_left_arrow.png	\
+	images/sb_right_arrow.png	\
+	images/sb_up_arrow.png		\
+	images/sb_v_double_arrow.png	\
+	images/shuttle.png		\
+	images/sizing.png		\
+	images/spider.png		\
+	images/spraycan.png		\
+	images/star.png			\
+	images/target.png		\
+	images/tcross.png		\
+	images/top_left_arrow.png	\
+	images/top_left_corner.png	\
+	images/top_right_corner.png	\
+	images/top_side.png		\
+	images/top_tee.png		\
+	images/trek.png			\
+	images/ul_angle.png		\
+	images/umbrella.png		\
+	images/ur_angle.png		\
+	images/watch.png		\
+	images/xterm.png
 
 # Extra options to supply to gtkdoc-fixref
 FIXXREF_OPTIONS= \
diff --git a/docs/reference/gdk/gdk-docs.sgml b/docs/reference/gdk/gdk-docs.sgml
index ed18e2fbbd..7be666074f 100644
--- a/docs/reference/gdk/gdk-docs.sgml
+++ b/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" />
diff --git a/docs/reference/gdk/gdk3-sections.txt b/docs/reference/gdk/gdk3-sections.txt
index ef3400d04f..6aa124debf 100644
--- a/docs/reference/gdk/gdk3-sections.txt
+++ b/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>
-<FILE>gdkdevicemanager</FILE>
-GdkDeviceManager
+<TITLE>GdkDevice</TITLE>
+<FILE>gdkdevice</FILE>
 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,14 +728,34 @@ 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>
 GdkEventType
@@ -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>
diff --git a/docs/reference/gdk/gdk3.types b/docs/reference/gdk/gdk3.types
index bb8607d4f8..abf4374715 100644
--- a/docs/reference/gdk/gdk3.types
+++ b/docs/reference/gdk/gdk3.types
@@ -1,9 +1,13 @@
 #include <gdk/gdk.h>
 
+gdk_app_launch_context_get_type
+gdk_cursor_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_keymap_get_type
-gdk_device_get_type
-gdk_device_manager_get_type
diff --git a/gdk/gdk.c b/gdk/gdk.c
index 1667226ff5..e7c7a0c49d 100644
--- a/gdk/gdk.c
+++ b/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)
 {
diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index 54cb7fac6e..714c8cd123 100644
--- a/gdk/gdkdevice.c
+++ b/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
diff --git a/gdk/gdkdevicemanager.c b/gdk/gdkdevicemanager.c
index ab546516d9..33fd1082ba 100644
--- a/gdk/gdkdevicemanager.c
+++ b/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
- * 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
+ * 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.
+ *
+ * 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)
- * 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.
+ * 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().
+ * 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.
+ * 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
+ * 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.
+ * 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.
+ * although gdk_window_set_support_multidevice() has to be called on
+ * #GdkWindows 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.
+ * 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.
+ * 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().
+ * 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. 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.
+ * 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. 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,
diff --git a/gdk/gdkdevicemanagerprivate.h b/gdk/gdkdevicemanagerprivate.h
index 543f7a99ab..df5a046961 100644
--- a/gdk/gdkdevicemanagerprivate.h
+++ b/gdk/gdkdevicemanagerprivate.h
@@ -36,6 +36,7 @@ struct _GdkDeviceManager
 {
   GObject parent_instance;
 
+  /*< private >*/
   GdkDisplay *display;
 };
 
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index 8941d38a17..a3dd068674 100644
--- a/gdk/gdkdisplay.c
+++ b/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
- *               could not be opened.
+ * Return value: (transfer none): a #GdkDisplay, or %NULL
+ *     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
- *              process should be completed
+ * @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.
+ * 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.
+ * 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: 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)
diff --git a/gdk/gdkdisplay.h b/gdk/gdkdisplay.h
index 4307bd9524..bda19c2b77 100644
--- a/gdk/gdkdisplay.h
+++ b/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);
 
diff --git a/gdk/gdkdisplaymanager.c b/gdk/gdkdisplaymanager.c
index cfd48475e4..9903490bdb 100644
--- a/gdk/gdkdisplaymanager.c
+++ b/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)
diff --git a/gdk/gdkdndprivate.h b/gdk/gdkdndprivate.h
index 618f0cc075..f1124304a6 100644
--- a/gdk/gdkdndprivate.h
+++ b/gdk/gdkdndprivate.h
@@ -69,6 +69,7 @@ struct _GdkDragContextClass {
 struct _GdkDragContext {
   GObject parent_instance;
 
+  /*< private >*/
   GdkDragProtocol protocol;
 
   gboolean is_source;
diff --git a/gdk/gdkmain.h b/gdk/gdkmain.h
index 963654236b..bcbe4d07dc 100644
--- a/gdk/gdkmain.h
+++ b/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;
diff --git a/gdk/gdkvisual.c b/gdk/gdkvisual.c
index 35d98eade3..c1b0160f2e 100644
--- a/gdk/gdkvisual.c
+++ b/gdk/gdkvisual.c
@@ -1,7 +1,7 @@
 /* GDK - The GIMP Drawing Kit
  * gdkvisual.c
- * 
- * Copyright 2001 Sun Microsystems Inc. 
+ *
+ * Copyright 2001 Sun Microsystems Inc.
  *
  * Erwann Chenede <erwann.chenede@sun.com>
  *
@@ -32,25 +32,26 @@
  * @Short_description: Low-level display hardware information
  * @Title: Visuals
  *
- * A #GdkVisual describes a particular video hardware display format. It includes
- * information about the number of bits used for each color, the way the bits are
- * translated into an RGB value for display, and the way the bits are stored in
- * memory. For example, a piece of display hardware might support 24-bit color,
- * 16-bit color, or 8-bit color; meaning 24/16/8-bit pixel sizes. For a given
- * pixel size, pixels can be in different formats; for example the "red" element
- * of an RGB pixel may be in the top 8 bits of the pixel, or may be in the lower
- * 4 bits.
+ * A #GdkVisual describes a particular video hardware display format.
+ * It includes information about the number of bits used for each color,
+ * the way the bits are translated into an RGB value for display, and
+ * the way the bits are stored in memory. For example, a piece of display
+ * hardware might support 24-bit color, 16-bit color, or 8-bit color;
+ * meaning 24/16/8-bit pixel sizes. For a given pixel size, pixels can
+ * be in different formats; for example the "red" element of an RGB pixel
+ * 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.
- * For the purposes of making this determination, higher bit depths are considered
- * better, and for visuals of the same bit depth, %GDK_VISUAL_PSEUDO_COLOR is
- * preferred at 8bpp, otherwise, the visual types are ranked in the order of
- * (highest to lowest) %GDK_VISUAL_DIRECT_COLOR, %GDK_VISUAL_TRUE_COLOR,
- * %GDK_VISUAL_PSEUDO_COLOR, %GDK_VISUAL_STATIC_COLOR, %GDK_VISUAL_GRAYSCALE,
- * then %GDK_VISUAL_STATIC_GRAY.
+ * A number of functions are provided for determining the "best" available
+ * visual. For the purposes of making this determination, higher bit depths
+ * are considered better, and for visuals of the same bit depth,
+ * %GDK_VISUAL_PSEUDO_COLOR is preferred at 8bpp, otherwise, the visual
+ * types are ranked in the order of(highest to lowest)
+ * %GDK_VISUAL_DIRECT_COLOR, %GDK_VISUAL_TRUE_COLOR,
+ * %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)
@@ -76,7 +77,7 @@ gdk_visual_class_init (GdkVisualClass *visual_class)
 
 /**
  * gdk_list_visuals:
- * 
+ *
  * Lists the available visuals for the default screen.
  * (See gdk_screen_list_visuals())
  * A visual describes a hardware image data format.
@@ -84,10 +85,10 @@ gdk_visual_class_init (GdkVisualClass *visual_class)
  * and might expect pixels to be in a certain format.
  *
  * Call g_list_free() on the return value when you're finished with it.
- * 
+ *
  * 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)
 {
@@ -96,13 +97,13 @@ gdk_list_visuals (void)
 
 /**
  * gdk_visual_get_system:
- * 
+ *
  * Get the system's default visual for the default GDK screen.
  * This is the visual for the root window of the display.
  * 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
- * be freed. %NULL may be returned if no visual supports @depth.
+ * over grayscale or fixed-colormap visuals. The return value should
+ * 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,14 +187,14 @@ 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)
 {
   GdkScreen *screen = gdk_screen_get_default();
 
   return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_with_type (screen,
-								  visual_type);
+                                                                  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,11 +228,10 @@ 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)
+gdk_query_depths (gint **depths,
+                  gint  *count)
 {
   GdkScreen *screen = gdk_screen_get_default();
 
@@ -248,10 +249,10 @@ 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)
+                        gint           *count)
 {
   GdkScreen *screen = gdk_screen_get_default();
 
@@ -350,15 +351,15 @@ gdk_visual_get_bits_per_rgb (GdkVisual *visual)
 
 /**
  * gdk_visual_get_red_pixel_details:
- * @visual: A #GdkVisual.
- * @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.
- * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL.
+ * @visual: A #GdkVisual
+ * @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
+ * @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.
+ * and DirectColor. The "mask" is the significant bits within the pixel.
  * The "shift" is the number of bits left we must shift a primary for it
- * to be in position (according to the "mask").  Finally, "precision" refers
+ * to be in position (according to the "mask"). Finally, "precision" refers
  * to how much precision the pixel value contains for a particular primary.
  *
  * Since: 2.22
@@ -384,14 +385,14 @@ 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.
- * @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.
+ * @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
+ * @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.
+ * and DirectColor. The "mask" is the significant bits within the pixel.
  * The "shift" is the number of bits left we must shift a primary for it
- * to be in position (according to the "mask").  Finally, "precision" refers
+ * to be in position (according to the "mask"). Finally, "precision" refers
  * to how much precision the pixel value contains for a particular primary.
  *
  * Since: 2.22
@@ -417,14 +418,14 @@ 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.
- * @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.
+ * @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
+ * @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.
+ * and DirectColor. The "mask" is the significant bits within the pixel.
  * The "shift" is the number of bits left we must shift a primary for it
- * to be in position (according to the "mask").  Finally, "precision" refers
+ * to be in position (according to the "mask"). Finally, "precision" refers
  * to how much precision the pixel value contains for a particular primary.
  *
  * Since: 2.22
diff --git a/gdk/gdkvisualprivate.h b/gdk/gdkvisualprivate.h
index 8099ec2663..075916a6f2 100644
--- a/gdk/gdkvisualprivate.h
+++ b/gdk/gdkvisualprivate.h
@@ -34,6 +34,7 @@ struct _GdkVisual
 {
   GObject parent_instance;
 
+  /*< private >*/
   GdkVisualType type;
   gint depth;
   GdkByteOrder byte_order;
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 699d5dc3bd..e771820919 100644
--- a/gdk/gdkwindow.c
+++ b/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,
diff --git a/gdk/x11/gdkmain-x11.c b/gdk/x11/gdkmain-x11.c
index 1e9b818198..0f2fd9636a 100644
--- a/gdk/x11/gdkmain-x11.c
+++ b/gdk/x11/gdkmain-x11.c
@@ -48,7 +48,41 @@
 #include <X11/XKBlib.h>
 #endif
 
-typedef struct _GdkPredicate        GdkPredicate;
+/**
+ * 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
 {
diff --git a/gdk/x11/gdkx.h b/gdk/x11/gdkx.h
index baed243708..48207b585d 100644
--- a/gdk/x11/gdkx.h
+++ b/gdk/x11/gdkx.h
@@ -21,7 +21,7 @@
  * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
  * file for a list of people on the GTK+ Team.  See the ChangeLog
  * files for a list of changes.  These files are distributed with
- * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
+ * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  */
 
 #ifndef __GDK_X_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>
diff --git a/gdk/x11/gdkx11screen.h b/gdk/x11/gdkx11screen.h
index 3404e92af1..cb709a30e0 100644
--- a/gdk/x11/gdkx11screen.h
+++ b/gdk/x11/gdkx11screen.h
@@ -64,37 +64,35 @@ gint     gdk_x11_get_default_screen       (void);
 #endif
 
 /**
- * GDK_DISPLAY_XDISPLAY:
- * @display: a #GdkDisplay.
+ * GDK_SCREEN_XDISPLAY:
+ * @screen: a #GdkScreen
  *
- * Returns the display of a #GdkDisplay.
+ * Returns the display of a X11 #GdkScreen.
  *
  * Returns: an Xlib <type>Display*</type>
  */
-#define GDK_SCREEN_XDISPLAY(screen)   (gdk_x11_display_get_xdisplay (gdk_screen_get_display (screen)))
+#define GDK_SCREEN_XDISPLAY(screen) (gdk_x11_display_get_xdisplay (gdk_screen_get_display (screen)))
 
 /**
  * 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))
+#define GDK_SCREEN_XSCREEN(screen) (gdk_x11_screen_get_xscreen (screen))
 
 /**
  * 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
- *  its display.
+ * Returns: the position of @screen among the screens of its display
  */
-#define GDK_SCREEN_XNUMBER(screen)    (gdk_x11_screen_get_screen_number (screen))
+#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);