[gtk+] Document WINDOWING macros

[Matthias Clasen <matthiasc src gnome org>]

commit 367211ed7f19f1f9fe3a658278e8c6083d86f1f6
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Dec 22 01:43:57 2010 -0500

    Document WINDOWING macros

 gdk/gdk.c |   67 +++++++++++++++++++++++++++++++++++++++++++++++++++----------
 1 files changed, 56 insertions(+), 11 deletions(-)
---
diff --git a/gdk/gdk.c b/gdk/gdk.c
index 6ab3caf..79f0b84 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -48,6 +48,51 @@
  * utility functions.
  */
 
+/**
+ * GDK_WINDOWING_X11:
+ *
+ * The #GDK_WINDOWING_X11 macro is defined if the X11 backend
+ * is supported.
+ *
+ * Use this macro to guard code that is specific to the X11-backend.
+ * Since GDK may be configured with multiple backends, an additional
+ * runtime check for the used backend is recommended:
+ * </para>
+ * <example>
+ * <title>Backend-specific code</title>
+ * <programlisting>
+ * #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");
+ * </programlisting>
+ * </example>
+ */
+
+/**
+ * GDK_WINDOWING_WIN32:
+ *
+ * The #GDK_WINDOWING_WIN32 macro is defined if the Win32 backend
+ * is supported.
+ */
+
+/**
+ * GDK_WINDOWING_QUARTZ:
+ *
+ * The #GDK_WINDOWING_QUARTZ macro is defined if the Quartz backend
+ * is supported.
+ */
 
 typedef struct _GdkPredicate  GdkPredicate;
 
@@ -323,14 +368,14 @@ gdk_display_open_default_libgtk_only (void)
  * @argc: (inout): the number of command line arguments.
  * @argv: (array length=argc) (inout): the array of command line arguments.
  *
- * Initializes the GDK library and connects to the X server, returning %TRUE on
- * success.
+ * Initializes the GDK library and connects to the windowing system,
+ * returning %TRUE on success.
  *
- * Any arguments used by GDK are removed from the array and @argc and @argv are
- * updated accordingly.
+ * Any arguments used by GDK are removed from the array and @argc and @argv
+ * are updated accordingly.
  *
- * GTK+ initializes GDK in gtk_init() and so this function is not usually needed
- * by GTK+ applications.
+ * GTK+ initializes GDK in gtk_init() and so this function is not usually
+ * needed by GTK+ applications.
  *
  * Returns: %TRUE if initialization succeeded.
  */
@@ -349,15 +394,15 @@ gdk_init_check (int    *argc,
  * @argc: (inout): the number of command line arguments.
  * @argv: (array length=argc) (inout): the array of command line arguments.
  *
- * Initializes the GDK library and connects to the X server.
+ * Initializes the GDK library and connects to the windowing system.
  * If initialization fails, a warning message is output and the application
  * terminates with a call to <literal>exit(1)</literal>.
  *
- * Any arguments used by GDK are removed from the array and @argc and @argv are
- * updated accordingly.
+ * Any arguments used by GDK are removed from the array and @argc and @argv
+ * are updated accordingly.
  *
- * GTK+ initializes GDK in gtk_init() and so this function is not usually needed
- * by GTK+ applications.
+ * GTK+ initializes GDK in gtk_init() and so this function is not usually
+ * needed by GTK+ applications.
  */
 void
 gdk_init (int *argc, char ***argv)