Documentation updates. Updates.

* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c: Documentation updates.
        * gtk/tmpl/gtkdnd.sgml, gtk/tmpl/gtkclipboard.sgml,
        gdk/tmpl/general.sgml, gdk/tmpl/threads.sgml,
        gdk/tmpl/x_interaction.sgml: Updates.

docs/reference/gdk/tmpl/general.sgml

@@ -369,21 +369,21 @@ Removes the X error trap installed with gdk_error_trap_push().
 
 <!-- ##### MACRO GDK_WINDOWING_X11 ##### -->
 <para>
-
+This macro is defined if GDK is configured to use the X backend.
 </para>
 
 
 
 <!-- ##### MACRO GDK_WINDOWING_WIN32 ##### -->
 <para>
-
+This macro is defined if GDK is configured to use the Win32 backend.
 </para>
 
 
 
 <!-- ##### MACRO GDK_WINDOWING_FB ##### -->
 <para>
-
+This macro is defined if GDK is configured to use the Linux framebuffer backend.
 </para>
 
 

docs/reference/gdk/tmpl/threads.sgml

@@ -2,11 +2,33 @@
 Threads
 
 <!-- ##### SECTION Short_Description ##### -->
-
+functions for using GDK in multi-threaded programs
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+For thread safety, GDK relies on the thread primitives in GLib, 
+and on the thread-safe GLib main loop.
+</para>
+<para>
+You must call g_thread_init() before executing any other GTK+ or GDK 
+functions in a threaded GTK+ program.
+</para>
+<para>
+Idles, timeouts, and input functions are executed outside
+of the main GTK+ lock. So, if you need to call GTK+
+inside of such a callback, you must surround the callback
+with a gdk_threads_enter()/gdk_threads_leave() pair.
+(However, signals are still executed within the main
+GTK+ lock.)
+</para>
+<para>
+In particular, this means, if you are writing widgets that might 
+be used in threaded programs, you <emphasis>must</emphasis> surround 
+timeouts and idle functions in this matter.
+</para>
+<para>
+As always, you must also surround any calls to GTK+ not made within 
+a signal handler with a gdk_threads_enter()/gdk_threads_leave() pair.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,35 +38,40 @@ Threads
 
 <!-- ##### MACRO GDK_THREADS_ENTER ##### -->
 <para>
-
+This macro marks the begin of a critical section
+in which GDK and GTK+ functions can be called.
+Only one thread at a time can be in such a critial 
+section.
 </para>
 
 
 
 <!-- ##### MACRO GDK_THREADS_LEAVE ##### -->
 <para>
-
+This macro marks the end of a critical section 
+begun with #GDK_THREADS_ENTER.
 </para>
 
 
 
 <!-- ##### FUNCTION gdk_threads_enter ##### -->
 <para>
-
+Enters a critical region like #GDK_THREADS_ENTER.
 </para>
 
 
 
 <!-- ##### FUNCTION gdk_threads_leave ##### -->
 <para>
-
+Leaves a critical region begun with gdk_threads_enter(). 
 </para>
 
 
 
 <!-- ##### VARIABLE gdk_threads_mutex ##### -->
 <para>
-
+The #GMutex used to implement the critical region for
+gdk_threads_enter()/gdk_threads_leave().
 </para>
 
 

docs/reference/gdk/tmpl/x_interaction.sgml

@@ -382,28 +382,29 @@ Returns the X font belonging to a #GdkFont.
 
 <!-- ##### FUNCTION gdk_x11_gc_get_xdisplay ##### -->
 <para>
-
+Returns the display of a #GdkGC.
 </para>
 
-@gc: 
-@Returns: 
+@gc: a #GdkGC. 
+@Returns: an Xlib <type>Display*</type>.
 
 
 <!-- ##### FUNCTION gdk_x11_gc_get_xgc ##### -->
 <para>
-
+Returns the X GC of a #GdkGC.
 </para>
 
-@gc: 
-@Returns: 
+@gc: a #GdkGC.
+@Returns: an Xlib <type>GC</type>.
 
 
 <!-- ##### FUNCTION gdk_x11_get_default_root_xwindow ##### -->
 <para>
-
+Gets the root window of the default screen 
+(see gdk_x11_get_default_screen()).  
 </para>
 
-@Returns: 
+@Returns: an Xlib <type>Window</type>.
 
 
 <!-- ##### FUNCTION gdk_x11_get_default_screen ##### -->
@@ -416,10 +417,12 @@ Returns the X font belonging to a #GdkFont.
 
 <!-- ##### FUNCTION gdk_x11_get_default_xdisplay ##### -->
 <para>
-
+Gets the default GTK+ display.
 </para>
 
-@Returns: 
+@Returns: the Xlib <type>Display*</type> for the display
+  specified in the <option>--display</option> command line option 
+  or the <envar>DISPLAY</envar> environment variable.
 
 
 <!-- ##### FUNCTION gdk_x11_grab_server ##### -->
@@ -434,11 +437,11 @@ gdk_x11_grab_server()/gdk_x11_ungrab_server() calls can be nested.
 
 <!-- ##### FUNCTION gdk_x11_image_get_xdisplay ##### -->
 <para>
-
+Returns the display of a #GdkImage.
 </para>
 
-@image: 
-@Returns: 
+@drawable: a #GdkImage.
+@Returns: an Xlib <type>Display*</type>.
 
 
 <!-- ##### FUNCTION gdk_x11_image_get_ximage ##### -->