Gdk API doc updates.

13 files changed, 200 insertions, 2 deletions

diff --git a/gdk/x11/gdkcolor-x11.c b/gdk/x11/gdkcolor-x11.c
index d46692719..fe543021b 100644
--- a/gdk/x11/gdkcolor-x11.c
+++ b/gdk/x11/gdkcolor-x11.c
@@ -1344,6 +1344,14 @@ gdk_colormap_equal (Colormap *a,
   return (*a == *b);
 }
 
+/**
+ * gdk_x11_colormap_get_xdisplay:
+ * @colormap: a #GdkColormap.
+ * 
+ * Returns the display of a #GdkColormap.
+ * 
+ * Return value: an Xlib <type>Display*</type>.
+ **/
 Display *
 gdk_x11_colormap_get_xdisplay (GdkColormap *colormap)
 {
@@ -1356,6 +1364,14 @@ gdk_x11_colormap_get_xdisplay (GdkColormap *colormap)
   return private->xdisplay;
 }
 
+/**
+ * gdk_x11_colormap_get_xcolormap:
+ * @colormap:  a #GdkColormap.
+ * 
+ * Returns the X colormap belonging to a #GdkColormap.
+ * 
+ * Return value: an Xlib <type>Colormap</type>.
+ **/
 Colormap
 gdk_x11_colormap_get_xcolormap (GdkColormap *colormap)
 {
diff --git a/gdk/x11/gdkcursor-x11.c b/gdk/x11/gdkcursor-x11.c
index f7ce4bf86..3a424d249 100644
--- a/gdk/x11/gdkcursor-x11.c
+++ b/gdk/x11/gdkcursor-x11.c
@@ -187,6 +187,14 @@ _gdk_cursor_destroy (GdkCursor *cursor)
   g_free (private);
 }
 
+/**
+ * gdk_x11_cursor_get_xdisplay:
+ * @cursor: a #GdkCursor.
+ * 
+ * Returns the display of a #GdkCursor.
+ * 
+ * Return value: an Xlib <type>Display*</type>.
+ **/
 Display *
 gdk_x11_cursor_get_xdisplay (GdkCursor *cursor)
 {
@@ -195,6 +203,14 @@ gdk_x11_cursor_get_xdisplay (GdkCursor *cursor)
   return GDK_DISPLAY_XDISPLAY(((GdkCursorPrivate *)cursor)->display);
 }
 
+/**
+ * gdk_x11_cursor_get_xcursor:
+ * @cursor: a #GdkCursor.
+ * 
+ * Returns the X cursor belonging to a #GdkCursor.
+ * 
+ * Return value: an Xlib <type>Cursor</type>.
+ **/
 Cursor
 gdk_x11_cursor_get_xcursor (GdkCursor *cursor)
 {
diff --git a/gdk/x11/gdkdisplay-x11.c b/gdk/x11/gdkdisplay-x11.c
index 4558e3449..5ff1bb469 100644
--- a/gdk/x11/gdkdisplay-x11.c
+++ b/gdk/x11/gdkdisplay-x11.c
@@ -465,6 +465,15 @@ gdk_display_sync (GdkDisplay * display)
   XSync (GDK_DISPLAY_XDISPLAY (display), False);
 }
 
+/**
+ * gdk_x11_display_grab:
+ * @display: a #GdkDisplay 
+ * 
+ * Call XGrabServer() on @display. 
+ * To ungrab the display again, use gdk_x11_display_ungrab(). 
+ *
+ * gdk_x11_display_grab()/gdk_x11_display_ungrab() calls can be nested.
+ **/
 void
 gdk_x11_display_grab (GdkDisplay * display)
 {
@@ -479,6 +488,13 @@ gdk_x11_display_grab (GdkDisplay * display)
   display_x11->grab_count++;
 }
 
+/**
+ * gdk_x11_display_ungrab:
+ * @display: a #GdkDisplay
+ * 
+ * Ungrab @display after it has been grabbed with 
+ * gdk_x11_display_grab(). 
+ **/
 void
 gdk_x11_display_ungrab (GdkDisplay * display)
 {
diff --git a/gdk/x11/gdkdnd-x11.c b/gdk/x11/gdkdnd-x11.c
index 43f10a1de..f2e5850c9 100644
--- a/gdk/x11/gdkdnd-x11.c
+++ b/gdk/x11/gdkdnd-x11.c
@@ -2863,6 +2863,23 @@ drag_context_find_window_cache (GdkDragContext  *context,
   return cache;
 }
 
+/**
+ * gdk_drag_find_window_for_screen:
+ * @context: a #GdkDragContext
+ * @drag_window: a window which may be at the pointer position, but
+ * should be ignored, since it is put up by the drag source as an icon.
+ * @screen: the screen where the destination window is sought. 
+ * @x_root: the x position of the pointer in root coordinates.
+ * @y_root: the y position of the pointer in root coordinates.
+ * @dest_window: location to store the destination window in.
+ * @protocol: location to store the DND protocol in.
+ * 
+ * Finds the destination window and DND protocol to use at the
+ * given pointer position. 
+ *
+ * This function is called by the drag source to obtain the 
+ * @dest_window and @protocol parameters for gdk_drag_motion().
+ **/
 void
 gdk_drag_find_window_for_screen (GdkDragContext  *context,
 				 GdkWindow       *drag_window,
diff --git a/gdk/x11/gdkdrawable-x11.c b/gdk/x11/gdkdrawable-x11.c
index a9149197d..54db5a89c 100644
--- a/gdk/x11/gdkdrawable-x11.c
+++ b/gdk/x11/gdkdrawable-x11.c
@@ -895,6 +895,14 @@ gdk_x11_get_visual (GdkDrawable    *drawable)
   return gdk_drawable_get_visual (GDK_DRAWABLE_IMPL_X11 (drawable)->wrapper);
 }
 
+/**
+ * gdk_x11_drawable_get_xdisplay:
+ * @drawable: a #GdkDrawable.
+ * 
+ * Returns the display of a #GdkDrawable.
+ * 
+ * Return value: an Xlib <type>Display*</type>.
+ **/
 Display *
 gdk_x11_drawable_get_xdisplay (GdkDrawable *drawable)
 {
@@ -904,6 +912,14 @@ gdk_x11_drawable_get_xdisplay (GdkDrawable *drawable)
     return GDK_SCREEN_XDISPLAY (GDK_DRAWABLE_IMPL_X11 (get_impl_drawable (drawable))->screen);
 }
 
+/**
+ * gdk_x11_drawable_get_xid:
+ * @drawable: a #GdkDrawable.
+ * 
+ * Returns the X resource (window or pixmap) belonging to a #GdkDrawable.
+ * 
+ * Return value: the ID of @drawable's X resource.
+ **/
 XID
 gdk_x11_drawable_get_xid (GdkDrawable *drawable)
 {
diff --git a/gdk/x11/gdkevents-x11.c b/gdk/x11/gdkevents-x11.c
index ceef45d9f..b21098b4a 100644
--- a/gdk/x11/gdkevents-x11.c
+++ b/gdk/x11/gdkevents-x11.c
@@ -2244,6 +2244,16 @@ fetch_net_wm_check_window (GdkScreen *screen)
   _gdk_x11_screen_window_manager_changed (GDK_SCREEN (screen_x11));
 }
 
+/**
+ * gdk_x11_screen_get_window_manager_name:
+ * @screen: a #GdkScreen 
+ * 
+ * Returns the name of the window manager for @screen. 
+ * 
+ * Return value: the name of the window manager screen @screen, or 
+ * "unknown" if the window manager is unknown. The string is owned by GDK
+ * and should not be freed.
+ **/
 const char*
 gdk_x11_screen_get_window_manager_name (GdkScreen *screen)
 {
diff --git a/gdk/x11/gdkfont-x11.c b/gdk/x11/gdkfont-x11.c
index fdee17414..b42a83187 100644
--- a/gdk/x11/gdkfont-x11.c
+++ b/gdk/x11/gdkfont-x11.c
@@ -764,6 +764,14 @@ gdk_text_extents_wc (GdkFont        *font,
 
 }
 
+/**
+ * gdk_x11_font_get_xdisplay:
+ * @font: a #GdkFont.
+ * 
+ * Returns the display of a #GdkFont.
+ * 
+ * Return value:  an Xlib <type>Display*</type>.
+ **/
 Display *
 gdk_x11_font_get_xdisplay (GdkFont *font)
 {
@@ -772,6 +780,14 @@ gdk_x11_font_get_xdisplay (GdkFont *font)
   return GDK_DISPLAY_XDISPLAY (((GdkFontPrivateX *)font)->display);
 }
 
+/**
+ * gdk_x11_font_get_xfont:
+ * @font: a #GdkFont.
+ * 
+ * Returns the X font belonging to a #GdkFont.
+ * 
+ * Return value: an Xlib <type>XFontStruct*</type> or an <type>XFontSet</type>.
+ **/
 gpointer
 gdk_x11_font_get_xfont (GdkFont *font)
 {
diff --git a/gdk/x11/gdkgc-x11.c b/gdk/x11/gdkgc-x11.c
index 4e0fa1697..20d9f8362 100644
--- a/gdk/x11/gdkgc-x11.c
+++ b/gdk/x11/gdkgc-x11.c
@@ -751,6 +751,14 @@ gdk_gc_get_screen (GdkGC *gc)
   return GDK_GC_X11 (gc)->screen;
 }
 
+/**
+ * gdk_x11_gc_get_xdisplay:
+ * @gc: a #GdkGC.
+ * 
+ * Returns the display of a #GdkGC.
+ * 
+ * Return value: an Xlib <type>Display*</type>.
+ **/
 Display *
 gdk_x11_gc_get_xdisplay (GdkGC *gc)
 {
@@ -759,6 +767,14 @@ gdk_x11_gc_get_xdisplay (GdkGC *gc)
   return GDK_SCREEN_XDISPLAY (gdk_gc_get_screen (gc));
 }
 
+/**
+ * gdk_x11_gc_get_xgc:
+ * @gc: a #GdkGC.
+ * 
+ * Returns the X GC of a #GdkGC.
+ * 
+ * Return value: an Xlib <type>GC</type>.
+ **/
 GC
 gdk_x11_gc_get_xgc (GdkGC *gc)
 {
diff --git a/gdk/x11/gdkimage-x11.c b/gdk/x11/gdkimage-x11.c
index 6db834502..b08a553a6 100644
--- a/gdk/x11/gdkimage-x11.c
+++ b/gdk/x11/gdkimage-x11.c
@@ -790,6 +790,14 @@ gdk_x11_image_destroy (GdkImage *image)
   image->windowing_data = NULL;
 }
 
+/**
+ * gdk_x11_image_get_xdisplay:
+ * @image: a #GdkImage.
+ * 
+ * Returns the display of a #GdkImage.
+ * 
+ * Return value: an Xlib <type>Display*</type>.
+ **/
 Display *
 gdk_x11_image_get_xdisplay (GdkImage *image)
 {
@@ -802,6 +810,14 @@ gdk_x11_image_get_xdisplay (GdkImage *image)
   return GDK_SCREEN_XDISPLAY (private->screen);
 }
 
+/**
+ * gdk_x11_image_get_ximage:
+ * @image: a #GdkImage.
+ * 
+ * Returns the X image belonging to a #GdkImage.
+ * 
+ * Return value: an <type>XImage*</type>.
+ **/
 XImage *
 gdk_x11_image_get_ximage (GdkImage *image)
 {
diff --git a/gdk/x11/gdkmain-x11.c b/gdk/x11/gdkmain-x11.c
index c34eafaad..27a09b3a3 100644
--- a/gdk/x11/gdkmain-x11.c
+++ b/gdk/x11/gdkmain-x11.c
@@ -736,12 +736,26 @@ _gdk_region_get_xrectangles (GdkRegion   *region,
   *n_rects = region->numRects;
 }
 
+/**
+ * gdk_x11_grab_server:
+ * 
+ * Call gdk_x11_display_grab() on the default display. 
+ * To ungrab the server again, use gdk_x11_ungrab_server(). 
+ *
+ * gdk_x11_grab_server()/gdk_x11_ungrab_server() calls can be nested.
+ **/ 
 void
 gdk_x11_grab_server ()
 {
   gdk_x11_display_grab (gdk_display_get_default ());
 }
 
+/**
+ * gdk_x11_ungrab_server:
+ *
+ * Ungrab the default display after it has been grabbed with 
+ * gdk_x11_grab_server(). 
+ **/
 void
 gdk_x11_ungrab_server ()
 {
@@ -763,14 +777,33 @@ gdk_x11_get_default_screen (void)
   return gdk_screen_get_number (gdk_screen_get_default ());
 }
 
+/**
+ * gdk_x11_get_default_root_xwindow:
+ * 
+ * Gets the root window of the default screen 
+ * (see gdk_x11_get_default_screen()).  
+ * 
+ * Return value: an Xlib <type>Window</type>.
+ **/
 Window
 gdk_x11_get_default_root_xwindow (void)
 {
   return GDK_SCREEN_XROOTWIN (gdk_screen_get_default ());
 }
 
+/**
+ * gdk_x11_get_default_xdisplay:
+ * 
+ * Gets the default GTK+ display.
+ * 
+ * Return value: the Xlib <type>Display*</type> for the display
+ * specified in the <option>--display</option> command line option 
+ * or the <envar>DISPLAY</envar> environment variable.
+ **/
 Display *
 gdk_x11_get_default_xdisplay (void)
 {
   return GDK_DISPLAY_XDISPLAY (gdk_display_get_default ());
 }
+
+
diff --git a/gdk/x11/gdkselection-x11.c b/gdk/x11/gdkselection-x11.c
index d79f2cd5a..927dc61e4 100644
--- a/gdk/x11/gdkselection-x11.c
+++ b/gdk/x11/gdkselection-x11.c
@@ -363,7 +363,7 @@ gdk_selection_property_get (GdkWindow  *requestor,
 }
 
 /**
- * gdk_selection_send_notify_for_display :
+ * gdk_selection_send_notify_for_display:
  * @display : the #GdkDisplay where @requestor is realized
  * @requestor : window to which to deliver response.
  * @selection : selection that was requested.
@@ -416,7 +416,7 @@ gdk_selection_send_notify_for_display (GdkDisplay *display,
  * the current local. (The elements of the array represent the
  * null-separated elements of the original text string.)
  *
- * Returns : he number of strings stored in list, or 0, 
+ * Returns : the number of strings stored in list, or 0, 
  * if the conversion failed. 
  */
 gint
diff --git a/gdk/x11/gdkvisual-x11.c b/gdk/x11/gdkvisual-x11.c
index 1b79f0d90..7de791221 100644
--- a/gdk/x11/gdkvisual-x11.c
+++ b/gdk/x11/gdkvisual-x11.c
@@ -562,6 +562,14 @@ gdk_x11_screen_lookup_visual (GdkScreen *screen,
   return NULL;
 }
 
+/**
+ * gdkx_visual_get:
+ * @xvisualid: a X visual id.
+ * 
+ * Returns a #GdkVisual corresponding to a X visual. 
+ * 
+ * Return value: the #GdkVisual.
+ **/
 GdkVisual*
 gdkx_visual_get (VisualID xvisualid)
 {
@@ -615,6 +623,14 @@ gdk_visual_equal (Visual *a,
   return (a->visualid == b->visualid);
 }
 
+/**
+ * gdk_x11_visual_get_xvisual:
+ * @visual: a #GdkVisual.
+ * 
+ * Returns the X visual belonging to a #GdkVisual.
+ * 
+ * Return value: an Xlib <type>Visual*</type>.
+ **/
 Visual *
 gdk_x11_visual_get_xvisual (GdkVisual *visual)
 {
diff --git a/gdk/x11/gdkxid.c b/gdk/x11/gdkxid.c
index 1150e66fd..92c8cecb4 100644
--- a/gdk/x11/gdkxid.c
+++ b/gdk/x11/gdkxid.c
@@ -92,6 +92,16 @@ gdk_xid_table_lookup_for_display (GdkDisplay  *display,
   return data;
 }
 
+
+/**
+ * gdk_xid_table_lookup:
+ * @xid: an X id.
+ * 
+ * Returns the Gdk object associated with the given X id.
+ * 
+ * Return value: the associated Gdk object, which may be a #GdkPixmap,
+ * a #GdkWindow or a #GdkFont.
+ **/
 gpointer
 gdk_xid_table_lookup (XID xid)
 {