From 1cbba3fae2592fe043f040a79b12a38d6cc3b93c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Javier=20Jard=C3=B3n?= <jjardon@gnome.org>
Date: Mon, 15 Nov 2010 20:01:05 +0100
Subject: [PATCH] docs: Move documentation to inline comments: x_interaction

---
 docs/reference/gdk/tmpl/.gitignore         |   1 +
 docs/reference/gdk/tmpl/x_interaction.sgml | 555 ---------------------
 gdk/x11/gdkx.h                             | 120 +++++
 3 files changed, 121 insertions(+), 555 deletions(-)
 delete mode 100644 docs/reference/gdk/tmpl/x_interaction.sgml

diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore
index 3823d757ea..cca0643a7f 100644
--- a/docs/reference/gdk/tmpl/.gitignore
+++ b/docs/reference/gdk/tmpl/.gitignore
@@ -19,3 +19,4 @@ selections.sgml
 threads.sgml
 visuals.sgml
 windows.sgml
+x_interaction.sgml
diff --git a/docs/reference/gdk/tmpl/x_interaction.sgml b/docs/reference/gdk/tmpl/x_interaction.sgml
deleted file mode 100644
index 7dc336e5a6..0000000000
--- a/docs/reference/gdk/tmpl/x_interaction.sgml
+++ /dev/null
@@ -1,555 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-X Window System Interaction
-
-<!-- ##### SECTION Short_Description ##### -->
-X backend-specific functions
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-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>
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### MACRO GDK_ROOT_WINDOW ##### -->
-<para>
-Obtains the Xlib window id of the root window of the current screen. 
-</para>
-
-
-
-<!-- ##### MACRO GDK_WINDOW_XDISPLAY ##### -->
-<para>
-Returns the display of a #GdkWindow.
-</para>
-
-@win: a #GdkWindow.
-@Returns: an Xlib <type>Display*</type>.
-
-
-<!-- ##### MACRO GDK_WINDOW_XID ##### -->
-<para>
-Returns the X window belonging to a #GdkWindow.
-</para>
-
-@win: a #GdkWindow.
-@Returns: the Xlib <type>Window</type> of @win.
-
-
-<!-- ##### MACRO GDK_DISPLAY_XDISPLAY ##### -->
-<para>
-Returns the display of a #GdkDisplay.
-</para>
-
-@display: a #GdkDisplay.
-
-
-<!-- ##### MACRO GDK_DRAWABLE_XDISPLAY ##### -->
-<para>
-Returns the display of a #GdkDrawable.
-</para>
-
-@win: a #GdkDrawable.
-@Returns: an Xlib <type>Display*</type>.
-
-
-<!-- ##### MACRO GDK_DRAWABLE_XID ##### -->
-<para>
-Returns the X resource (window or pixmap) belonging to a #GdkDrawable.
-</para>
-
-@win: a #GdkDrawable.
-@Returns: the ID of @win's X resource.
-
-
-<!-- ##### MACRO GDK_SCREEN_XDISPLAY ##### -->
-<para>
-Returns the display of a #GdkScreen.
-</para>
-
-@screen: a #GdkScreen.
-@Returns: an Xlib <type>Display*</type>.
-
-
-<!-- ##### MACRO GDK_SCREEN_XNUMBER ##### -->
-<para>
-Returns the index of a #GdkScreen.
-</para>
-
-@screen: a #GdkScreen
-@Returns: the position of @screen among the screens of
-  its display.
-
-
-<!-- ##### MACRO GDK_SCREEN_XSCREEN ##### -->
-<para>
-Returns the screen of a #GdkScreen.
-</para>
-
-@screen: a #GdkScreen
-@Returns: an Xlib <type>Screen*</type>.
-
-
-<!-- ##### MACRO GDK_CURSOR_XCURSOR ##### -->
-<para>
-Returns the X cursor belonging to a #GdkCursor.
-</para>
-
-@cursor: a #GdkCursor.
-@Returns: an Xlib <type>Cursor</type>.
-
-
-<!-- ##### MACRO GDK_CURSOR_XDISPLAY ##### -->
-<para>
-Returns the display of a #GdkCursor.
-</para>
-
-@cursor: a #GdkCursor.
-@Returns: an Xlib <type>Display*</type>.
-
-
-<!-- ##### MACRO GDK_WINDOW_XWINDOW ##### -->
-<para>
-Another name for GDK_DRAWABLE_XID(). 
-</para>
-
-
-
-<!-- ##### FUNCTION gdkx_visual_get ##### -->
-<para>
-
-</para>
-
-@xvisualid: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_window_foreign_new ##### -->
-<para>
-
-</para>
-
-@anid: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_window_foreign_new_for_display ##### -->
-<para>
-
-</para>
-
-@display: 
-@anid: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_xid_table_lookup ##### -->
-<para>
-
-</para>
-
-@xid: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_xid_table_lookup_for_display ##### -->
-<para>
-
-</para>
-
-@display: 
-@xid: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_window_lookup ##### -->
-<para>
-</para>
-
-@anid: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_window_lookup_for_display ##### -->
-<para>
-
-</para>
-
-@display: 
-@anid: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_lookup_xdisplay ##### -->
-<para>
-
-</para>
-
-@xdisplay: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_get_server_time ##### -->
-<para>
-
-</para>
-
-@window: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_net_wm_supports ##### -->
-<para>
-
-</para>
-
-@property: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_screen_supports_net_wm_hint ##### -->
-<para>
-
-</para>
-
-@screen: 
-@property: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_screen_get_window_manager_name ##### -->
-<para>
-
-</para>
-
-@screen: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_screen_get_monitor_output ##### -->
-<para>
-
-</para>
-
-@screen: 
-@monitor_num: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_screen_lookup_visual ##### -->
-<para>
-
-</para>
-
-@screen: 
-@xvisualid: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_window_set_user_time ##### -->
-<para>
-
-</para>
-
-@window: 
-@timestamp: 
-
-
-<!-- ##### FUNCTION gdk_x11_window_move_to_current_desktop ##### -->
-<para>
-
-</para>
-
-@window: 
-
-
-<!-- ##### FUNCTION gdk_x11_display_get_user_time ##### -->
-<para>
-
-</para>
-
-@display: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_cursor_get_xcursor ##### -->
-<para>
-
-</para>
-
-@cursor: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_cursor_get_xdisplay ##### -->
-<para>
-
-</para>
-
-@cursor: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_display_broadcast_startup_message ##### -->
-<para>
-
-</para>
-
-@display: 
-@message_type: 
-@Varargs: 
-
-
-<!-- ##### FUNCTION gdk_x11_display_get_startup_notification_id ##### -->
-<para>
-
-</para>
-
-@display: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_display_get_xdisplay ##### -->
-<para>
-
-</para>
-
-@display: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_display_grab ##### -->
-<para>
-
-</para>
-
-@display: 
-
-
-<!-- ##### FUNCTION gdk_x11_display_ungrab ##### -->
-<para>
-
-</para>
-
-@display: 
-
-
-<!-- ##### FUNCTION gdk_x11_display_error_trap_push ##### -->
-<para>
-
-</para>
-
-@display: 
-
-
-<!-- ##### FUNCTION gdk_x11_display_error_trap_pop_ignored ##### -->
-<para>
-
-</para>
-
-@display: 
-
-
-<!-- ##### FUNCTION gdk_x11_display_set_cursor_theme ##### -->
-<para>
-
-</para>
-
-@display: 
-@theme: 
-@size: 
-
-
-<!-- ##### FUNCTION gdk_x11_register_standard_event_type ##### -->
-<para>
-
-</para>
-
-@display: 
-@event_base: 
-@n_events: 
-
-
-<!-- ##### FUNCTION gdk_x11_drawable_get_xdisplay ##### -->
-<para>
-
-</para>
-
-@drawable: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_drawable_get_xid ##### -->
-<para>
-
-</para>
-
-@drawable: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_get_default_root_xwindow ##### -->
-<para>
-
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_get_default_screen ##### -->
-<para>
-
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_get_default_xdisplay ##### -->
-<para>
-
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_grab_server ##### -->
-<para>
-
-</para>
-
-@void: 
-
-
-<!-- ##### FUNCTION gdk_x11_screen_get_screen_number ##### -->
-<para>
-
-</para>
-
-@screen: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_screen_get_xscreen ##### -->
-<para>
-
-</para>
-
-@screen: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_ungrab_server ##### -->
-<para>
-
-</para>
-
-@void: 
-
-
-<!-- ##### FUNCTION gdk_x11_visual_get_xvisual ##### -->
-<para>
-
-</para>
-
-@visual: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_atom_to_xatom ##### -->
-<para>
-
-</para>
-
-@atom: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_atom_to_xatom_for_display ##### -->
-<para>
-
-</para>
-
-@display: 
-@atom: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_xatom_to_atom ##### -->
-<para>
-
-</para>
-
-@xatom: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_xatom_to_atom_for_display ##### -->
-<para>
-
-</para>
-
-@display: 
-@xatom: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_get_xatom_by_name ##### -->
-<para>
-
-</para>
-
-@atom_name: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_get_xatom_by_name_for_display ##### -->
-<para>
-
-</para>
-
-@display: 
-@atom_name: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_get_xatom_name ##### -->
-<para>
-
-</para>
-
-@xatom: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_x11_get_xatom_name_for_display ##### -->
-<para>
-
-</para>
-
-@display: 
-@xatom: 
-@Returns: 
-
-
diff --git a/gdk/x11/gdkx.h b/gdk/x11/gdkx.h
index 8b7a3959bd..7fc0227348 100644
--- a/gdk/x11/gdkx.h
+++ b/gdk/x11/gdkx.h
@@ -33,6 +33,28 @@
 
 G_BEGIN_DECLS
 
+
+/**
+ * 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>
+ */
+
+
 Display *gdk_x11_drawable_get_xdisplay    (GdkDrawable *drawable);
 XID      gdk_x11_drawable_get_xid         (GdkDrawable *drawable);
 GdkDrawable *gdk_x11_window_get_drawable_impl (GdkWindow *window);
@@ -54,21 +76,89 @@ Display *gdk_x11_get_default_xdisplay     (void);
 gint     gdk_x11_get_default_screen       (void);
 #endif
 
+/**
+ * GDK_CURSOR_XDISPLAY:
+ * @cursor: a #GdkCursor.
+ *
+ * Returns the display of a #GdkCursor.
+ *
+ * Returns: an Xlib <type>Display*</type>.
+ */
 #define GDK_CURSOR_XDISPLAY(cursor)   (gdk_x11_cursor_get_xdisplay (cursor))
+
+/**
+ * GDK_CURSOR_XCURSOR:
+ * @cursor: a #GdkCursor.
+ *
+ * Returns the X cursor belonging to a #GdkCursor.
+ *
+ * Returns: an Xlib <type>Cursor</type>.
+ */
 #define GDK_CURSOR_XCURSOR(cursor)    (gdk_x11_cursor_get_xcursor (cursor))
 
+
 #ifdef GDK_COMPILATION
 
 #include "gdkprivate-x11.h"
 #include "gdkscreen-x11.h"
 
+/**
+ * GDK_DISPLAY_XDISPLAY:
+ * @display: a #GdkDisplay.
+ *
+ * Returns the display of a #GdkDisplay.
+ */
 #define GDK_DISPLAY_XDISPLAY(display) (GDK_DISPLAY_X11(display)->xdisplay)
 
+/**
+ * GDK_WINDOW_XDISPLAY:
+ * @win: a #GdkWindow.
+ *
+ * Returns the display of a #GdkWindow.
+ *
+ * Returns: an Xlib <type>Display*</type>.
+ */
 #define GDK_WINDOW_XDISPLAY(win)      (GDK_SCREEN_X11 (GDK_WINDOW_SCREEN (win))->xdisplay)
 #define GDK_WINDOW_XID(win)           (GDK_DRAWABLE_IMPL_X11(((GdkWindowObject *)win)->impl)->xid)
+
+/**
+ * GDK_DRAWABLE_XDISPLAY:
+ * @win: a #GdkDrawable.
+ *
+ * Returns the display of a #GdkDrawable.
+ *
+ * Returns: an Xlib <type>Display*</type>.
+ */
 #define GDK_DRAWABLE_XDISPLAY(win)    (GDK_WINDOW_XDISPLAY (win))
+
+/**
+ * GDK_DRAWABLE_XID:
+ * @win: a #GdkDrawable.
+ *
+ * Returns the X resource (window or pixmap) belonging to a #GdkDrawable.
+ *
+ * Returns: the ID of @win's X resource.
+ */
 #define GDK_DRAWABLE_XID(win)         (GDK_WINDOW_XID (win))
+
+/**
+ * GDK_SCREEN_XDISPLAY:
+ * @screen: a #GdkScreen.
+ *
+ * Returns the display of a #GdkScreen.
+ *
+ * Returns: an Xlib <type>Display*</type>.
+ */
 #define GDK_SCREEN_XDISPLAY(screen)   (GDK_SCREEN_X11 (screen)->xdisplay)
+
+/**
+ * GDK_SCREEN_XSCREEN:
+ * @screen: a #GdkScreen
+ *
+ * Returns the screen of a #GdkScreen.
+ *
+ * Returns: an Xlib <type>Screen*</type>.
+ */
 #define GDK_SCREEN_XSCREEN(screen)    (GDK_SCREEN_X11 (screen)->xscreen)
 #define GDK_SCREEN_XNUMBER(screen)    (GDK_SCREEN_X11 (screen)->screen_num) 
 #define GDK_WINDOW_XWINDOW	      GDK_DRAWABLE_XID
@@ -76,18 +166,48 @@ gint     gdk_x11_get_default_screen       (void);
 #else /* GDK_COMPILATION */
 
 #ifndef GDK_MULTIHEAD_SAFE
+/**
+ * GDK_ROOT_WINDOW:
+ *
+ * Obtains the Xlib window id of the root window of the current screen.
+ */
 #define GDK_ROOT_WINDOW()             (gdk_x11_get_default_root_xwindow ())
 #endif
 
 #define GDK_DISPLAY_XDISPLAY(display) (gdk_x11_display_get_xdisplay (display))
 
 #define GDK_WINDOW_XDISPLAY(win)      (gdk_x11_drawable_get_xdisplay (gdk_x11_window_get_drawable_impl (win)))
+
+/**
+ * GDK_WINDOW_XID:
+ * @win: a #GdkWindow.
+ *
+ * Returns the X window belonging to a #GdkWindow.
+ *
+ * Returns: the Xlib <type>Window</type> of @win.
+ */
 #define GDK_WINDOW_XID(win)           (gdk_x11_drawable_get_xid (win))
+
+/**
+ * GDK_WINDOW_XWINDOW:
+ *
+ * Another name for GDK_DRAWABLE_XID().
+ */
 #define GDK_WINDOW_XWINDOW(win)       (gdk_x11_drawable_get_xid (win))
 #define GDK_DRAWABLE_XDISPLAY(win)    (gdk_x11_drawable_get_xdisplay (win))
 #define GDK_DRAWABLE_XID(win)         (gdk_x11_drawable_get_xid (win))
 #define GDK_SCREEN_XDISPLAY(screen)   (gdk_x11_display_get_xdisplay (gdk_screen_get_display (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 position of @screen among the screens of
+ *  its display.
+ */
 #define GDK_SCREEN_XNUMBER(screen)    (gdk_x11_screen_get_screen_number (screen))
 
 #endif /* GDK_COMPILATION */