[gtk+/native-layout] Merge in Gdk-custom.c introspection annotations

From: Tristan Van Berkom <tvb src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk+/native-layout] Merge in Gdk-custom.c introspection annotations
Date: Sun, 4 Apr 2010 02:05:29 +0000 (UTC)
commit f584679cfa7bdac0ada61426f252e4190189d93b
Author: Colin Walters <walters verbum org>
Date:   Tue Aug 18 14:35:10 2009 -0400

    Merge in Gdk-custom.c introspection annotations
    
    The Gdk-custom.c file in gir-repository contained a number of
    introspection annotations.  Merge those into the GDK source files.
    
    Some documentation was moved from the tmpl/ files to accomodate
    the addition of annotations.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=592279

 docs/reference/gdk/tmpl/input_devices.sgml |   12 ++---
 docs/reference/gdk/tmpl/pixmaps.sgml       |   61 -------------------------
 gdk/gdk.c                                  |   14 ++++--
 gdk/gdkcolor.c                             |    4 +-
 gdk/gdkdisplay.c                           |   22 +++++-----
 gdk/gdkdisplaymanager.c                    |   21 +++++----
 gdk/gdkdnd.c                               |    8 ++--
 gdk/gdkdraw.c                              |    6 +-
 gdk/gdkinput.h                             |    3 +
 gdk/gdkkeys.c                              |    6 +-
 gdk/gdkpixmap.c                            |   67 ++++++++++++++++++++++++++++
 gdk/gdkregion-generic.c                    |    2 +-
 gdk/gdkwindow.c                            |   24 +++++-----
 gdk/x11/gdkcursor-x11.c                    |    4 +-
 gdk/x11/gdkdnd-x11.c                       |    8 ++--
 gdk/x11/gdkinput-x11.c                     |   10 ++++
 gdk/x11/gdkinput.c                         |    9 +++-
 gdk/x11/gdkkeys-x11.c                      |   26 +++++-----
 gdk/x11/gdkscreen-x11.c                    |    6 +-
 gdk/x11/gdkvisual-x11.c                    |    4 +-
 20 files changed, 173 insertions(+), 144 deletions(-)
---
diff --git a/docs/reference/gdk/tmpl/input_devices.sgml b/docs/reference/gdk/tmpl/input_devices.sgml
index b905921..f5f16be 100644
--- a/docs/reference/gdk/tmpl/input_devices.sgml
+++ b/docs/reference/gdk/tmpl/input_devices.sgml
@@ -228,15 +228,11 @@ Specifies how an axis of a device is used.
 
 
 <!-- ##### FUNCTION gdk_device_get_state ##### -->
-<para>
-Gets the current state of a device.
-</para>
 
- device: a #GdkDevice.
- window: a #GdkWindow.
- axes: an array of doubles to store the values of the axes of @device in, 
-  or %NULL.
- mask: location to store the modifiers, or %NULL.
+ device:
+ window:
+ axes:
+ mask:
 
 
 <!-- ##### FUNCTION gdk_device_get_history ##### -->
diff --git a/docs/reference/gdk/tmpl/pixmaps.sgml b/docs/reference/gdk/tmpl/pixmaps.sgml
index 5831979..4cf9086 100644
--- a/docs/reference/gdk/tmpl/pixmaps.sgml
+++ b/docs/reference/gdk/tmpl/pixmaps.sgml
@@ -77,76 +77,15 @@ for the new pixmap. Can be %NULL, if the depth is given.
 
 
 <!-- ##### FUNCTION gdk_pixmap_create_from_xpm ##### -->
-<para>
-Create a pixmap from a XPM file.
-</para>
-
- drawable: a #GdkDrawable, used to determine default values
-for the new pixmap.
- mask: a 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.
- transparent_color: the color to be used for the pixels
-that are transparent in the input file. Can be %NULL,
-in which case a default color will be used.
- filename: the filename of a file containing XPM data.
- Returns: the #GdkPixmap
 
 
 <!-- ##### FUNCTION gdk_pixmap_colormap_create_from_xpm ##### -->
-<para>
-Create a pixmap from a XPM file using a particular colormap.
-</para>
-
- drawable: a #GdkDrawable, used to determine default values
-for the new pixmap. Can be %NULL if @colormap is given.
- colormap: the #GdkColormap that the new pixmap will be use.
-  If omitted, the colormap for @window will be used.
- mask: a 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.
- transparent_color: the color to be used for the pixels
-that are transparent in the input file. Can be %NULL,
-in which case a default color will be used.
- filename: the filename of a file containing XPM data.
- Returns: the #GdkPixmap.
 
 
 <!-- ##### FUNCTION gdk_pixmap_create_from_xpm_d ##### -->
-<para>
-Create a pixmap from data in XPM format.
-</para>
-
- drawable: a #GdkDrawable, used to determine default values
-for the new pixmap.
- mask: 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.
- transparent_color: This color will be used for the pixels
-that are transparent in the input file. Can be %NULL
-in which case a default color will be used.
- data: Pointer to a string containing the XPM data.
- Returns: the #GdkPixmap
 
 
 <!-- ##### FUNCTION gdk_pixmap_colormap_create_from_xpm_d ##### -->
-<para>
-Create a pixmap from data in XPM format using a particular
-colormap.
-</para>
-
- drawable: a #GdkDrawable, used to determine default values
-for the new pixmap. Can be %NULL if @colormap is given.
- colormap: the #GdkColormap that the new pixmap will be use.
-  If omitted, the colormap for @window will be used.
- mask: a 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.
- transparent_color: the color to be used for the pixels
-that are transparent in the input file. Can be %NULL,
-in which case a default color will be used.
- data: Pointer to a string containing the XPM data.
- Returns: the #GdkPixmap.
 
 
 <!-- ##### MACRO gdk_pixmap_ref ##### -->
diff --git a/gdk/gdk.c b/gdk/gdk.c
index 5dd2fae..0a5fd93 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -338,9 +338,10 @@ gdk_display_open_default_libgtk_only (void)
   return display;
 }
 
-/*
- *--------------------------------------------------------------
- * gdk_init_check
+/**
+ * gdk_init_check:
+ * @argc: (inout):
+ * @argv: (array length=argc) (inout):
  *
  *   Initialize the library for use.
  *
@@ -359,7 +360,6 @@ gdk_display_open_default_libgtk_only (void)
  *
  *--------------------------------------------------------------
  */
-
 gboolean
 gdk_init_check (int    *argc,
 		char ***argv)
@@ -369,6 +369,12 @@ gdk_init_check (int    *argc,
   return gdk_display_open_default_libgtk_only () != NULL;
 }
 
+
+/**
+ * gdk_init:
+ * @argc: (inout):
+ * @argv: (array length=argc) (inout):
+ */
 void
 gdk_init (int *argc, char ***argv)
 {
diff --git a/gdk/gdkcolor.c b/gdk/gdkcolor.c
index 3bd044e..b718038 100644
--- a/gdk/gdkcolor.c
+++ b/gdk/gdkcolor.c
@@ -318,8 +318,8 @@ gdk_color_get_type (void)
 /**
  * gdk_color_parse:
  * @spec: the string specifying the color.
- * @color: the #GdkColor to fill in
- * 
+ * @color: (out): the #GdkColor to fill in
+ *
  * Parses a textual specification of a color and fill in the
  * <structfield>red</structfield>, <structfield>green</structfield>,
  * and <structfield>blue</structfield> fields of a #GdkColor
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index c2064ba..34c8035 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -466,12 +466,12 @@ _gdk_display_enable_motion_hints (GdkDisplay *display)
 /**
  * gdk_display_get_pointer:
  * @display: a #GdkDisplay
- * @screen: location to store the screen that the
+ * @screen: (allow-none): location to store the screen that the
  *          cursor is on, or %NULL.
- * @x: location to store root window X coordinate of pointer, or %NULL.
- * @y: location to store root window Y coordinate of pointer, or %NULL.
- * @mask: location to store current modifier mask, or %NULL
- * 
+ * @x: (out): location to store root window X coordinate of pointer, or %NULL.
+ * @y: (out): location to store root window Y coordinate of pointer, or %NULL.
+ * @mask: (out): location to store current modifier mask, or %NULL
+ *
  * Gets the current location of the pointer and the current modifier
  * mask for a given display.
  *
@@ -567,17 +567,17 @@ gdk_window_real_window_get_pointer (GdkDisplay       *display,
 /**
  * gdk_display_get_window_at_pointer:
  * @display: a #GdkDisplay
- * @win_x: return location for x coordinate of the pointer location relative 
+ * @win_x: (out) (allow-none): return location for x coordinate of the pointer location relative
  *    to the window origin, or %NULL
- * @win_y: return location for y coordinate of the pointer location relative
+ * @win_y: (out) (allow-none): return location for y coordinate of the pointer location relative
  &    to the window origin, or %NULL
- * 
+ *
  * Obtains the window underneath the mouse pointer, returning the location
- * of the pointer in that window in @win_x, @win_y for @screen. Returns %NULL 
+ * of the pointer in that window in @win_x, @win_y for @screen. Returns %NULL
  * if the window under the mouse pointer is not known to GDK (for example, 
  * belongs to another application).
- * 
- * Returns: the window under the mouse pointer, or %NULL
+ *
+ * Returns: (transfer none): the window under the mouse pointer, or %NULL
  *
  * Since: 2.2
  **/
diff --git a/gdk/gdkdisplaymanager.c b/gdk/gdkdisplaymanager.c
index 0f9a094..e10adc6 100644
--- a/gdk/gdkdisplaymanager.c
+++ b/gdk/gdkdisplaymanager.c
@@ -147,11 +147,12 @@ gdk_display_manager_get_property (GObject      *object,
     }
 }
 
-/** 
+/**
  * gdk_display_manager_get:
- * @returns: the singleton #GdkDisplayManager object.
  *
- * Returns the global #GdkDisplayManager singleton; gdk_parse_pargs(),
+ * Gets the singleton #GdkDisplayManager object.
+ *
+ * Returns: (transfer none): The global #GdkDisplayManager singleton; gdk_parse_pargs(),
  * gdk_init(), or gdk_init_check() must have been called first.
  *
  * Since: 2.2
@@ -171,9 +172,9 @@ gdk_display_manager_get (void)
  * gdk_display_manager_get_default_display:
  * @display_manager: a #GdkDisplayManager 
  *
- * Gets the default #GdkDisplay. 
- * 
- * Returns: a #GdkDisplay, or %NULL if there is no default
+ * Gets the default #GdkDisplay.
+ *
+ * Returns: (transfer none): a #GdkDisplay, or %NULL if there is no default
  *   display.
  *
  * Since: 2.2
@@ -190,8 +191,8 @@ gdk_display_manager_get_default_display (GdkDisplayManager *display_manager)
  * Gets the default #GdkDisplay. This is a convenience
  * function for
  * <literal>gdk_display_manager_get_default_display (gdk_display_manager_get ())</literal>.
- * 
- * Returns: a #GdkDisplay, or %NULL if there is no default
+ *
+ * Returns: (transfer none): a #GdkDisplay, or %NULL if there is no default
  *   display.
  *
  * Since: 2.2
@@ -207,8 +208,8 @@ gdk_display_get_default (void)
  *
  * Gets the default screen for the default display. (See
  * gdk_display_get_default ()).
- * 
- * Returns: a #GdkScreen, or %NULL if there is no default display.
+ *
+ * Returns: (transfer none): a #GdkScreen, or %NULL if there is no default display.
  *
  * Since: 2.2
  */
diff --git a/gdk/gdkdnd.c b/gdk/gdkdnd.c
index 6433660..2d114fa 100644
--- a/gdk/gdkdnd.c
+++ b/gdk/gdkdnd.c
@@ -37,11 +37,11 @@
  *      should be ignored, since it is put up by the drag source as an icon.
  * @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.
- * 
+ * @dest_window: (out): location to store the destination window in.
+ * @protocol: (out): location to store the DND protocol in.
+ *
  * Finds the destination window and DND protocol to use at the
- * given pointer position. 
+ * given pointer position.
  *
  * This function is called by the drag source to obtain the 
  * @dest_window and @protocol parameters for gdk_drag_motion().
diff --git a/gdk/gdkdraw.c b/gdk/gdkdraw.c
index 298f405..ef42b8e 100644
--- a/gdk/gdkdraw.c
+++ b/gdk/gdkdraw.c
@@ -142,12 +142,12 @@ gdk_drawable_get_data (GdkDrawable   *drawable,
 /**
  * gdk_drawable_get_size:
  * @drawable: a #GdkDrawable
- * @width: location to store drawable's width, or %NULL
- * @height: location to store drawable's height, or %NULL
+ * @width: (out): location to store drawable's width, or %NULL
+ * @height: (out): location to store drawable's height, or %NULL
  *
  * Fills * width and * height with the size of @drawable.
  * @width or @height can be %NULL if you only want the other one.
- * 
+ *
  * On the X11 platform, if @drawable is a #GdkWindow, the returned
  * size is the size reported in the most-recently-processed configure
  * event, rather than the current size on the X server.
diff --git a/gdk/gdkinput.h b/gdk/gdkinput.h
index 454def8..9e1bbc7 100644
--- a/gdk/gdkinput.h
+++ b/gdk/gdkinput.h
@@ -145,16 +145,19 @@ void           gdk_device_set_key       (GdkDevice      *device,
 void     gdk_device_set_axis_use (GdkDevice         *device,
 				  guint              index_,
 				  GdkAxisUse         use);
+
 void     gdk_device_get_state    (GdkDevice         *device,
 				  GdkWindow         *window,
 				  gdouble           *axes,
 				  GdkModifierType   *mask);
+
 gboolean gdk_device_get_history  (GdkDevice         *device,
 				  GdkWindow         *window,
 				  guint32            start,
 				  guint32            stop,
 				  GdkTimeCoord    ***events,
 				  gint              *n_events);
+
 void     gdk_device_free_history (GdkTimeCoord     **events,
 				  gint               n_events);
 gboolean gdk_device_get_axis     (GdkDevice         *device,
diff --git a/gdk/gdkkeys.c b/gdk/gdkkeys.c
index 130dbac..6953b46 100644
--- a/gdk/gdkkeys.c
+++ b/gdk/gdkkeys.c
@@ -121,12 +121,12 @@ gdk_keymap_init (GdkKeymap *keymap)
 /**
  * gdk_keyval_convert_case:
  * @symbol: a keyval
- * @lower: return location for lowercase version of @symbol
- * @upper: return location for uppercase version of @symbol
+ * @lower: (out): return location for lowercase version of @symbol
+ * @upper: (out): return location for uppercase version of @symbol
  *
  * Obtains the upper- and lower-case versions of the keyval @symbol.
  * Examples of keyvals are #GDK_a, #GDK_Enter, #GDK_F1, etc.
- * 
+ *
  **/
 void
 gdk_keyval_convert_case (guint symbol,
diff --git a/gdk/gdkpixmap.c b/gdk/gdkpixmap.c
index 919a202..9a594a2 100644
--- a/gdk/gdkpixmap.c
+++ b/gdk/gdkpixmap.c
@@ -672,6 +672,24 @@ gdk_pixmap_colormap_new_from_pixbuf (GdkColormap    *colormap,
   return pixmap;
 }
 
+/**
+ * gdk_pixmap_colormap_create_from_xpm:
+ * @drawable: a #GdkDrawable, used to determine default values
+ * for the new pixmap. Can be %NULL if @colormap is given.
+ * @colormap: the #GdkColormap that the new pixmap will be use.
+ * If omitted, the colormap for @window will be used.
+ * @mask: a 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.
+ * @transparent_color: the color to be used for the pixels
+ * that are transparent in the input file. Can be %NULL,
+ * in which case a default color will be used.
+ * @filename: the filename of a file containing XPM data.
+ *
+ * Create a pixmap from a XPM file using a particular colormap.
+ *
+ * Returns: (transfer none): the #GdkPixmap.
+ */
 GdkPixmap*
 gdk_pixmap_colormap_create_from_xpm (GdkDrawable    *drawable,
 				     GdkColormap    *colormap,
@@ -700,6 +718,22 @@ gdk_pixmap_colormap_create_from_xpm (GdkDrawable    *drawable,
   return pixmap;
 }
 
+/**
+ * gdk_pixmap_create_from_xpm:
+ * @drawable: a #GdkDrawable, used to determine default values
+ * for the new pixmap.
+ * @mask: (out) a 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.
+ * @transparent_color: the color to be used for the pixels
+ * that are transparent in the input file. Can be %NULL,
+ * in which case a default color will be used.
+ * @filename: the filename of a file containing XPM data.
+ *
+ * Create a pixmap from a XPM file.
+ *
+ * Returns: (transfer none): the #GdkPixmap
+ */
 GdkPixmap*
 gdk_pixmap_create_from_xpm (GdkDrawable    *drawable,
 			    GdkBitmap     **mask,
@@ -710,6 +744,23 @@ gdk_pixmap_create_from_xpm (GdkDrawable    *drawable,
 					      transparent_color, filename);
 }
 
+/**
+ * gdk_pixmap_colormap_create_from_xpm_d:
+ * @drawable: a #GdkDrawable, used to determine default values
+ * for the new pixmap. Can be %NULL if @colormap is given.
+ * @colormap: the #GdkColormap that the new pixmap will be use.
+ * If omitted, the colormap for @window will be used.
+ * @mask: a 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.
+ * @transparent_color: the color to be used for the pixels
+ * that are transparent in the input file. Can be %NULL,
+ * in which case a default color will be used.
+ * @data: Pointer to a string containing the XPM data.
+ *
+ * Create a pixmap from data in XPM format using a particular
+ * colormap.
+ */
 GdkPixmap*
 gdk_pixmap_colormap_create_from_xpm_d (GdkDrawable    *drawable,
 				       GdkColormap    *colormap,
@@ -738,6 +789,22 @@ gdk_pixmap_colormap_create_from_xpm_d (GdkDrawable    *drawable,
   return pixmap;
 }
 
+/**
+ * gdk_pixmap_create_from_xpm_d:
+ * @drawable: a #GdkDrawable, used to determine default values
+ * for the new pixmap.
+ * @mask: (out): 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.
+ * @transparent_color: This color will be used for the pixels
+ * that are transparent in the input file. Can be %NULL
+ * in which case a default color will be used.
+ * @data: Pointer to a string containing the XPM data.
+ *
+ * Create a pixmap from data in XPM format.
+ *
+ * Returns: (transfer none): the #GdkPixmap.
+ */
 GdkPixmap*
 gdk_pixmap_create_from_xpm_d (GdkDrawable    *drawable,
 			      GdkBitmap     **mask,
diff --git a/gdk/gdkregion-generic.c b/gdk/gdkregion-generic.c
index d98dc88..0801b1e 100644
--- a/gdk/gdkregion-generic.c
+++ b/gdk/gdkregion-generic.c
@@ -226,7 +226,7 @@ gdk_region_get_clipbox (const GdkRegion *region,
 /**
  * gdk_region_get_rectangles:
  * @region: a #GdkRegion
- * @rectangles: return location for an array of rectangles
+ * @rectangles: (array length=n_rectangles) (transfer container): return location for an array of rectangles
  * @n_rectangles: length of returned array
  *
  * Obtains the area covered by the region as a list of rectangles.
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 78b19e8..cd7def8 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -1256,7 +1256,7 @@ sync_native_window_stack_position (GdkWindow *window)
 
 /**
  * gdk_window_new:
- * @parent: a #GdkWindow, or %NULL to create the window as a child of
+ * @parent: (allow-none): a #GdkWindow, or %NULL to create the window as a child of
  *   the default root window for the default display.
  * @attributes: attributes of the new window
  * @attributes_mask: mask indicating which fields in @attributes are valid
@@ -1266,7 +1266,7 @@ sync_native_window_stack_position (GdkWindow *window)
  * more details.  Note: to use this on displays other than the default
  * display, @parent must be specified.
  *
- * Return value: the new #GdkWindow
+ * Return value: (transfer none): the new #GdkWindow
  **/
 GdkWindow*
 gdk_window_new (GdkWindow     *parent,
@@ -3456,12 +3456,12 @@ gdk_window_get_offsets (GdkWindow *window,
 /**
  * gdk_window_get_internal_paint_info:
  * @window: a #GdkWindow
- * @real_drawable: location to store the drawable to which drawing should be
+ * @real_drawable: (out): location to store the drawable to which drawing should be
  *            done.
- * @x_offset: location to store the X offset between coordinates in @window,
+ * @x_offset: (out): location to store the X offset between coordinates in @window,
  *            and the underlying window system primitive coordinates for
  *            * real_drawable 
- * @y_offset: location to store the Y offset between coordinates in @window,
+ * @y_offset: (out): location to store the Y offset between coordinates in @window,
  *            and the underlying window system primitive coordinates for
  *            * real_drawable 
  *
@@ -6199,18 +6199,18 @@ gdk_window_constrain_size (GdkGeometry *geometry,
 /**
  * gdk_window_get_pointer:
  * @window: a #GdkWindow
- * @x: return location for X coordinate of pointer or %NULL to not
+ * @x: (out) (allow-none): return location for X coordinate of pointer or %NULL to not
  *      return the X coordinate
- * @y: return location for Y coordinate of pointer or %NULL to not
+ * @y: (out) (allow-none):  return location for Y coordinate of pointer or %NULL to not
  *      return the Y coordinate
- * @mask: return location for modifier mask or %NULL to not return the
+ * @mask: (out) (allow-none): return location for modifier mask or %NULL to not return the
  *      modifier mask
  *
  * Obtains the current pointer position and modifier state.
  * The position is given in coordinates relative to the upper left
  * corner of @window.
  *
- * Return value: the window containing the pointer (as with
+ * Return value: (transfer none): the window containing the pointer (as with
  * gdk_window_at_pointer()), or %NULL if the window containing the
  * pointer isn't known to GDK
  **/
@@ -6259,8 +6259,8 @@ gdk_window_get_pointer (GdkWindow	  *window,
 
 /**
  * gdk_window_at_pointer:
- * @win_x: return location for origin of the window under the pointer
- * @win_y: return location for origin of the window under the pointer
+ * @win_x: (out) (allow-none): return location for origin of the window under the pointer
+ * @win_y: (out) (allow-none): return location for origin of the window under the pointer
  *
  * Obtains the window underneath the mouse pointer, returning the
  * location of that window in @win_x, @win_y. Returns %NULL if the
@@ -6271,7 +6271,7 @@ gdk_window_get_pointer (GdkWindow	  *window,
  * NOTE: For multihead-aware widgets or applications use
  * gdk_display_get_window_at_pointer() instead.
  *
- * Return value: window under the mouse pointer
+ * Return value: (transfer none): window under the mouse pointer
  **/
 GdkWindow*
 gdk_window_at_pointer (gint *win_x,
diff --git a/gdk/x11/gdkcursor-x11.c b/gdk/x11/gdkcursor-x11.c
index 19d79cf..5cfbaa5 100644
--- a/gdk/x11/gdkcursor-x11.c
+++ b/gdk/x11/gdkcursor-x11.c
@@ -1035,8 +1035,8 @@ gdk_display_get_default_cursor_size (GdkDisplay    *display)
 /**
  * gdk_display_get_maximal_cursor_size:
  * @display: a #GdkDisplay
- * @width: the return location for the maximal cursor width
- * @height: the return location for the maximal cursor height
+ * @width: (out): the return location for the maximal cursor width
+ * @height: (out): the return location for the maximal cursor height
  *
  * Gets the maximal size to use for cursors on @display.
  *
diff --git a/gdk/x11/gdkdnd-x11.c b/gdk/x11/gdkdnd-x11.c
index c7c803a..938e7e1 100644
--- a/gdk/x11/gdkdnd-x11.c
+++ b/gdk/x11/gdkdnd-x11.c
@@ -3170,11 +3170,11 @@ drag_context_find_window_cache (GdkDragContext  *context,
  * @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.
- * 
+ * @dest_window: (out): location to store the destination window in.
+ * @protocol: (out): location to store the DND protocol in.
+ *
  * Finds the destination window and DND protocol to use at the
- * given pointer position. 
+ * given pointer position.
  *
  * This function is called by the drag source to obtain the 
  * @dest_window and @protocol parameters for gdk_drag_motion().
diff --git a/gdk/x11/gdkinput-x11.c b/gdk/x11/gdkinput-x11.c
index a793a42..767b070 100644
--- a/gdk/x11/gdkinput-x11.c
+++ b/gdk/x11/gdkinput-x11.c
@@ -858,6 +858,16 @@ _gdk_device_get_history (GdkDevice         *device,
     return FALSE;
 }
 
+/**
+ * gdk_device_get_state:
+ * @device: a #GdkDevice.
+ * @window: a #GdkWindow.
+ * @axes: an array of doubles to store the values of the axes of @device in,
+ * or %NULL.
+ * @mask: location to store the modifiers, or %NULL.
+ *
+ * Gets the current state of a device.
+ */
 void
 gdk_device_get_state (GdkDevice       *device,
 		      GdkWindow       *window,
diff --git a/gdk/x11/gdkinput.c b/gdk/x11/gdkinput.c
index 95485d7..72eb5ab 100644
--- a/gdk/x11/gdkinput.c
+++ b/gdk/x11/gdkinput.c
@@ -243,7 +243,7 @@ impl_coord_in_window (GdkWindow *window,
  * @window: the window with respect to which which the event coordinates will be reported
  * @start: starting timestamp for range of events to return
  * @stop: ending timestamp for the range of events to return
- * @events: location to store a newly-allocated array of #GdkTimeCoord, or %NULL
+ * @events: (array length=n_events) (out) (transfer none): location to store a newly-allocated array of #GdkTimeCoord, or %NULL
  * @n_events: location to store the length of @events, or %NULL
  *
  * Obtains the motion history for a device; given a starting and
@@ -351,6 +351,13 @@ _gdk_device_allocate_history (GdkDevice *device,
   return result;
 }
 
+/**
+ * gdk_device_free_history:
+ * @events: (inout) (transfer none): an array of #GdkTimeCoord.
+ * @n_events: the length of the array.
+ *
+ * Frees an array of #GdkTimeCoord that was returned by gdk_device_get_history().
+ */
 void
 gdk_device_free_history (GdkTimeCoord **events,
 			 gint           n_events)
diff --git a/gdk/x11/gdkkeys-x11.c b/gdk/x11/gdkkeys-x11.c
index 01d2a18..8cb5b3b 100644
--- a/gdk/x11/gdkkeys-x11.c
+++ b/gdk/x11/gdkkeys-x11.c
@@ -834,11 +834,11 @@ gdk_keymap_get_caps_lock_state (GdkKeymap *keymap)
 
 /**
  * gdk_keymap_get_entries_for_keyval:
- * @keymap: a #GdkKeymap, or %NULL to use the default keymap
+ * @keymap: (allow-none): a #GdkKeymap, or %NULL to use the default keymap
  * @keyval: a keyval, such as %GDK_a, %GDK_Up, %GDK_Return, etc.
- * @keys: return location for an array of #GdkKeymapKey
- * @n_keys: return location for number of elements in returned array
- * 
+ * @keys: (out): return location for an array of #GdkKeymapKey
+ * @n_keys: (out): return location for number of elements in returned array
+ *
  * Obtains a list of keycode/group/level combinations that will
  * generate @keyval. Groups and levels are two kinds of keyboard mode;
  * in general, the level determines whether the top or bottom symbol
@@ -984,10 +984,10 @@ gdk_keymap_get_entries_for_keyval (GdkKeymap     *keymap,
 
 /**
  * gdk_keymap_get_entries_for_keycode:
- * @keymap: a #GdkKeymap or %NULL to use the default keymap
+ * @keymap: (allow-none): a #GdkKeymap or %NULL to use the default keymap
  * @hardware_keycode: a keycode
- * @keys: return location for array of #GdkKeymapKey, or %NULL
- * @keyvals: return location for array of keyvals, or %NULL
+ * @keys: (out): return location for array of #GdkKeymapKey, or %NULL
+ * @keyvals: (out): return location for array of keyvals, or %NULL
  * @n_entries: length of @keys and @keyvals
  *
  * Returns the keyvals bound to @hardware_keycode.
@@ -1409,14 +1409,14 @@ translate_keysym (GdkKeymapX11   *keymap_x11,
 
 /**
  * gdk_keymap_translate_keyboard_state:
- * @keymap: a #GdkKeymap, or %NULL to use the default
+ * @keymap: (allow-none): a #GdkKeymap, or %NULL to use the default
  * @hardware_keycode: a keycode
- * @state: a modifier state 
+ * @state: a modifier state
  * @group: active keyboard group
- * @keyval: return location for keyval, or %NULL
- * @effective_group: return location for effective group, or %NULL
- * @level: return location for level, or %NULL
- * @consumed_modifiers: return location for modifiers that were used to
+ * @keyval: (out) (allow-none): return location for keyval, or %NULL
+ * @effective_group: (out) (allow-none): return location for effective group, or %NULL
+ * @level: (out) (allow-none):  return location for level, or %NULL
+ * @consumed_modifiers: (out) (allow-none):  return location for modifiers that were used to
  *     determine the group or level, or %NULL
  *
  * Translates the contents of a #GdkEventKey into a keyval, effective
diff --git a/gdk/x11/gdkscreen-x11.c b/gdk/x11/gdkscreen-x11.c
index 3e7b8b9..5b0cb17 100644
--- a/gdk/x11/gdkscreen-x11.c
+++ b/gdk/x11/gdkscreen-x11.c
@@ -214,9 +214,9 @@ gdk_screen_get_number (GdkScreen *screen)
  * gdk_screen_get_root_window:
  * @screen: a #GdkScreen
  *
- * Gets the root window of @screen. 
- * 
- * Returns: the root window
+ * Gets the root window of @screen.
+ *
+ * Returns: (transfer none): the root window
  *
  * Since: 2.2
  **/
diff --git a/gdk/x11/gdkvisual-x11.c b/gdk/x11/gdkvisual-x11.c
index 6d827c9..1e78165 100644
--- a/gdk/x11/gdkvisual-x11.c
+++ b/gdk/x11/gdkvisual-x11.c
@@ -466,8 +466,8 @@ gdk_visual_get_best_with_both (gint          depth,
 
 /**
  * gdk_query_depths:
- * @depths: return location for available depths 
- * @count: return location for number of available depths
+ * @depths: (out) (array): return location for available depths
+ * @count: (out): return location for number of available depths
  *
  * This function returns the available bit depths for the default
  * screen. It's equivalent to listing the visuals
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]