--- gdk_docs_orig.xml	2010-04-07 00:02:56.000000000 -0400
+++ gdk_docs_new.xml	2010-04-07 23:16:52.000000000 -0400
@@ -6,6 +6,7 @@
 determine how this total height will be drawn in
 relation to the baseline. See gdk_text_extents().
 
+Deprecated: 2.2: Use gdk_text_extents() instead.
 
 </description>
 <parameters>
@@ -20,7 +21,6 @@
 </parameters>
 <return> the height of the character in pixels.
 
-Deprecated: 2.2: Use gdk_text_extents() instead.
 </return>
 </function>
 
@@ -51,7 +51,9 @@
 
 <function name="gdk_display_get_screen">
 <description>
-Returns: the #GdkScreen object
+Returns a screen object for one of the screens of the display.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -66,12 +68,14 @@
 </parameters>
 <return> the #GdkScreen object
 
-Since: 2.2
 </return>
 </function>
 
 <function name="gdk_x11_screen_get_xscreen">
 <description>
+Returns the screen of a #GdkScreen.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -80,10 +84,7 @@
 </parameter_description>
 </parameter>
 </parameters>
-<return> (transfer none): an Xlib &lt;type&gt;Screen*&lt;/type&gt;
-the screen of a #GdkScreen.
-
-Since: 2.2
+<return> an Xlib &lt;type&gt;Screen*&lt;/type&gt;
 </return>
 </function>
 
@@ -158,7 +159,8 @@
 
 <function name="gdk_screen_width">
 <description>
-Return value: the width of the default screen in pixels.
+Returns the width of the default screen in pixels.
+
 
 </description>
 <parameters>
@@ -274,7 +276,8 @@
 
 <function name="gdk_x11_cursor_get_xcursor">
 <description>
-Return value: an Xlib &lt;type&gt;Cursor&lt;/type&gt;.
+Returns the X cursor belonging to a #GdkCursor.
+
 
 </description>
 <parameters>
@@ -407,7 +410,11 @@
 
 <function name="gdk_display_get_default_group">
 <description>
-Return value: The default group leader window for @display
+Returns the default group leader window for all toplevel windows
+on @display. This window is implicitly created by GDK. 
+See gdk_window_set_group().
+
+Since: 2.4
 
 </description>
 <parameters>
@@ -418,7 +425,6 @@
 </parameters>
 <return> The default group leader window for @display
 
-Since: 2.4
 </return>
 </function>
 
@@ -516,7 +522,7 @@
 </parameter_description>
 </parameter>
 <parameter name="gc">
-<parameter_description> (allow-none): the new GC to use for drawing, or %NULL
+<parameter_description> the new GC to use for drawing, or %NULL
 </parameter_description>
 </parameter>
 </parameters>
@@ -533,6 +539,7 @@
 This is useful for applications which wish to launch an application
 on a specific screen.
 
+Since: 2.4
 
 </description>
 <parameters>
@@ -591,7 +598,6 @@
 </parameters>
 <return> %TRUE on success, %FALSE if an error was set
 
-Since: 2.4
 </return>
 </function>
 
@@ -599,6 +605,7 @@
 <description>
 Get the default #GdkScreen for @display.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -609,13 +616,13 @@
 </parameters>
 <return> the default #GdkScreen object for @display
 
-Since: 2.2
 </return>
 </function>
 
 <function name="gdk_screen_height">
 <description>
-Return value: the height of the default screen in pixels.
+Returns the height of the default screen in pixels.
+
 
 </description>
 <parameters>
@@ -635,7 +642,7 @@
 </description>
 <parameters>
 <parameter name="parent">
-<parameter_description> (allow-none): a #GdkWindow, or %NULL to create the window as a child of
+<parameter_description> a #GdkWindow, or %NULL to create the window as a child of
 the default root window for the default display.
 </parameter_description>
 </parameter>
@@ -693,6 +700,7 @@
 <description>
 Deprecated function; use g_object_ref() instead.
 
+Deprecated: 2.0: Use g_object_ref() instead.
 
 </description>
 <parameters>
@@ -703,7 +711,6 @@
 </parameters>
 <return> the colormap
 
-Deprecated: 2.0: Use g_object_ref() instead.
 </return>
 </function>
 
@@ -728,6 +735,7 @@
 If you need to keep this around over window resizes, you need to
 add a reference to it.
 
+Since: 2.18
 
 </description>
 <parameters>
@@ -738,7 +746,6 @@
 </parameters>
 <return> The offscreen pixmap, or %NULL if not offscreen
 
-Since: 2.18
 </return>
 </function>
 
@@ -752,6 +759,7 @@
 For example in the X backend, a native window handle is an Xlib
 &lt;type&gt;XID&lt;/type&gt;.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -768,7 +776,6 @@
 %NULL if the window has been destroyed. The wrapper will be
 newly created, if one doesn't exist already.
 
-Since: 2.2
 </return>
 </function>
 
@@ -797,6 +804,7 @@
 <description>
 Creates a new attribute specifying the color to emboss text with.
 
+Since: 2.12
 
 </description>
 <parameters>
@@ -807,13 +815,13 @@
 </parameters>
 <return> new #PangoAttribute
 
-Since: 2.12
 </return>
 </function>
 
 <function name="gdk_x11_drawable_get_xdisplay">
 <description>
-Return value: an Xlib &lt;type&gt;Display*&lt;/type&gt;.
+Returns the display of a #GdkDrawable.
+
 
 </description>
 <parameters>
@@ -849,7 +857,9 @@
 
 <function name="gdk_display_get_default_cursor_size">
 <description>
-Returns: the default cursor size.
+Returns the default size to use for cursors on @display.
+
+Since: 2.4
 
 </description>
 <parameters>
@@ -860,7 +870,6 @@
 </parameters>
 <return> the default cursor size.
 
-Since: 2.4
 </return>
 </function>
 
@@ -901,6 +910,7 @@
 Gets the index of @screen among the screens in the display
 to which it belongs. (See gdk_screen_get_display())
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -911,7 +921,6 @@
 </parameters>
 <return> the index
 
-Since: 2.2
 </return>
 </function>
 
@@ -1062,7 +1071,9 @@
 
 <function name="gdk_screen_get_n_monitors">
 <description>
-Returns: number of monitors which @screen consists of
+Returns the number of monitors which @screen consists of.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -1073,7 +1084,6 @@
 </parameters>
 <return> number of monitors which @screen consists of
 
-Since: 2.2
 </return>
 </function>
 
@@ -1085,6 +1095,7 @@
 FIXME needs a list of valid settings here, or a link to 
 more information.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -1104,13 +1115,16 @@
 <return> %TRUE if the setting existed and a value was stored
 in @value, %FALSE otherwise.
 
-Since: 2.2
 </return>
 </function>
 
 <function name="gdk_display_supports_cursor_color">
 <description>
-Returns: whether cursors can have multiple colors.
+Returns %TRUE if multicolored cursors are supported
+on @display. Otherwise, cursors have only a forground
+and a background color.
+
+Since: 2.4
 
 </description>
 <parameters>
@@ -1121,7 +1135,6 @@
 </parameters>
 <return> whether cursors can have multiple colors.
 
-Since: 2.4
 </return>
 </function>
 
@@ -1203,6 +1216,7 @@
 <description>
 Determines the width of a given character.
 
+Deprecated: 2.2: Use gdk_text_extents() instead.
 
 </description>
 <parameters>
@@ -1217,7 +1231,6 @@
 </parameters>
 <return> the width of the character in pixels.
 
-Deprecated: 2.2: Use gdk_text_extents() instead.
 </return>
 </function>
 
@@ -1327,6 +1340,7 @@
 should only be used for legacy code that cannot be easily converted
 to use Pango. Using Pango directly will produce better results.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -1342,7 +1356,6 @@
 <return> the newly loaded font, or %NULL if the font
 cannot be loaded.
 
-Since: 2.2
 </return>
 </function>
 
@@ -1419,7 +1432,10 @@
 
 <function name="gdk_display_supports_shapes">
 <description>
-Returns: %TRUE if shaped windows are supported 
+Returns %TRUE if gdk_window_shape_combine_mask() can
+be used to create shaped windows on @display.
+
+Since: 2.10
 
 </description>
 <parameters>
@@ -1430,7 +1446,6 @@
 </parameters>
 <return> %TRUE if shaped windows are supported 
 
-Since: 2.10
 </return>
 </function>
 
@@ -1501,7 +1516,7 @@
 </parameter_description>
 </parameter>
 <parameter name="mask">
-<parameter_description> (out): Pointer to a place to store a bitmap representing
+<parameter_description> Pointer to a place to store a bitmap representing
 the transparency mask of the XPM file. Can be %NULL,
 in which case transparency will be ignored.
 </parameter_description>
@@ -1688,11 +1703,11 @@
 </parameter_description>
 </parameter>
 <parameter name="foreground">
-<parameter_description> (allow-none): foreground override color, or %NULL for none
+<parameter_description> foreground override color, or %NULL for none
 </parameter_description>
 </parameter>
 <parameter name="background">
-<parameter_description> (allow-none): background override color, or %NULL for none
+<parameter_description> background override color, or %NULL for none
 </parameter_description>
 </parameter>
 </parameters>
@@ -1707,12 +1722,58 @@
 This allows you to efficiently read individual pixels on the client side.
 
 If the drawable @src has no colormap (gdk_drawable_get_colormap()
-Return value: The same pixbuf as @dest if it was non-%NULL, or a newly-created
+returns %NULL), then a suitable colormap must be specified.
+Typically a #GdkWindow or a pixmap created by passing a #GdkWindow
+to gdk_pixmap_new() will already have a colormap associated with
+it.  If the drawable has a colormap, the @cmap argument will be
+ignored.  If the drawable is a bitmap (1 bit per pixel pixmap),
+then a colormap is not required; pixels with a value of 1 are
+assumed to be white, and pixels with a value of 0 are assumed to be
+black. For taking screenshots, gdk_colormap_get_system() returns
+the correct colormap to use.
+
+If the specified destination pixbuf @dest is %NULL, then this
+function will create an RGB pixbuf with 8 bits per channel and no
+alpha, with the same size specified by the @width and @height
+arguments.  In this case, the @dest_x and @dest_y arguments must be
+specified as 0.  If the specified destination pixbuf is not %NULL
+and it contains alpha information, then the filled pixels will be
+set to full opacity (alpha = 255).
+
+If the specified drawable is a pixmap, then the requested source
+rectangle must be completely contained within the pixmap, otherwise
+the function will return %NULL. For pixmaps only (not for windows)
+passing -1 for width or height is allowed to mean the full width
+or height of the pixmap.
+
+If the specified drawable is a window, and the window is off the
+screen, then there is no image data in the obscured/offscreen
+regions to be placed in the pixbuf. The contents of portions of the
+pixbuf corresponding to the offscreen region are undefined.
+
+If the window you're obtaining data from is partially obscured by
+other windows, then the contents of the pixbuf areas corresponding
+to the obscured regions are undefined.
+
+If the target drawable is not mapped (typically because it's
+iconified/minimized or not on the current workspace), then %NULL
+will be returned.
+
+If memory can't be allocated for the return value, %NULL will be returned
+instead.
+
+(In short, there are several ways this function can fail, and if it fails
+it returns %NULL; so check the return value.)
+
+This function calls gdk_drawable_get_image() internally and
+converts the resulting image to a #GdkPixbuf, so the
+documentation for gdk_drawable_get_image() may also be relevant.
+
 
 </description>
 <parameters>
 <parameter name="dest">
-<parameter_description> (allow-none): Destination pixbuf, or %NULL if a new pixbuf should be created.
+<parameter_description> Destination pixbuf, or %NULL if a new pixbuf should be created.
 </parameter_description>
 </parameter>
 <parameter name="src">
@@ -1777,7 +1838,9 @@
 
 <function name="gdk_screen_width_mm">
 <description>
-Return value: the width of the default screen in millimeters,
+Returns the width of the default screen in millimeters.
+Note that on many X servers this value will not be correct.
+
 
 </description>
 <parameters>
@@ -1794,6 +1857,7 @@
 the current locale. (The elements of the array represent the
 nul-separated elements of the original text string.)
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -1829,7 +1893,6 @@
 <return> the number of strings stored in list, or 0, 
 if the conversion failed. 
 
-Since: 2.2
 </return>
 </function>
 
@@ -1842,6 +1905,7 @@
 The returned list should be freed with g_list_free(), but
 its elements need not be freed.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -1852,7 +1916,6 @@
 </parameters>
 <return> list of toplevel windows, free with g_list_free()
 
-Since: 2.2
 </return>
 </function>
 
@@ -1921,7 +1984,12 @@
 
 <function name="gdk_x11_display_get_user_time">
 <description>
-Returns: the timestamp of the last user interaction 
+Returns the timestamp of the last user interaction on 
+@display. The timestamp is taken from events caused
+by user interaction such as key presses or pointer 
+movements. See gdk_x11_window_set_user_time().
+
+Since: 2.8
 
 </description>
 <parameters>
@@ -1932,13 +2000,13 @@
 </parameters>
 <return> the timestamp of the last user interaction 
 
-Since: 2.8
 </return>
 </function>
 
 <function name="gdk_x11_image_get_xdisplay">
 <description>
-Return value: an Xlib &lt;type&gt;Display*&lt;/type&gt;.
+Returns the display of a #GdkImage.
+
 
 </description>
 <parameters>
@@ -2024,7 +2092,9 @@
 
 <function name="gdk_screen_height_mm">
 <description>
-Return value: the height of the default screen in millimeters,
+Returns the height of the default screen in millimeters.
+Note that on many X servers this value will not be correct.
+
 
 </description>
 <parameters>
@@ -2034,41 +2104,6 @@
 </return>
 </function>
 
-<function name="GdkWindow">
-<description>
-The ::from-embedder signal is emitted to translate coordinates
-in the embedder of an offscreen window to the offscreen window.
-
-See also #GtkWindow::to-embedder.
-
-Since: 2.18
-
-</description>
-<parameters>
-<parameter name="window">
-<parameter_description> the offscreen window on which the signal is emitted
-</parameter_description>
-</parameter>
-<parameter name="embedder-x">
-<parameter_description> x coordinate in the embedder window
-</parameter_description>
-</parameter>
-<parameter name="embedder-y">
-<parameter_description> y coordinate in the embedder window
-</parameter_description>
-</parameter>
-<parameter name="offscreen-x">
-<parameter_description> return location for the x coordinate in the offscreen window
-</parameter_description>
-</parameter>
-<parameter name="offscreen-y">
-<parameter_description> return location for the y coordinate in the offscreen window
-</parameter_description>
-</parameter>
-</parameters>
-<return></return>
-</function>
-
 <function name="gdk_gc_set_font">
 <description>
 Sets the font for a graphics context. (Note that
@@ -2094,6 +2129,7 @@
 <description>
 Gets the default colormap for @screen.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -2104,7 +2140,6 @@
 </parameters>
 <return> (transfer none): the default #GdkColormap.
 
-Since: 2.2
 </return>
 </function>
 
@@ -2112,6 +2147,7 @@
 <description>
 Gets the window that @window is embedded in.
 
+Since: 2.18
 
 </description>
 <parameters>
@@ -2123,7 +2159,6 @@
 <return> the embedding #GdkWindow, or %NULL if @window is not an
 embedded offscreen window
 
-Since: 2.18
 </return>
 </function>
 
@@ -2226,7 +2261,49 @@
 <description>
 Sets a function to be called at regular intervals holding the GDK lock,
 with the given priority.  The function is called repeatedly until it 
-Return value: the ID (greater than 0) of the event source.
+returns %FALSE, at which point the timeout is automatically destroyed 
+and the function will not be called again.  The @notify function is
+called when the timeout is destroyed.  The first call to the
+function will be at the end of the first @interval.
+
+Note that timeout functions may be delayed, due to the processing of other
+event sources. Thus they should not be relied on for precise timing.
+After each call to the timeout function, the time of the next
+timeout is recalculated based on the current time and the given interval
+(it does not try to 'catch up' time lost in delays).
+
+This variant of g_timeout_add_full() can be thought of a MT-safe version 
+for GTK+ widgets for the following use case:
+
+|[
+static gboolean timeout_callback (gpointer data)
+{
+SomeWidget *self = data;
+
+/* do stuff with self */
+
+self-&gt;timeout_id = 0;
+
+return FALSE;
+}
+
+static void some_widget_do_stuff_later (SomeWidget *self)
+{
+self-&gt;timeout_id = g_timeout_add (timeout_callback, self)
+}
+
+static void some_widget_finalize (GObject *object)
+{
+SomeWidget *self = SOME_WIDGET (object);
+
+if (self-&gt;timeout_id)
+g_source_remove (self-&gt;timeout_id);
+
+G_OBJECT_CLASS (parent_class)-&gt;finalize (object);
+}
+]|
+
+Since: 2.12
 
 </description>
 <parameters>
@@ -2249,13 +2326,12 @@
 </parameter_description>
 </parameter>
 <parameter name="notify">
-<parameter_description> (allow-none):   function to call when the timeout is removed, or %NULL
+<parameter_description>   function to call when the timeout is removed, or %NULL
 </parameter_description>
 </parameter>
 </parameters>
 <return> the ID (greater than 0) of the event source.
 
-Since: 2.12
 </return>
 </function>
 
@@ -2300,7 +2376,7 @@
 </parameter_description>
 </parameter>
 <parameter name="gc">
-<parameter_description> (allow-none): a #GdkGC, used for clipping, or %NULL
+<parameter_description> a #GdkGC, used for clipping, or %NULL
 </parameter_description>
 </parameter>
 <parameter name="pixbuf">
@@ -2353,6 +2429,7 @@
 with the same string value. The special value %GDK_NONE
 is converted to %None.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -2367,7 +2444,6 @@
 </parameters>
 <return> the X atom corresponding to @atom, or %None
 
-Since: 2.2
 </return>
 </function>
 
@@ -2391,18 +2467,18 @@
 </parameter_description>
 </parameter>
 <parameter name="real_drawable">
-<parameter_description> (out): location to store the drawable to which drawing should be
+<parameter_description> location to store the drawable to which drawing should be
 done.
 </parameter_description>
 </parameter>
 <parameter name="x_offset">
-<parameter_description> (out): location to store the X offset between coordinates in @window,
+<parameter_description> location to store the X offset between coordinates in @window,
 and the underlying window system primitive coordinates for
 *@real_drawable.
 </parameter_description>
 </parameter>
 <parameter name="y_offset">
-<parameter_description> (out): location to store the Y offset between coordinates in @window,
+<parameter_description> location to store the Y offset between coordinates in @window,
 and the underlying window system primitive coordinates for
 *@real_drawable.
 </parameter_description>
@@ -2450,8 +2526,9 @@
 
 <function name="gdk_event_get_time">
 <description>
+Returns the time stamp from @event, if there is one; otherwise
 returns #GDK_CURRENT_TIME. If @event is %NULL, returns #GDK_CURRENT_TIME.
-Return value: time stamp field from @event
+
 
 </description>
 <parameters>
@@ -2602,7 +2679,9 @@
 
 <function name="gdk_color_black">
 <description>
-Return value: %TRUE if the allocation succeeded.
+Returns the black color for a given colormap. The resulting
+value has already been allocated. 
+
 
 </description>
 <parameters>
@@ -2774,7 +2853,8 @@
 
 <function name="gdk_font_id">
 <description>
-Return value: the numeric X Font ID
+Returns the X Font ID for the given font. 
+
 
 </description>
 <parameters>
@@ -2853,6 +2933,7 @@
 Converts a text property in the given encoding to
 a list of UTF-8 strings. 
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -2885,7 +2966,6 @@
 <return> the number of strings in the resulting
 list.
 
-Since: 2.2
 </return>
 </function>
 
@@ -3106,6 +3186,7 @@
 <description>
 Gets the height in millimeters of the specified monitor.
 
+Since: 2.14
 
 </description>
 <parameters>
@@ -3120,7 +3201,6 @@
 </parameters>
 <return> the height of the monitor, or -1 if not available
 
-Since: 2.14
 </return>
 </function>
 
@@ -3154,11 +3234,11 @@
 </description>
 <parameters>
 <parameter name="depths">
-<parameter_description> (out) (array): return location for available depths
+<parameter_description> return location for available depths
 </parameter_description>
 </parameter>
 <parameter name="count">
-<parameter_description> (out): return location for number of available depths
+<parameter_description> return location for number of available depths
 </parameter_description>
 </parameter>
 </parameters>
@@ -3197,6 +3277,7 @@
 This is useful for applications which wish to launch an application
 on a specific screen.
 
+Since: 2.4
 
 </description>
 <parameters>
@@ -3240,7 +3321,6 @@
 </parameters>
 <return> %TRUE on success, %FALSE if error is set
 
-Since: 2.4
 </return>
 </function>
 
@@ -3253,6 +3333,7 @@
 This function is useful when matching key events against
 accelerators.
 
+Since: 2.20
 
 </description>
 <parameters>
@@ -3270,13 +3351,17 @@
 if a virtual modifier is mapped to a non-virtual modifier that
 was already set in @state.
 
-Since: 2.20
 </return>
 </function>
 
 <function name="gdk_color_to_string">
 <description>
-Return value: a newly-allocated text string
+Returns a textual specification of @color in the hexadecimal form
+&lt;literal&gt;&num;rrrrggggbbbb&lt;/literal&gt;, where &lt;literal&gt;r&lt;/literal&gt;,
+&lt;literal&gt;g&lt;/literal&gt; and &lt;literal&gt;b&lt;/literal&gt; are hex digits
+representing the red, green and blue components respectively.
+
+Since: 2.12
 
 </description>
 <parameters>
@@ -3287,7 +3372,6 @@
 </parameters>
 <return> a newly-allocated text string
 
-Since: 2.12
 </return>
 </function>
 
@@ -3303,6 +3387,7 @@
 for cases where the dimensions of the pixmap are known. For the X
 backend, this avoids a roundtrip to the server.
 
+Since: 2.10
 
 </description>
 <parameters>
@@ -3330,7 +3415,6 @@
 <return> the newly-created #GdkPixmap wrapper for the 
 native pixmap or %NULL if the pixmap has been destroyed.
 
-Since: 2.10
 </return>
 </function>
 
@@ -3530,7 +3614,7 @@
 </parameter_description>
 </parameter>
 <parameter name="rect">
-<parameter_description> (allow-none): rectangle to invalidate or %NULL to invalidate the whole
+<parameter_description> rectangle to invalidate or %NULL to invalidate the whole
 window
 </parameter_description>
 </parameter>
@@ -3546,6 +3630,7 @@
 <description>
 Gets the #GdkScreen associated with a #GdkDrawable.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -3556,7 +3641,6 @@
 </parameters>
 <return> the #GdkScreen associated with @drawable
 
-Since: 2.2
 </return>
 </function>
 
@@ -3794,6 +3878,7 @@
 Request #GdkEventOwnerChange events for ownership changes
 of the selection named by the given atom.
 
+Since: 2.6
 
 </description>
 <parameters>
@@ -3810,7 +3895,6 @@
 <return> whether #GdkEventOwnerChange events will 
 be sent.
 
-Since: 2.6
 </return>
 </function>
 
@@ -4010,6 +4094,7 @@
 
 For details, see gdk_threads_add_timeout_full().
 
+Since: 2.14
 
 </description>
 <parameters>
@@ -4028,7 +4113,6 @@
 </parameters>
 <return> the ID (greater than 0) of the event source.
 
-Since: 2.14
 </return>
 </function>
 
@@ -4069,12 +4153,12 @@
 
 <function name="gdk_keymap_get_default">
 <description>
+Returns the #GdkKeymap attached to the default display.
 
 </description>
 <parameters>
 </parameters>
 <return> the #GdkKeymap attached to the default display.
-the #GdkKeymap attached to the default display.
 </return>
 </function>
 
@@ -4137,6 +4221,7 @@
 <description>
 Gets the #GdkScreen for which @gc was created
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -4147,7 +4232,6 @@
 </parameters>
 <return> the #GdkScreen for @gc.
 
-Since: 2.2
 </return>
 </function>
 
@@ -4167,6 +4251,7 @@
 On the X backend, support for RGBA cursors requires a
 sufficently new version of the X Render extension. 
 
+Since: 2.4
 
 </description>
 <parameters>
@@ -4189,7 +4274,6 @@
 </parameters>
 <return> a new #GdkCursor.
 
-Since: 2.4
 </return>
 </function>
 
@@ -4237,7 +4321,7 @@
 
 <function name="gdk_window_get_decorations">
 <description>
-Returns: TRUE if the window has decorations set, FALSE otherwise.
+Returns the decorations set on the GdkWindow with #gdk_window_set_decorations
 
 </description>
 <parameters>
@@ -4259,6 +4343,7 @@
 Determines if keyboard layouts for both right-to-left and left-to-right
 languages are in use.
 
+Since: 2.12
 
 </description>
 <parameters>
@@ -4269,7 +4354,6 @@
 </parameters>
 <return> %TRUE if there are layouts in both directions, %FALSE otherwise
 
-Since: 2.12
 </return>
 </function>
 
@@ -4376,7 +4460,7 @@
 </parameter_description>
 </parameter>
 <parameter name="destroy_func">
-<parameter_description> (allow-none): function to free @data, or %NULL
+<parameter_description> function to free @data, or %NULL
 </parameter_description>
 </parameter>
 </parameters>
@@ -4385,7 +4469,15 @@
 
 <function name="gdk_event_get_screen">
 <description>
-Return value: the screen for the event
+Returns the screen for the event. The screen is
+typically the screen for &lt;literal&gt;event-&gt;any.window&lt;/literal&gt;, but
+for events such as mouse events, it is the screen
+where the pointer was when the event occurs -
+that is, the screen which has the root window 
+to which &lt;literal&gt;event-&gt;motion.x_root&lt;/literal&gt; and
+&lt;literal&gt;event-&gt;motion.y_root&lt;/literal&gt; are relative.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -4396,7 +4488,6 @@
 </parameters>
 <return> the screen for the event
 
-Since: 2.2
 </return>
 </function>
 
@@ -4444,6 +4535,7 @@
 <description>
 List all currently open displays.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -4455,13 +4547,14 @@
 <return> a newly allocated #GSList of #GdkDisplay objects.
 Free this list with g_slist_free() when you are done with it.
 
-Since: 2.2
 </return>
 </function>
 
 <function name="gdk_xid_table_lookup">
 <description>
-Return value: the associated Gdk object, which may be a #GdkPixmap,
+Returns the Gdk object associated with the given X id for the default
+display.
+
 
 </description>
 <parameters>
@@ -4742,7 +4835,12 @@
 
 <function name="gdk_pointer_is_grabbed">
 <description>
-Return value: %TRUE if the pointer is currently grabbed by this application.* 
+Returns %TRUE if the pointer on the default display is currently 
+grabbed by this application.
+
+Note that this does not take the inmplicit pointer grab on button
+presses into account.
+
 
 </description>
 <parameters>
@@ -4803,6 +4901,7 @@
 This is useful for applications which wish to launch an application
 on a specific screen.
 
+Since: 2.4
 
 </description>
 <parameters>
@@ -4821,7 +4920,6 @@
 </parameters>
 <return> %TRUE on success, %FALSE if error is set.
 
-Since: 2.4
 </return>
 </function>
 
@@ -4844,7 +4942,7 @@
 </parameter_description>
 </parameter>
 <parameter name="color">
-<parameter_description> (allow-none): the color to use, or %NULL to unset a previously
+<parameter_description> the color to use, or %NULL to unset a previously
 set override color.
 </parameter_description>
 </parameter>
@@ -4857,6 +4955,7 @@
 Convert a string from the encoding of the current 
 locale into a form suitable for storing in a window property.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -4888,7 +4987,6 @@
 </parameters>
 <return> 0 upon success, non-zero upon failure. 
 
-Since: 2.2
 </return>
 </function>
 
@@ -4927,7 +5025,10 @@
 
 <function name="gdk_display_supports_input_shapes">
 <description>
-Returns: %TRUE if windows with modified input shape are supported 
+Returns %TRUE if gdk_window_input_shape_combine_mask() can
+be used to modify the input shape of windows on @display.
+
+Since: 2.10
 
 </description>
 <parameters>
@@ -4938,7 +5039,6 @@
 </parameters>
 <return> %TRUE if windows with modified input shape are supported 
 
-Since: 2.10
 </return>
 </function>
 
@@ -5075,7 +5175,9 @@
 
 <function name="gdk_screen_get_monitor_at_point">
 <description>
-Returns: the monitor number in which the point (@x,@y) lies, or
+Returns the monitor number in which the point (@x,@y) is located.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -5095,7 +5197,6 @@
 <return> the monitor number in which the point (@x,@y) lies, or
 a monitor close to (@x,@y) if the point is not in any monitor.
 
-Since: 2.2
 </return>
 </function>
 
@@ -5255,6 +5356,7 @@
 not get more events from the windowing system.  It only checks the events
 that have already been moved to the GDK event queue.)
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -5267,7 +5369,6 @@
 if no events are in the queue. The returned #GdkEvent should be freed with
 gdk_event_free().
 
-Since: 2.2
 </return>
 </function>
 
@@ -5366,6 +5467,7 @@
 <description>
 Gets the default #GdkDisplay.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -5377,7 +5479,6 @@
 <return> (transfer none): a #GdkDisplay, or %NULL if there is no default
 display.
 
-Since: 2.2
 </return>
 </function>
 
@@ -5539,6 +5640,7 @@
 Gets the display name specified in the command line arguments passed
 to gdk_init() or gdk_parse_args(), if any.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -5546,7 +5648,6 @@
 <return> the display name, if specified explicitely, otherwise %NULL
 this string is owned by GTK+ and must not be modified or freed.
 
-Since: 2.2
 </return>
 </function>
 
@@ -5562,7 +5663,7 @@
 </parameter_description>
 </parameter>
 <parameter name="rectangles">
-<parameter_description> (array length=n_rectangles) (transfer container): return location for an array of rectangles
+<parameter_description> return location for an array of rectangles
 </parameter_description>
 </parameter>
 <parameter name="n_rectangles">
@@ -5575,7 +5676,10 @@
 
 <function name="gdk_colormap_get_system_size">
 <description>
-Return value: the size of the system's default colormap.
+Returns the size of the system's default colormap.
+(See the description of struct #GdkColormap for an
+explanation of the size of a colormap.)
+
 
 </description>
 <parameters>
@@ -5674,6 +5778,7 @@
 the optimal one in those previous versions. GdkRGB can now render to 
 drawables with any visual.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -5684,7 +5789,6 @@
 </parameters>
 <return> The #GdkVisual chosen by GdkRGB.
 
-Since: 2.2
 </return>
 </function>
 
@@ -5704,6 +5808,7 @@
 is more convenient if you want to keep a context around and track
 changes to the screen's font rendering settings.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -5714,13 +5819,14 @@
 </parameters>
 <return> a new #PangoContext for @screen
 
-Since: 2.2
 </return>
 </function>
 
 <function name="gdk_xid_table_lookup_for_display">
 <description>
-Return value: the associated Gdk object, which may be a #GdkPixmap,
+Returns the GDK object associated with the given X id.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -5737,7 +5843,6 @@
 a #GdkWindow or a #GdkFont or %NULL if no object is associated
 with the X id.
 
-Since: 2.2
 </return>
 </function>
 
@@ -5791,6 +5896,7 @@
 This is the visual for the root window of the display.
 The return value should not be freed.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -5801,7 +5907,6 @@
 </parameters>
 <return> (transfer none): the system visual
 
-Since: 2.2
 </return>
 </function>
 
@@ -5924,7 +6029,8 @@
 
 <function name="gdk_x11_cursor_get_xdisplay">
 <description>
-Return value: an Xlib &lt;type&gt;Display*&lt;/type&gt;.
+Returns the display of a #GdkCursor.
+
 
 </description>
 <parameters>
@@ -6037,7 +6143,7 @@
 </parameter_description>
 </parameter>
 <parameter name="dest">
-<parameter_description> (allow-none): return location for the intersection of @src1 and @src2, or %NULL
+<parameter_description> return location for the intersection of @src1 and @src2, or %NULL
 </parameter_description>
 </parameter>
 </parameters>
@@ -6045,26 +6151,6 @@
 </return>
 </function>
 
-<function name="GdkScreen">
-<description>
-The ::monitors-changed signal is emitted when the number, size
-or position of the monitors attached to the screen change. 
-
-Only for X11 and OS X for now. A future implementation for Win32
-may be a possibility.
-
-Since: 2.14
-
-</description>
-<parameters>
-<parameter name="screen">
-<parameter_description> the object on which the signal is emitted
-</parameter_description>
-</parameter>
-</parameters>
-<return></return>
-</function>
-
 <function name="gdk_device_get_state">
 <description>
 Gets the current state of a device.
@@ -6096,6 +6182,7 @@
 <description>
 Gets the #GdkDisplay associated with a #GdkDrawable.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -6106,7 +6193,6 @@
 </parameters>
 <return> the #GdkDisplay associated with @drawable
 
-Since: 2.2
 </return>
 </function>
 
@@ -6114,6 +6200,7 @@
 <description>
 Deprecated function; use g_object_ref() instead.
 
+Deprecated: 2.0: Use g_object_ref() instead.
 
 </description>
 <parameters>
@@ -6124,7 +6211,6 @@
 </parameters>
 <return> the gc.
 
-Deprecated: 2.0: Use g_object_ref() instead.
 </return>
 </function>
 
@@ -6257,11 +6343,11 @@
 </parameter_description>
 </parameter>
 <parameter name="lower">
-<parameter_description> (out): return location for lowercase version of @symbol
+<parameter_description> return location for lowercase version of @symbol
 </parameter_description>
 </parameter>
 <parameter name="upper">
-<parameter_description> (out): return location for uppercase version of @symbol
+<parameter_description> return location for uppercase version of @symbol
 </parameter_description>
 </parameter>
 </parameters>
@@ -6334,7 +6420,8 @@
 
 <function name="gdk_x11_font_get_xdisplay">
 <description>
-Return value:  an Xlib &lt;type&gt;Display*&lt;/type&gt;.
+Returns the display of a #GdkFont.
+
 
 </description>
 <parameters>
@@ -6349,7 +6436,14 @@
 
 <function name="_gdk_drawable_get_scratch_gc">
 <description>
-Return value: A #GdkGC suitable for drawing on @drawable
+Returns a #GdkGC suitable for drawing on @drawable. The #GdkGC has
+the standard values for @drawable, except for the graphics_exposures
+field which is determined by the @graphics_exposures parameter.
+
+The foreground color of the returned #GdkGC is undefined. The #GdkGC
+must not be altered in any way, except to change its foreground color.
+
+Since: 2.4
 
 </description>
 <parameters>
@@ -6364,7 +6458,6 @@
 </parameters>
 <return> A #GdkGC suitable for drawing on @drawable
 
-Since: 2.4
 </return>
 </function>
 
@@ -6417,11 +6510,11 @@
 </parameter_description>
 </parameter>
 <parameter name="width">
-<parameter_description> (allow-none): (out): location to store drawable's width, or %NULL
+<parameter_description> location to store drawable's width, or %NULL
 </parameter_description>
 </parameter>
 <parameter name="height">
-<parameter_description> (allow-none): (out): location to store drawable's height, or %NULL
+<parameter_description> location to store drawable's height, or %NULL
 </parameter_description>
 </parameter>
 </parameters>
@@ -6432,6 +6525,7 @@
 <description>
 Looks up the #GdkVisual for a particular screen and X Visual ID.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -6447,7 +6541,6 @@
 <return> the #GdkVisual (owned by the screen object), or %NULL
 if the visual ID wasn't found.
 
-Since: 2.2
 </return>
 </function>
 
@@ -6462,6 +6555,7 @@
 If no primary monitor is configured by the user, the return value
 will be 0, defaulting to the first monitor.
 
+Since: 2.20
 
 </description>
 <parameters>
@@ -6472,7 +6566,6 @@
 </parameters>
 <return> An integer index for the primary monitor, or 0 if none is configured.
 
-Since: 2.20
 </return>
 </function>
 
@@ -6502,7 +6595,10 @@
 
 <function name="gdk_display_supports_selection_notification">
 <description>
-Return value: whether #GdkEventOwnerChange events will 
+Returns whether #GdkEventOwnerChange events will be 
+sent when the owner of a selection changes.
+
+Since: 2.6
 
 </description>
 <parameters>
@@ -6514,7 +6610,6 @@
 <return> whether #GdkEventOwnerChange events will 
 be sent.
 
-Since: 2.6
 </return>
 </function>
 
@@ -6547,6 +6642,7 @@
 <description>
 Gets the display to which the @screen belongs.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -6557,7 +6653,6 @@
 </parameters>
 <return> the display to which @screen belongs
 
-Since: 2.2
 </return>
 </function>
 
@@ -6580,6 +6675,9 @@
 
 <function name="gdk_x11_screen_get_screen_number">
 <description>
+Returns the index of a #GdkScreen.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -6590,9 +6688,6 @@
 </parameters>
 <return> the position of @screen among the screens of
 its display.
-the index of a #GdkScreen.
-
-Since: 2.2
 </return>
 </function>
 
@@ -6640,6 +6735,7 @@
 }
 ]|
 
+Since: 2.12
 
 </description>
 <parameters>
@@ -6657,13 +6753,12 @@
 </parameter_description>
 </parameter>
 <parameter name="notify">
-<parameter_description> (allow-none):   function to call when the idle is removed, or %NULL
+<parameter_description>   function to call when the idle is removed, or %NULL
 </parameter_description>
 </parameter>
 </parameters>
 <return> the ID (greater than 0) of the event source.
 
-Since: 2.12
 </return>
 </function>
 
@@ -6691,7 +6786,7 @@
 </parameter_description>
 </parameter>
 <parameter name="matrix">
-<parameter_description> (allow-none): a #PangoMatrix, or %NULL to use an identity transformation
+<parameter_description> a #PangoMatrix, or %NULL to use an identity transformation
 </parameter_description>
 </parameter>
 <parameter name="font">
@@ -6738,7 +6833,8 @@
 
 <function name="gdk_x11_font_get_xfont">
 <description>
-Return value: an Xlib &lt;type&gt;XFontStruct*&lt;/type&gt; or an &lt;type&gt;XFontSet&lt;/type&gt;.
+Returns the X font belonging to a #GdkFont.
+
 
 </description>
 <parameters>
@@ -6753,7 +6849,9 @@
 
 <function name="gdk_display_get_core_pointer">
 <description>
-Return value: the core pointer device; this is owned by the
+Returns the core pointer device for the given display
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -6765,7 +6863,6 @@
 <return> the core pointer device; this is owned by the
 display and should not be freed.
 
-Since: 2.2
 </return>
 </function>
 
@@ -6775,6 +6872,7 @@
 If the X server does not support version 1.2 of the RANDR
 extension, 0 is returned.
 
+Since: 2.14
 
 </description>
 <parameters>
@@ -6789,7 +6887,6 @@
 </parameters>
 <return> the XID of the monitor
 
-Since: 2.14
 </return>
 </function>
 
@@ -6952,6 +7049,7 @@
 <description>
 Gets the system's default colormap for @screen
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -6962,7 +7060,6 @@
 </parameters>
 <return> (transfer none): the default colormap for @screen.
 
-Since: 2.2
 </return>
 </function>
 
@@ -6971,6 +7068,7 @@
 Convert from an X atom for a #GdkDisplay to the corresponding
 #GdkAtom.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -6985,7 +7083,6 @@
 </parameters>
 <return> the corresponding #GdkAtom.
 
-Since: 2.2
 </return>
 </function>
 
@@ -7084,7 +7181,7 @@
 </parameter_description>
 </parameter>
 <parameter name="options">
-<parameter_description> (allow-none): a #cairo_font_options_t, or %NULL to unset any
+<parameter_description> a #cairo_font_options_t, or %NULL to unset any
 previously set default font options.
 </parameter_description>
 </parameter>
@@ -7209,7 +7306,12 @@
 
 <function name="gdk_drag_drop_succeeded">
 <description>
-Return value: %TRUE if the drop was successful.
+Returns whether the dropped data has been successfully 
+transferred. This function is intended to be used while 
+handling a %GDK_DROP_FINISHED event, its return value is
+meaningless at other times.
+
+Since: 2.6
 
 </description>
 <parameters>
@@ -7220,7 +7322,6 @@
 </parameters>
 <return> %TRUE if the drop was successful.
 
-Since: 2.6
 </return>
 </function>
 
@@ -7443,7 +7544,7 @@
 </parameter_description>
 </parameter>
 <parameter name="sibling">
-<parameter_description> (allow-none): a #GdkWindow that is a sibling of @window, or %NULL
+<parameter_description> a #GdkWindow that is a sibling of @window, or %NULL
 </parameter_description>
 </parameter>
 <parameter name="above">
@@ -7456,7 +7557,12 @@
 
 <function name="gdk_x11_get_xatom_name">
 <description>
-Return value: name of the X atom; this string is owned by GTK+,
+Returns the name of an X atom for GDK's default display. This
+function is meant mainly for debugging, so for convenience, unlike
+&lt;function&gt;XAtomName()&lt;/function&gt; and gdk_atom_name(), the result 
+doesn't need to be freed. Also, this function will never return %NULL, 
+even if @xatom is invalid.
+
 
 </description>
 <parameters>
@@ -7488,7 +7594,13 @@
 
 <function name="gdk_keymap_get_entries_for_keycode">
 <description>
-Returns: %TRUE if there were any entries
+Returns the keyvals bound to @hardware_keycode.
+The Nth #GdkKeymapKey in @keys is bound to the Nth
+keyval in @keyvals. Free the returned arrays with g_free().
+When a keycode is pressed by the user, the keyval from
+this list of entries is selected by considering the effective
+keyboard group and level. See gdk_keymap_translate_keyboard_state().
+
 
 </description>
 <parameters>
@@ -7699,6 +7811,7 @@
 <description>
 Check to see if a window is destroyed..
 
+Since: 2.18
 
 </description>
 <parameters>
@@ -7709,7 +7822,6 @@
 </parameters>
 <return> %TRUE if the window is destroyed
 
-Since: 2.18
 </return>
 </function>
 
@@ -7717,6 +7829,7 @@
 <description>
 Gets the screen to which this visual belongs
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -7727,7 +7840,6 @@
 </parameters>
 <return> (transfer none): the screen to which this visual belongs.
 
-Since: 2.2
 </return>
 </function>
 
@@ -7735,6 +7847,7 @@
 <description>
 Finds out if a regions is the same as a rectangle.
 
+Since: 2.18
 
 </description>
 <parameters>
@@ -7749,7 +7862,6 @@
 </parameters>
 <return> %TRUE if @region and @rectangle are equal.
 
-Since: 2.18
 </return>
 </function>
 
@@ -7758,6 +7870,7 @@
 Deprecated equivalent of calling g_object_ref() on @drawable.
 (Drawables were not objects in previous versions of GDK.)
 
+Deprecated: 2.0: Use g_object_ref() instead.
 
 </description>
 <parameters>
@@ -7768,7 +7881,6 @@
 </parameters>
 <return> the same @drawable passed in
 
-Deprecated: 2.0: Use g_object_ref() instead.
 </return>
 </function>
 
@@ -7907,6 +8019,7 @@
 &lt;/para&gt;&lt;/listitem&gt;
 &lt;/itemizedlist&gt;
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -7921,7 +8034,6 @@
 </parameters>
 <return> a new #GdkCursor
 
-Since: 2.2
 </return>
 </function>
 
@@ -7991,7 +8103,11 @@
 
 <function name="gdk_display_supports_cursor_alpha">
 <description>
-Returns: whether cursors can have alpha channels.
+Returns %TRUE if cursors can use an 8bit alpha channel
+on @display. Otherwise, cursors are restricted to bilevel
+alpha (i.e. a mask).
+
+Since: 2.4
 
 </description>
 <parameters>
@@ -8002,13 +8118,13 @@
 </parameters>
 <return> whether cursors can have alpha channels.
 
-Since: 2.4
 </return>
 </function>
 
 <function name="gdk_x11_colormap_get_xdisplay">
 <description>
-Return value: an Xlib &lt;type&gt;Display*&lt;/type&gt;.
+Returns the display of a #GdkColormap.
+
 
 </description>
 <parameters>
@@ -8203,6 +8319,7 @@
 For example in the X backend, a native pixmap handle is an Xlib
 &lt;type&gt;XID&lt;/type&gt;.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -8218,7 +8335,6 @@
 <return> the #GdkPixmap wrapper for the native pixmap,
 or %NULL if there is none.
 
-Since: 2.2
 </return>
 </function>
 
@@ -8250,7 +8366,7 @@
 </parameter_description>
 </parameter>
 <parameter name="pixmap">
-<parameter_description> (allow-none): a #GdkPixmap, or %NULL
+<parameter_description> a #GdkPixmap, or %NULL
 </parameter_description>
 </parameter>
 <parameter name="parent_relative">
@@ -8291,18 +8407,21 @@
 Gets the default screen for the default display. (See
 gdk_display_get_default ()).
 
+Since: 2.2
 
 </description>
 <parameters>
 </parameters>
 <return> (transfer none): a #GdkScreen, or %NULL if there is no default display.
 
-Since: 2.2
 </return>
 </function>
 
 <function name="gdk_keymap_get_for_display">
 <description>
+Returns the #GdkKeymap attached to @display.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -8312,9 +8431,6 @@
 </parameter>
 </parameters>
 <return> the #GdkKeymap attached to @display.
-the #GdkKeymap attached to @display.
-
-Since: 2.2
 </return>
 </function>
 
@@ -8402,11 +8518,11 @@
 </parameter_description>
 </parameter>
 <parameter name="foreground">
-<parameter_description> (allow-none): foreground override color, or %NULL for none
+<parameter_description> foreground override color, or %NULL for none
 </parameter_description>
 </parameter>
 <parameter name="background">
-<parameter_description> (allow-none): background override color, or %NULL for none
+<parameter_description> background override color, or %NULL for none
 </parameter_description>
 </parameter>
 </parameters>
@@ -8437,6 +8553,7 @@
 For example in the X backend, a native pixmap handle is an Xlib
 &lt;type&gt;XID&lt;/type&gt;.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -8452,7 +8569,6 @@
 <return> the newly-created #GdkPixmap wrapper for the 
 native pixmap or %NULL if the pixmap has been destroyed.
 
-Since: 2.2
 </return>
 </function>
 
@@ -8483,6 +8599,7 @@
 Appends an event before the specified event, or if it isn't in
 the queue, onto the tail of the event queue.
 
+Since: 2.16
 
 </description>
 <parameters>
@@ -8501,13 +8618,14 @@
 </parameters>
 <return> the newly appended list node.
 
-Since: 2.16
 </return>
 </function>
 
 <function name="gdk_cursor_get_display">
 <description>
-Returns: the #GdkDisplay associated to @cursor
+Returns the display on which the #GdkCursor is defined.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -8518,7 +8636,6 @@
 </parameters>
 <return> the #GdkDisplay associated to @cursor
 
-Since: 2.2
 </return>
 </function>
 
@@ -8607,6 +8724,7 @@
 Determines the name to pass to gdk_display_open() to get
 a #GdkDisplay with this screen as the default screen.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -8617,7 +8735,6 @@
 </parameters>
 <return> a newly allocated string, free with g_free()
 
-Since: 2.2
 </return>
 </function>
 
@@ -8657,7 +8774,9 @@
 
 <function name="gdk_font_get_display">
 <description>
-Returns: the corresponding #GdkDisplay.
+Returns the #GdkDisplay for @font.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -8668,13 +8787,13 @@
 </parameters>
 <return> the corresponding #GdkDisplay.
 
-Since: 2.2
 </return>
 </function>
 
 <function name="gdk_x11_gc_get_xgc">
 <description>
-Return value: an Xlib &lt;type&gt;GC&lt;/type&gt;.
+Returns the X GC of a #GdkGC.
+
 
 </description>
 <parameters>
@@ -8735,6 +8854,7 @@
 <description>
 Test if the pointer is grabbed.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -8745,7 +8865,6 @@
 </parameters>
 <return> %TRUE if an active X pointer grab is in effect
 
-Since: 2.2
 </return>
 </function>
 
@@ -8753,6 +8872,7 @@
 <description>
 Gets the root window of @screen.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -8763,7 +8883,6 @@
 </parameters>
 <return> (transfer none): the root window
 
-Since: 2.2
 </return>
 </function>
 
@@ -8771,6 +8890,7 @@
 <description>
 Creates a new event of the given type. All fields are set to 0.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -8782,7 +8902,6 @@
 <return> a newly-allocated #GdkEvent. The returned #GdkEvent 
 should be freed with gdk_event_free().
 
-Since: 2.2
 </return>
 </function>
 
@@ -8806,6 +8925,7 @@
 <description>
 Gets the width in millimeters of the specified monitor, if available.
 
+Since: 2.14
 
 </description>
 <parameters>
@@ -8820,7 +8940,6 @@
 </parameters>
 <return> the width of the monitor, or -1 if not available
 
-Since: 2.14
 </return>
 </function>
 
@@ -8920,7 +9039,10 @@
 <function name="gdk_x11_colormap_foreign_new">
 <description>
 If xcolormap refers to a colormap previously known to GTK+,
-Return value: the #GdkColormap object for @xcolormap.
+returns a new reference to the existing #GdkColormap object,
+otherwise creates a new GdkColormap object and returns that
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -8939,7 +9061,6 @@
 reference to the object will only free the #GdkColoramp
 object and not call XFreeColormap()
 
-Since: 2.2
 </return>
 </function>
 
@@ -9075,7 +9196,8 @@
 
 <function name="gdkx_visual_get">
 <description>
-Return value: the #GdkVisual.
+Returns a #GdkVisual corresponding to a X visual. 
+
 
 </description>
 <parameters>
@@ -9188,7 +9310,9 @@
 
 <function name="gdk_devices_list">
 <description>
-Return value: a list of #GdkDevice
+Returns the list of available input devices for the default display.
+The list is statically allocated and should not be freed.
+
 
 </description>
 <parameters>
@@ -9226,7 +9350,8 @@
 
 <function name="gdk_x11_drawable_get_xid">
 <description>
-Return value: the ID of @drawable's X resource.
+Returns the X resource (window or pixmap) belonging to a #GdkDrawable.
+
 
 </description>
 <parameters>
@@ -9248,7 +9373,7 @@
 </description>
 <parameters>
 <parameter name="dest">
-<parameter_description> (allow-none): Destination pixbuf, or %NULL if a new pixbuf should be created.
+<parameter_description> Destination pixbuf, or %NULL if a new pixbuf should be created.
 </parameter_description>
 </parameter>
 <parameter name="src">
@@ -9256,7 +9381,7 @@
 </parameter_description>
 </parameter>
 <parameter name="cmap">
-<parameter_description> (allow-none): A colormap, or %NULL to use the one for @src
+<parameter_description> A colormap, or %NULL to use the one for @src
 </parameter_description>
 </parameter>
 <parameter name="src_x">
@@ -9321,7 +9446,10 @@
 
 <function name="gdk_display_list_devices">
 <description>
-Return value: a list of #GdkDevice
+Returns the list of available input devices attached to @display.
+The list is statically allocated and should not be freed.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -9332,7 +9460,6 @@
 </parameters>
 <return> a list of #GdkDevice
 
-Since: 2.2
 </return>
 </function>
 
@@ -9663,7 +9790,22 @@
 
 <function name="gdk_screen_get_active_window">
 <description>
-Return value: the currently active window, or %NULL.
+Returns the screen's currently active window.
+
+On X11, this is done by inspecting the _NET_ACTIVE_WINDOW property
+on the root window, as described in the &lt;ulink
+url=&quot;http://www.freedesktop.org/Standards/wm-spec&quot;&gt;Extended Window
+Manager Hints&lt;/ulink&gt;. If there is no currently currently active
+window, or the window manager does not support the
+_NET_ACTIVE_WINDOW hint, this function returns %NULL.
+
+On other platforms, this function may return %NULL, depending on whether
+it is implementable on that platform.
+
+The returned window should be unrefed using g_object_unref() when
+no longer needed.
+
+Since: 2.10
 
 </description>
 <parameters>
@@ -9674,7 +9816,6 @@
 </parameters>
 <return> the currently active window, or %NULL.
 
-Since: 2.10
 </return>
 </function>
 
@@ -9682,6 +9823,7 @@
 <description>
 Allocates a single color from a colormap.
 
+Deprecated: 2.2: Use gdk_colormap_alloc_color() instead.
 
 </description>
 <parameters>
@@ -9697,7 +9839,6 @@
 </parameters>
 <return> %TRUE if the allocation succeeded.
 
-Deprecated: 2.2: Use gdk_colormap_alloc_color() instead.
 </return>
 </function>
 
@@ -9705,6 +9846,7 @@
 <description>
 Converts from UTF-8 to compound text. 
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -9737,7 +9879,6 @@
 <return> %TRUE if the conversion succeeded, otherwise
 %FALSE.
 
-Since: 2.2
 </return>
 </function>
 
@@ -9746,6 +9887,7 @@
 Establish a callback when a condition becomes true on
 a file descriptor.
 
+Deprecated: 2.14: Use g_io_add_watch() on a #GIOChannel
 
 </description>
 <parameters>
@@ -9769,7 +9911,6 @@
 <return> a tag that can later be used as an argument to
 gdk_input_remove().
 
-Deprecated: 2.14: Use g_io_add_watch() on a #GIOChannel
 </return>
 </function>
 
@@ -9777,6 +9918,7 @@
 <description>
 Gets any options previously set with gdk_screen_set_font_options().
 
+Since: 2.10
 
 </description>
 <parameters>
@@ -9788,7 +9930,6 @@
 <return> the current font options, or %NULL if no default
 font options have been set.
 
-Since: 2.10
 </return>
 </function>
 
@@ -9800,6 +9941,7 @@
 it can render to any colormap and visual. So there's no need to
 call this function.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -9810,7 +9952,6 @@
 </parameters>
 <return> the preferred colormap
 
-Since: 2.2
 </return>
 </function>
 
@@ -9943,20 +10084,20 @@
 </parameter_description>
 </parameter>
 <parameter name="screen">
-<parameter_description> (allow-none): location to store the screen that the
+<parameter_description> location to store the screen that the
 cursor is on, or %NULL.
 </parameter_description>
 </parameter>
 <parameter name="x">
-<parameter_description> (allow-none): (out): location to store root window X coordinate of pointer, or %NULL.
+<parameter_description> location to store root window X coordinate of pointer, or %NULL.
 </parameter_description>
 </parameter>
 <parameter name="y">
-<parameter_description> (allow-none): (out): location to store root window Y coordinate of pointer, or %NULL.
+<parameter_description> location to store root window Y coordinate of pointer, or %NULL.
 </parameter_description>
 </parameter>
 <parameter name="mask">
-<parameter_description> (allow-none): (out): location to store current modifier mask, or %NULL
+<parameter_description> location to store current modifier mask, or %NULL
 </parameter_description>
 </parameter>
 </parameters>
@@ -10231,7 +10372,13 @@
 
 <function name="gdkx_colormap_get">
 <description>
-Return value: the existing #GdkColormap object if it was
+Returns a #GdkColormap corresponding to a X colormap;
+this function only works if the colormap is already
+known to GTK+ (a colormap created by GTK+ or the default
+colormap for the screen), since GTK+ 
+
+Always use gdk_x11_colormap_foreign_new() instead.
+
 
 </description>
 <parameters>
@@ -10274,11 +10421,11 @@
 </parameter_description>
 </parameter>
 <parameter name="dest_window">
-<parameter_description> (out): location to store the destination window in.
+<parameter_description> location to store the destination window in.
 </parameter_description>
 </parameter>
 <parameter name="protocol">
-<parameter_description> (out): location to store the DND protocol in.
+<parameter_description> location to store the DND protocol in.
 </parameter_description>
 </parameter>
 </parameters>
@@ -10294,6 +10441,7 @@
 
 Some backends may not support native child windows.
 
+Since: 2.18
 
 </description>
 <parameters>
@@ -10304,7 +10452,6 @@
 </parameters>
 <return> %TRUE if the window has a native window, %FALSE otherwise
 
-Since: 2.18
 </return>
 </function>
 
@@ -10334,6 +10481,7 @@
 <description>
 Gets the screen for which this colormap was created.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -10344,7 +10492,6 @@
 </parameters>
 <return> the screen for which this colormap was created.
 
-Since: 2.2
 </return>
 </function>
 
@@ -10383,6 +10530,7 @@
 Gets the next #GdkEvent to be processed for @display, fetching events from the
 windowing system if necessary.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -10394,7 +10542,6 @@
 <return> the next #GdkEvent to be processed, or %NULL if no events
 are pending. The returned #GdkEvent should be freed with gdk_event_free().
 
-Since: 2.2
 </return>
 </function>
 
@@ -10442,6 +10589,7 @@
 <description>
 Gets the name of the display.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -10453,7 +10601,6 @@
 <return> a string representing the display name. This string is owned
 by GDK and should not be modified or freed.
 
-Since: 2.2
 </return>
 </function>
 
@@ -10530,7 +10677,11 @@
 
 <function name="gdk_x11_get_xatom_by_name_for_display">
 <description>
-Return value: a X atom for a #GdkDisplay
+Returns the X atom for a #GdkDisplay corresponding to @atom_name.
+This function caches the result, so if called repeatedly it is much
+faster than XInternAtom(), which is a round trip to the server each time.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -10545,7 +10696,6 @@
 </parameters>
 <return> a X atom for a #GdkDisplay
 
-Since: 2.2
 </return>
 </function>
 
@@ -10579,7 +10729,11 @@
 
 <function name="gdk_screen_get_monitor_plug_name">
 <description>
-Returns: a newly-allocated string containing the name of the monitor,
+Returns the output name of the specified monitor.
+Usually something like VGA, DVI, or TV, not the actual
+product name of the display device.
+
+Since: 2.14
 
 </description>
 <parameters>
@@ -10595,7 +10749,6 @@
 <return> a newly-allocated string containing the name of the monitor,
 or %NULL if the name cannot be determined
 
-Since: 2.14
 </return>
 </function>
 
@@ -10627,7 +10780,7 @@
 </parameter_description>
 </parameter>
 <parameter name="mask">
-<parameter_description> (allow-none): shape mask, or %NULL
+<parameter_description> shape mask, or %NULL
 </parameter_description>
 </parameter>
 <parameter name="x">
@@ -10679,7 +10832,8 @@
 
 <function name="gdk_x11_colormap_get_xcolormap">
 <description>
-Return value: an Xlib &lt;type&gt;Colormap&lt;/type&gt;.
+Returns the X colormap belonging to a #GdkColormap.
+
 
 </description>
 <parameters>
@@ -10754,7 +10908,12 @@
 
 <function name="gdk_display_supports_clipboard_persistence">
 <description>
-Returns: %TRUE if the display supports clipboard persistance.
+Returns whether the speicifed display supports clipboard
+persistance; i.e. if it's possible to store the clipboard data after an
+application has quit. On X11 this checks if a clipboard daemon is
+running.
+
+Since: 2.6
 
 </description>
 <parameters>
@@ -10765,7 +10924,6 @@
 </parameters>
 <return> %TRUE if the display supports clipboard persistance.
 
-Since: 2.6
 </return>
 </function>
 
@@ -10788,7 +10946,9 @@
 
 <function name="gdk_color_white">
 <description>
-Return value: %TRUE if the allocation succeeded.
+Returns the white color for a given colormap. The resulting
+value has already allocated been allocated. 
+
 
 </description>
 <parameters>
@@ -10830,6 +10990,7 @@
 Establish a callback when a condition becomes true on
 a file descriptor.
 
+Deprecated: 2.14: Use g_io_add_watch_full() on a #GIOChannel
 
 </description>
 <parameters>
@@ -10858,7 +11019,6 @@
 <return> a tag that can later be used as an argument to
 gdk_input_remove().
 
-Deprecated: 2.14: Use g_io_add_watch_full() on a #GIOChannel
 </return>
 </function>
 
@@ -10868,6 +11028,7 @@
 function for
 &lt;literal&gt;gdk_display_manager_get_default_display (gdk_display_manager_get ())&lt;/literal&gt;.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -10875,7 +11036,6 @@
 <return> (transfer none): a #GdkDisplay, or %NULL if there is no default
 display.
 
-Since: 2.2
 </return>
 </function>
 
@@ -10886,6 +11046,7 @@
 there is no custom cursor set on the specified window, and it is
 using the cursor for its parent window.
 
+Since: 2.18
 
 </description>
 <parameters>
@@ -10898,7 +11059,6 @@
 by the #GdkWindow and should not be unreferenced directly. Use
 gdk_window_set_cursor() to unset the cursor of the window
 
-Since: 2.18
 </return>
 </function>
 
@@ -10950,7 +11110,8 @@
 
 <function name="gdk_keymap_get_direction">
 <description>
-Returns: %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL 
+Returns the direction of effective layout of the keymap.
+
 
 </description>
 <parameters>
@@ -10998,6 +11159,7 @@
 applications, though the amount of data is limited to 20 bytes on
 X11, and to just four bytes on Windows.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -11016,7 +11178,6 @@
 </parameters>
 <return> non-zero on success.
 
-Since: 2.2
 </return>
 </function>
 
@@ -11143,6 +11304,10 @@
 
 <function name="gdk_screen_get_monitor_at_window">
 <description>
+Returns the number of the monitor in which the largest area of the 
+bounding rectangle of @window resides.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -11158,16 +11323,14 @@
 <return> the monitor number in which most of @window is located,
 or if @window does not intersect any monitors, a monitor,
 close to @window.
-the number of the monitor in which the largest area of the 
-bounding rectangle of @window resides.
-
-Since: 2.2
 </return>
 </function>
 
 <function name="gdk_keymap_get_caps_lock_state">
 <description>
-Returns: %TRUE if Caps Lock is on
+Returns whether the Caps Lock modifer is locked.
+
+Since: 2.16
 
 </description>
 <parameters>
@@ -11178,7 +11341,6 @@
 </parameters>
 <return> %TRUE if Caps Lock is on
 
-Since: 2.16
 </return>
 </function>
 
@@ -11208,6 +11370,7 @@
 <description>
 Gets the singleton #GdkDisplayManager object.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -11215,7 +11378,6 @@
 <return> (transfer none): The global #GdkDisplayManager singleton; gdk_parse_pargs(),
 gdk_init(), or gdk_init_check() must have been called first.
 
-Since: 2.2
 </return>
 </function>
 
@@ -11299,6 +11461,7 @@
 Gets the width of @screen in millimeters. 
 Note that on some X servers this value will not be correct.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -11309,12 +11472,16 @@
 </parameters>
 <return> the width of @screen in millimeters.
 
-Since: 2.2
 </return>
 </function>
 
 <function name="gdk_screen_set_resolution">
 <description>
+Sets the resolution for font handling on the screen. This is a
+scale factor between points specified in a #PangoFontDescription
+and cairo units. The default value is 96, meaning that a 10 point
+font will be 13 units high. (10 * 96. / 72. = 13.3).
+
 Since: 2.10
 
 </description>
@@ -11326,11 +11493,6 @@
 <parameter name="dpi">
 <parameter_description> the resolution in &quot;dots per inch&quot;. (Physical inches aren't actually
 involved; the terminology is conventional.)
- 
-Sets the resolution for font handling on the screen. This is a
-scale factor between points specified in a #PangoFontDescription
-and cairo units. The default value is 96, meaning that a 10 point
-font will be 13 units high. (10 * 96. / 72. = 13.3).
 </parameter_description>
 </parameter>
 </parameters>
@@ -11368,26 +11530,6 @@
 <return></return>
 </function>
 
-<function name="GdkDisplayManager">
-<description>
-The ::display_opened signal is emitted when a display is opened.
-
-Since: 2.2
-
-</description>
-<parameters>
-<parameter name="display_manager">
-<parameter_description> the object on which the signal is emitted
-</parameter_description>
-</parameter>
-<parameter name="display">
-<parameter_description> the opened display
-</parameter_description>
-</parameter>
-</parameters>
-<return></return>
-</function>
-
 <function name="gdk_keyval_to_unicode">
 <description>
 Convert from a GDK key symbol to the corresponding ISO10646 (Unicode)
@@ -11481,6 +11623,7 @@
 For example in the X backend, a native window handle is an Xlib
 &lt;type&gt;XID&lt;/type&gt;.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -11496,7 +11639,6 @@
 <return> the #GdkWindow wrapper for the native window, 
 or %NULL if there is none.
 
-Since: 2.2
 </return>
 </function>
 
@@ -11506,6 +11648,7 @@
 results of gdk_pango_renderer_get_default() rather than creating a new
 renderer.
 
+Since: 2.6
 
 </description>
 <parameters>
@@ -11516,7 +11659,6 @@
 </parameters>
 <return> a newly created #PangoRenderer. Free with g_object_unref().
 
-Since: 2.6
 </return>
 </function>
 
@@ -11524,6 +11666,7 @@
 <description>
 Gets the startup notification ID for a display.
 
+Since: 2.12
 
 </description>
 <parameters>
@@ -11534,7 +11677,6 @@
 </parameters>
 <return> the startup notification ID for @display
 
-Since: 2.12
 </return>
 </function>
 
@@ -11555,6 +11697,7 @@
 You can monitor the window_manager_changed signal on #GdkScreen to detect
 a window manager change.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -11569,13 +11712,13 @@
 </parameters>
 <return> %TRUE if the window manager supports @property
 
-Since: 2.2
 </return>
 </function>
 
 <function name="gdk_device_get_core_pointer">
 <description>
-Return value: the core pointer device; this is owned by the
+Returns the core pointer device for the default display.
+
 
 </description>
 <parameters>
@@ -11598,6 +11741,7 @@
 ever unload the module again (e.g. do not use this function in
 GTK+ theme engines).
 
+Since: 2.10
 
 </description>
 <parameters>
@@ -11608,7 +11752,6 @@
 </parameters>
 <return> the atom corresponding to @atom_name
 
-Since: 2.10
 </return>
 </function>
 
@@ -11620,6 +11763,7 @@
 process if a foreign window was previously created for that
 window, but a new foreign window will never be created by this call. 
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -11636,7 +11780,6 @@
 window known to the current process, the #GdkWindow that owns the 
 selection, otherwise %NULL.
 
-Since: 2.2
 </return>
 </function>
 
@@ -11669,7 +11812,7 @@
 </parameter_description>
 </parameter>
 <parameter name="events">
-<parameter_description> (array length=n_events) (out) (transfer none): location to store a newly-allocated array of #GdkTimeCoord, or %NULL
+<parameter_description> location to store a newly-allocated array of #GdkTimeCoord, or %NULL
 </parameter_description>
 </parameter>
 <parameter name="n_events">
@@ -11801,6 +11944,7 @@
 
 See gdk_threads_add_idle_full().
 
+Since: 2.12
 
 </description>
 <parameters>
@@ -11815,7 +11959,6 @@
 </parameters>
 <return> the ID (greater than 0) of the event source.
 
-Since: 2.12
 </return>
 </function>
 
@@ -11900,27 +12043,6 @@
 <return></return>
 </function>
 
-<function name="GdkDisplay">
-<description>
-The ::closed signal is emitted when the connection to the windowing
-system for @display is closed.
-
-Since: 2.2
-
-</description>
-<parameters>
-<parameter name="display">
-<parameter_description> the object on which the signal is emitted
-</parameter_description>
-</parameter>
-<parameter name="is_error">
-<parameter_description> %TRUE if the display was closed due to an error
-</parameter_description>
-</parameter>
-</parameters>
-<return></return>
-</function>
-
 <function name="gdk_window_foreign_new">
 <description>
 Wraps a native window for the default display in a #GdkWindow.
@@ -12008,7 +12130,10 @@
 
 <function name="gdk_x11_get_xatom_by_name">
 <description>
-Return value: a X atom for GDK's default display.
+Returns the X atom for GDK's default display corresponding to @atom_name.
+This function caches the result, so if called repeatedly it is much
+faster than XInternAtom(), which is a round trip to the server each time.
+
 
 </description>
 <parameters>
@@ -12068,6 +12193,7 @@
 between different expose events. 
 &lt;/para&gt;&lt;/note&gt;
 
+Since: 2.8
 
 </description>
 <parameters>
@@ -12079,7 +12205,6 @@
 <return> A newly created Cairo context. Free with
 cairo_destroy() when you are done drawing.
 
-Since: 2.8
 </return>
 </function>
 
@@ -12162,7 +12287,8 @@
 
 <function name="gdk_colormap_get_visual">
 <description>
-Return value: the visual of the colormap.
+Returns the visual for which a given colormap was created.
+
 
 </description>
 <parameters>
@@ -12196,7 +12322,10 @@
 
 <function name="gdk_screen_get_height_mm">
 <description>
-Returns: the heigth of @screen in millimeters.
+Returns the height of @screen in millimeters. 
+Note that on some X servers this value will not be correct.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -12207,13 +12336,13 @@
 </parameters>
 <return> the heigth of @screen in millimeters.
 
-Since: 2.2
 </return>
 </function>
 
 <function name="gdk_x11_gc_get_xdisplay">
 <description>
-Return value: an Xlib &lt;type&gt;Display*&lt;/type&gt;.
+Returns the display of a #GdkGC.
+
 
 </description>
 <parameters>
@@ -12399,7 +12528,14 @@
 
 <function name="gdk_screen_is_composited">
 <description>
-Return value: Whether windows with RGBA visuals can reasonably be
+Returns whether windows with an RGBA visual can reasonably
+be expected to have their alpha channel drawn correctly on
+the screen.
+
+On X11 this function returns whether a compositing manager is
+compositing @screen.
+
+Since: 2.10
 
 </description>
 <parameters>
@@ -12411,7 +12547,6 @@
 <return> Whether windows with RGBA visuals can reasonably be
 expected to have their alpha channels drawn correctly on the screen.
 
-Since: 2.10
 </return>
 </function>
 
@@ -12474,7 +12609,7 @@
 </description>
 <parameters>
 <parameter name="keymap">
-<parameter_description> (allow-none): a #GdkKeymap, or %NULL to use the default
+<parameter_description> a #GdkKeymap, or %NULL to use the default
 </parameter_description>
 </parameter>
 <parameter name="hardware_keycode">
@@ -12490,19 +12625,19 @@
 </parameter_description>
 </parameter>
 <parameter name="keyval">
-<parameter_description> (out) (allow-none): return location for keyval, or %NULL
+<parameter_description> return location for keyval, or %NULL
 </parameter_description>
 </parameter>
 <parameter name="effective_group">
-<parameter_description> (out) (allow-none): return location for effective group, or %NULL
+<parameter_description> return location for effective group, or %NULL
 </parameter_description>
 </parameter>
 <parameter name="level">
-<parameter_description> (out) (allow-none):  return location for level, or %NULL
+<parameter_description>  return location for level, or %NULL
 </parameter_description>
 </parameter>
 <parameter name="consumed_modifiers">
-<parameter_description> (out) (allow-none):  return location for modifiers that were used to
+<parameter_description>  return location for modifiers that were used to
 determine the group or level, or %NULL
 </parameter_description>
 </parameter>
@@ -12585,7 +12720,7 @@
 </parameter_description>
 </parameter>
 <parameter name="icon_name">
-<parameter_description> (allow-none): an icon name, or %NULL
+<parameter_description> an icon name, or %NULL
 </parameter_description>
 </parameter>
 </parameters>
@@ -12679,6 +12814,7 @@
 This is used in the #GtkText and #GtkCList widgets in GTK+ to make sure any
 GraphicsExpose events are handled before the widget is scrolled.
 
+Deprecated: 2.18:
 
 </description>
 <parameters>
@@ -12690,13 +12826,13 @@
 <return>  a #GdkEventExpose if a GraphicsExpose was received, or %NULL if a
 NoExpose event was received.
 
-Deprecated: 2.18:
 </return>
 </function>
 
 <function name="gdk_x11_visual_get_xvisual">
 <description>
-Return value: an Xlib &lt;type&gt;Visual*&lt;/type&gt;.
+Returns the X visual belonging to a #GdkVisual.
+
 
 </description>
 <parameters>
@@ -12717,6 +12853,7 @@
 event recorder. Applications should never have any
 reason to use this facility.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -12733,7 +12870,6 @@
 </parameters>
 <return> the previous pointer hook table
 
-Since: 2.2
 </return>
 </function>
 
@@ -12756,7 +12892,7 @@
 </parameter_description>
 </parameter>
 <parameter name="icon">
-<parameter_description> (allow-none): a #GIcon, or %NULL
+<parameter_description> a #GIcon, or %NULL
 </parameter_description>
 </parameter>
 </parameters>
@@ -12875,7 +13011,14 @@
 
 <function name="_gdk_drawable_get_subwindow_scratch_gc">
 <description>
-Return value: A #GdkGC suitable for drawing on @drawable
+Returns a #GdkGC suitable for drawing on @drawable. The #GdkGC has
+the standard values for @drawable, except for the graphics_exposures
+field which is %TRUE and the subwindow mode which is %GDK_INCLUDE_INFERIORS.
+
+The foreground color of the returned #GdkGC is undefined. The #GdkGC
+must not be altered in any way, except to change its foreground color.
+
+Since: 2.18
 
 </description>
 <parameters>
@@ -12886,7 +13029,6 @@
 </parameters>
 <return> A #GdkGC suitable for drawing on @drawable
 
-Since: 2.18
 </return>
 </function>
 
@@ -12934,6 +13076,7 @@
 <description>
 Gets the number of screen managed by the @display.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -12944,7 +13087,6 @@
 </parameters>
 <return> number of screens.
 
-Since: 2.2
 </return>
 </function>
 
@@ -12952,6 +13094,7 @@
 <description>
 Deprecated function; use g_object_ref() instead.
 
+Deprecated: 2.0: Use g_object_ref() instead.
 
 </description>
 <parameters>
@@ -12962,7 +13105,6 @@
 </parameters>
 <return> the image
 
-Deprecated: 2.0: Use g_object_ref() instead.
 </return>
 </function>
 
@@ -12970,6 +13112,7 @@
 <description>
 Sets the #GdkWindow @owner as the current owner of the selection @selection.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -13001,7 +13144,6 @@
 <return> %TRUE if the selection owner was successfully changed to owner,
 otherwise %FALSE. 
 
-Since: 2.2
 </return>
 </function>
 
@@ -13028,7 +13170,8 @@
 
 <function name="gdk_x11_image_get_ximage">
 <description>
-Return value: an &lt;type&gt;XImage*&lt;/type&gt;.
+Returns the X image belonging to a #GdkImage.
+
 
 </description>
 <parameters>
@@ -13045,6 +13188,7 @@
 <description>
 Gets the height of @screen in pixels
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -13055,7 +13199,6 @@
 </parameters>
 <return> the height of @screen in pixels.
 
-Since: 2.2
 </return>
 </function>
 
@@ -13073,17 +13216,17 @@
 </parameter_description>
 </parameter>
 <parameter name="x">
-<parameter_description> (out) (allow-none): return location for X coordinate of pointer or %NULL to not
+<parameter_description> return location for X coordinate of pointer or %NULL to not
 return the X coordinate
 </parameter_description>
 </parameter>
 <parameter name="y">
-<parameter_description> (out) (allow-none):  return location for Y coordinate of pointer or %NULL to not
+<parameter_description>  return location for Y coordinate of pointer or %NULL to not
 return the Y coordinate
 </parameter_description>
 </parameter>
 <parameter name="mask">
-<parameter_description> (out) (allow-none): return location for modifier mask or %NULL to not return the
+<parameter_description> return location for modifier mask or %NULL to not return the
 modifier mask
 </parameter_description>
 </parameter>
@@ -13365,13 +13508,13 @@
 <description>
 Creates a new #GdkAppLaunchContext.
 
+Since: 2.14
 
 </description>
 <parameters>
 </parameters>
 <return> a new #GdkAppLaunchContext
 
-Since: 2.14
 </return>
 </function>
 
@@ -13397,6 +13540,7 @@
 if the window under the mouse pointer is not known to GDK (for example, 
 belongs to another application).
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -13405,25 +13549,30 @@
 </parameter_description>
 </parameter>
 <parameter name="win_x">
-<parameter_description> (out) (allow-none): return location for x coordinate of the pointer location relative
+<parameter_description> return location for x coordinate of the pointer location relative
 to the window origin, or %NULL
 </parameter_description>
 </parameter>
 <parameter name="win_y">
-<parameter_description> (out) (allow-none): return location for y coordinate of the pointer location relative
+<parameter_description> return location for y coordinate of the pointer location relative
  &amp;    to the window origin, or %NULL
 </parameter_description>
 </parameter>
 </parameters>
 <return> (transfer none): the window under the mouse pointer, or %NULL
 
-Since: 2.2
 </return>
 </function>
 
 <function name="gdk_cursor_get_image">
 <description>
-Returns: a #GdkPixbuf representing @cursor, or %NULL
+Returns a #GdkPixbuf with the image used to display the cursor.
+
+Note that depending on the capabilities of the windowing system and 
+on the cursor, GDK may not be able to obtain the image data. In this 
+case, %NULL is returned.
+
+Since: 2.8
 
 </description>
 <parameters>
@@ -13434,7 +13583,6 @@
 </parameters>
 <return> a #GdkPixbuf representing @cursor, or %NULL
 
-Since: 2.8
 </return>
 </function>
 
@@ -13662,7 +13810,12 @@
 
 <function name="gdk_x11_get_xatom_name_for_display">
 <description>
-Return value: name of the X atom; this string is owned by GDK,
+Returns the name of an X atom for its display. This
+function is meant mainly for debugging, so for convenience, unlike
+XAtomName() and gdk_atom_name(), the result doesn't need to
+be freed. 
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -13678,7 +13831,6 @@
 <return> name of the X atom; this string is owned by GDK,
 so it shouldn't be modifed or freed. 
 
-Since: 2.2
 </return>
 </function>
 
@@ -13881,6 +14033,7 @@
 For setting an overall opacity for a top-level window, see
 gdk_window_set_opacity().
 
+Since: 2.8
 
 </description>
 <parameters>
@@ -13892,7 +14045,6 @@
 <return> (transfer none): a colormap to use for windows with
 an alpha channel or %NULL if the capability is not available.
 
-Since: 2.8
 </return>
 </function>
 
@@ -14019,6 +14171,7 @@
 
 Call g_list_free() on the return value when you're finished with it.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -14030,7 +14183,6 @@
 <return> a list of visuals; the list must be freed, but not its 
 contents
 
-Since: 2.2
 </return>
 </function>
 
@@ -14055,7 +14207,9 @@
 
 <function name="gdk_x11_screen_get_window_manager_name">
 <description>
-Return value: the name of the window manager screen @screen, or 
+Returns the name of the window manager for @screen. 
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -14068,13 +14222,18 @@
 &quot;unknown&quot; if the window manager is unknown. The string is owned by GDK
 and should not be freed.
 
-Since: 2.2
 </return>
 </function>
 
 <function name="gdk_display_supports_composite">
 <description>
-Returns: %TRUE if windows may be composited.
+Returns %TRUE if gdk_window_set_composited() can be used
+to redirect drawing on the window using compositing.
+
+Currently this only works on X11 with XComposite and
+XDamage extensions available.
+
+Since: 2.12
 
 </description>
 <parameters>
@@ -14085,13 +14244,13 @@
 </parameters>
 <return> %TRUE if windows may be composited.
 
-Since: 2.12
 </return>
 </function>
 
 <function name="gdk_drag_get_selection">
 <description>
-Return value: the selection atom.
+Returns the selection atom for the current source window.
+
 
 </description>
 <parameters>
@@ -14126,11 +14285,11 @@
 </description>
 <parameters>
 <parameter name="argc">
-<parameter_description> (inout):
+<parameter_description>
 </parameter_description>
 </parameter>
 <parameter name="argv">
-<parameter_description> (array length=argc) (inout):
+<parameter_description>
 </parameter_description>
 </parameter>
 </parameters>
@@ -14204,6 +14363,7 @@
 Creates a new cursor by looking up @name in the current cursor
 theme. 
 
+Since: 2.8
 
 </description>
 <parameters>
@@ -14219,7 +14379,6 @@
 <return> a new #GdkCursor, or %NULL if there is no cursor with 
 the given name 
 
-Since: 2.8
 </return>
 </function>
 
@@ -14328,7 +14487,23 @@
 
 <function name="gdk_screen_get_window_stack">
 <description>
-Return value: a list of #GdkWindow&lt;!-- --&gt;s for the current window stack,
+Returns a #GList of #GdkWindow&lt;!-- --&gt;s representing the current
+window stack.
+
+On X11, this is done by inspecting the _NET_CLIENT_LIST_STACKING
+property on the root window, as described in the &lt;ulink
+url=&quot;http://www.freedesktop.org/Standards/wm-spec&quot;&gt;Extended Window
+Manager Hints&lt;/ulink&gt;. If the window manager does not support the
+_NET_CLIENT_LIST_STACKING hint, this function returns %NULL.
+
+On other platforms, this function may return %NULL, depending on whether
+it is implementable on that platform.
+
+The returned list is newly allocated and owns references to the
+windows it contains, so it should be freed using g_list_free() and
+its windows unrefed using g_object_unref() when no longer needed.
+
+Since: 2.10
 
 </description>
 <parameters>
@@ -14340,7 +14515,6 @@
 <return> a list of #GdkWindow&lt;!-- --&gt;s for the current window stack,
 or %NULL.
 
-Since: 2.10
 </return>
 </function>
 
@@ -14350,6 +14524,7 @@
 alpha channel. See the docs for gdk_screen_get_rgba_colormap()
 for caveats.
 
+Since: 2.8
 
 </description>
 <parameters>
@@ -14361,7 +14536,6 @@
 <return> (transfer none): a visual to use for windows with an
 alpha channel or %NULL if the capability is not available.
 
-Since: 2.8
 </return>
 </function>
 
@@ -14420,7 +14594,7 @@
 </parameter_description>
 </parameter>
 <parameter name="drawable">
-<parameter_description> (allow-none): the new target drawable, or %NULL
+<parameter_description> the new target drawable, or %NULL
 </parameter_description>
 </parameter>
 </parameters>
@@ -14473,24 +14647,6 @@
 <return></return>
 </function>
 
-<function name="GdkKeymap">
-<description>
-The ::state-changed signal is emitted when the state of the
-keyboard changes, e.g when Caps Lock is turned on or off.
-See gdk_keymap_get_caps_lock_state().
-
-Since: 2.16
-
-</description>
-<parameters>
-<parameter name="keymap">
-<parameter_description> the object on which the signal is emitted
-</parameter_description>
-</parameter>
-</parameters>
-<return></return>
-</function>
-
 <function name="gdk_get_show_events">
 <description>
 Gets whether event debugging output is enabled.
@@ -14539,11 +14695,11 @@
 </description>
 <parameters>
 <parameter name="win_x">
-<parameter_description> (out) (allow-none): return location for origin of the window under the pointer
+<parameter_description> return location for origin of the window under the pointer
 </parameter_description>
 </parameter>
 <parameter name="win_y">
-<parameter_description> (out) (allow-none): return location for origin of the window under the pointer
+<parameter_description> return location for origin of the window under the pointer
 </parameter_description>
 </parameter>
 </parameters>
@@ -14555,6 +14711,7 @@
 <description>
 This function returns the type hint set for a window.
 
+Since: 2.10
 
 </description>
 <parameters>
@@ -14565,7 +14722,6 @@
 </parameters>
 <return> The type hint set for @window
 
-Since: 2.10
 </return>
 </function>
 
@@ -14596,6 +14752,7 @@
 Gets the resolution for font handling on the screen; see
 gdk_screen_set_resolution() for full details.
 
+Since: 2.10
 
 </description>
 <parameters>
@@ -14607,7 +14764,6 @@
 <return> the current resolution, or -1 if no resolution
 has been set.
 
-Since: 2.10
 </return>
 </function>
 
@@ -14671,6 +14827,9 @@
 
 <function name="gdk_x11_display_get_xdisplay">
 <description>
+Returns the X display of a #GdkDisplay.
+
+Since: 2.2
 
 </description>
 <parameters>
@@ -14680,9 +14839,6 @@
 </parameter>
 </parameters>
 <return> an X display.
-the X display of a #GdkDisplay.
-
-Since: 2.2
 </return>
 </function>
 
@@ -14707,6 +14863,7 @@
 @image. If @image is %NULL, creates a new image of size @width x @height
 and copies into that. See gdk_drawable_get_image() for further details.
 
+Since: 2.4
 
 </description>
 <parameters>
@@ -14715,7 +14872,7 @@
 </parameter_description>
 </parameter>
 <parameter name="image">
-<parameter_description> (allow-none): a #GdkDrawable, or %NULL if a new @image should be created.
+<parameter_description> a #GdkDrawable, or %NULL if a new @image should be created.
 </parameter_description>
 </parameter>
 <parameter name="src_x">
@@ -14746,7 +14903,6 @@
 <return> @image, or a new a #GdkImage containing the contents
 of @drawable
 
-Since: 2.4
 </return>
 </function>
 
@@ -14821,13 +14977,13 @@
 The returned list should be freed with g_list_free(), but
 its elements need not be freed.
 
+Deprecated: 2.16: Use gdk_screen_get_toplevel_windows() instead.
 
 </description>
 <parameters>
 </parameters>
 <return> list of toplevel windows, free with g_list_free()
 
-Deprecated: 2.16: Use gdk_screen_get_toplevel_windows() instead.
 </return>
 </function>
 
@@ -14837,6 +14993,7 @@
 See g_timeout_add_seconds_full() for a discussion of why it is
 a good idea to use this function if you don't need finer granularity.
 
+Since: 2.14
 
 </description>
 <parameters>
@@ -14858,13 +15015,12 @@
 </parameter_description>
 </parameter>
 <parameter name="notify">
-<parameter_description> (allow-none):   function to call when the timeout is removed, or %NULL
+<parameter_description>   function to call when the timeout is removed, or %NULL
 </parameter_description>
 </parameter>
 </parameters>
 <return> the ID (greater than 0) of the event source.
 
-Since: 2.14
 </return>
 </function>
 
@@ -14923,11 +15079,11 @@
 </parameter_description>
 </parameter>
 <parameter name="dest_window">
-<parameter_description> (out): location to store the destination window in.
+<parameter_description> location to store the destination window in.
 </parameter_description>
 </parameter>
 <parameter name="protocol">
-<parameter_description> (out): location to store the DND protocol in.
+<parameter_description> location to store the DND protocol in.
 </parameter_description>
 </parameter>
 </parameters>
@@ -14957,7 +15113,7 @@
 </parameter_description>
 </parameter>
 <parameter name="color">
-<parameter_description> (out): the #GdkColor to fill in
+<parameter_description> the #GdkColor to fill in
 </parameter_description>
 </parameter>
 </parameters>
@@ -15035,6 +15191,7 @@
 <description>
 Gets the width of @screen in pixels
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -15045,7 +15202,6 @@
 </parameters>
 <return> the width of @screen in pixels.
 
-Since: 2.2
 </return>
 </function>
 
@@ -15056,7 +15212,7 @@
 </description>
 <parameters>
 <parameter name="events">
-<parameter_description> (inout) (transfer none): an array of #GdkTimeCoord.
+<parameter_description> an array of #GdkTimeCoord.
 </parameter_description>
 </parameter>
 <parameter name="n_events">
@@ -15098,6 +15254,7 @@
 <description>
 Find the #GdkDisplay corresponding to @display, if any exists.
 
+Since: 2.2
 
 </description>
 <parameters>
@@ -15108,7 +15265,6 @@
 </parameters>
 <return> the #GdkDisplay, if found, otherwise %NULL.
 
-Since: 2.2
 </return>
 </function>
 
@@ -15118,11 +15274,11 @@
 </description>
 <parameters>
 <parameter name="argc">
-<parameter_description> (inout):
+<parameter_description>
 </parameter_description>
 </parameter>
 <parameter name="argv">
-<parameter_description> (array length=argc) (inout):
+<parameter_description>
 </parameter_description>
 </parameter>
 </parameters>
@@ -15150,7 +15306,9 @@
 
 <function name="gdk_window_get_group">
 <description>
-Return value: the group leader window for @window
+Returns the group leader window for @window. See gdk_window_set_group().
+
+Since: 2.4
 
 </description>
 <parameters>
@@ -15161,7 +15319,6 @@
 </parameters>
 <return> the group leader window for @window
 
-Since: 2.4
 </return>
 </function>
 
@@ -15176,6 +15333,7 @@
 and gdk_pango_renderer_set_gc() to set the drawable and graphics context
 to use for drawing.
 
+Since: 2.6
 
 </description>
 <parameters>
@@ -15188,7 +15346,6 @@
 renderer is owned by GTK+ and will be kept around until the
 screen is closed.
 
-Since: 2.6
 </return>
 </function>
 
@@ -15259,6 +15416,7 @@
 
 See gdk_threads_add_timeout_full().
 
+Since: 2.12
 
 </description>
 <parameters>
@@ -15278,7 +15436,6 @@
 </parameters>
 <return> the ID (greater than 0) of the event source.
 
-Since: 2.12
 </return>
 </function>
 
