Gdk API doc updates.

16 files changed, 213 insertions, 7 deletions

diff --git a/gdk/gdkdisplaymanager.c b/gdk/gdkdisplaymanager.c
index e3ac84162f..644652dc30 100644
--- a/gdk/gdkdisplaymanager.c
+++ b/gdk/gdkdisplaymanager.c
@@ -176,11 +176,7 @@ gdk_display_manager_get (void)
  * gdk_display_manager_get_default_display:
  * @display_manager: a #GdkDisplayManager 
  *
- * Gets the default #GdkDisplay. This is a convenience
- * function for:
- * <programlisting>
- *   gdk_display_manager_get_default_display (gdk_display_manager_get ())
- * </programlisting>
+ * Gets the default #GdkDisplay. 
  * 
  * Returns: a #GdkDisplay, or %NULL if there is no default
  *   display.
@@ -258,3 +254,4 @@ gdk_display_manager_list_displays (GdkDisplayManager *display_manager)
 {
   return g_slist_copy (_gdk_displays);
 }
+
diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c
index 2dfe0c82e2..4e464906e3 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -260,6 +260,15 @@ gdk_event_put (GdkEvent *event)
 static GMemChunk *event_chunk = NULL;
 static GHashTable *event_hash = NULL;
 
+/**
+ * gdk_event_new:
+ * @type: a #GdkEventType 
+ * 
+ * Creates a new event of the given type. All fields are set to 0.
+ * 
+ * Return value: a newly-allocated #GdkEvent. The returned #GdkEvent 
+ * should be freed with gdk_event_free().
+ **/
 GdkEvent*
 gdk_event_new (GdkEventType type)
 {
diff --git a/gdk/linux-fb/gdkselection-fb.c b/gdk/linux-fb/gdkselection-fb.c
index a62ff130c5..65c72126c4 100644
--- a/gdk/linux-fb/gdkselection-fb.c
+++ b/gdk/linux-fb/gdkselection-fb.c
@@ -285,6 +285,7 @@ gdk_utf8_to_string_target (const gchar *str)
 
 /**
  * gdk_utf8_to_compound_text_for_display:
+ * @display:  a #GdkDisplay
  * @str:      a UTF-8 string
  * @encoding: location to store resulting encoding
  * @format:   location to store format of the result
@@ -381,6 +382,7 @@ make_list (const gchar  *text,
 
 /**
  * gdk_text_property_to_utf8_list_for_display:
+ * @display:  a #GdkDisplay
  * @encoding: an atom representing the encoding of the text
  * @format:   the format of the property
  * @text:     the text to convert
diff --git a/gdk/x11/gdkcolor-x11.c b/gdk/x11/gdkcolor-x11.c
index d46692719d..fe543021b0 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 f7ce4bf864..3a424d2495 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 4558e3449a..5ff1bb4699 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 43f10a1de2..f2e5850c9f 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 a9149197df..54db5a89c2 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 ceef45d9f7..b21098b4a1 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 fdee174145..b42a831874 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 4e0fa16974..20d9f83623 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 6db8345020..b08a553a69 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 c34eafaadd..27a09b3a34 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 d79f2cd5a8..927dc61e49 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 1b79f0d903..7de7912216 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 1150e66fd6..92c8cecb47 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)
 {