[GI] Add missing (out) and (array) annotations

49 files changed, 301 insertions, 248 deletions

diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index 8da802fd81..7e34c993c8 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -1480,9 +1480,9 @@ gtk_about_dialog_set_website_label (GtkAboutDialog *about,
  * Returns the string which are displayed in the authors tab
  * of the secondary credits dialog.
  *
- * Return value: A %NULL-terminated string array containing
- *  the authors. The array is owned by the about dialog
- *  and must not be modified.
+ * Return value: (array zero-terminated=1) (transfer none): A
+ *  %NULL-terminated string array containing the authors. The array is
+ *  owned by the about dialog and must not be modified.
  *
  * Since: 2.6
  */
@@ -1535,9 +1535,9 @@ gtk_about_dialog_set_authors (GtkAboutDialog  *about,
  * Returns the string which are displayed in the documenters
  * tab of the secondary credits dialog.
  *
- * Return value: A %NULL-terminated string array containing
- *  the documenters. The array is owned by the about dialog
- *  and must not be modified.
+ * Return value: (array zero-terminated=1) (transfer none): A
+ *  %NULL-terminated string array containing the documenters. The
+ *  array is owned by the about dialog and must not be modified.
  *
  * Since: 2.6
  */
@@ -1590,9 +1590,9 @@ gtk_about_dialog_set_documenters (GtkAboutDialog *about,
  * Returns the string which are displayed in the artists tab
  * of the secondary credits dialog.
  *
- * Return value: A %NULL-terminated string array containing
- *  the artists. The array is owned by the about dialog
- *  and must not be modified.
+ * Return value: (array zero-terminated=1) (transfer none): A
+ *  %NULL-terminated string array containing the artists. The array is
+ *  owned by the about dialog and must not be modified.
  *
  * Since: 2.6
  */
diff --git a/gtk/gtkalignment.c b/gtk/gtkalignment.c
index 78f21aafff..281fa9cd33 100644
--- a/gtk/gtkalignment.c
+++ b/gtk/gtkalignment.c
@@ -753,10 +753,14 @@ gtk_alignment_set_padding (GtkAlignment    *alignment,
 /**
  * gtk_alignment_get_padding:
  * @alignment: a #GtkAlignment
- * @padding_top: (allow-none): location to store the padding for the top of the widget, or %NULL
- * @padding_bottom: (allow-none): location to store the padding for the bottom of the widget, or %NULL
- * @padding_left: (allow-none): location to store the padding for the left of the widget, or %NULL
- * @padding_right: (allow-none): location to store the padding for the right of the widget, or %NULL
+ * @padding_top: (out) (allow-none): location to store the padding for
+ *     the top of the widget, or %NULL
+ * @padding_bottom: (out) (allow-none): location to store the padding
+ *     for the bottom of the widget, or %NULL
+ * @padding_left: (out) (allow-none): location to store the padding
+ *     for the left of the widget, or %NULL
+ * @padding_right: (out) (allow-none): location to store the padding
+ *     for the right of the widget, or %NULL
  *
  * Gets the padding on the different sides of the widget.
  * See gtk_alignment_set_padding ().
diff --git a/gtk/gtkbox.c b/gtk/gtkbox.c
index 8c7f86705e..6292ca854a 100644
--- a/gtk/gtkbox.c
+++ b/gtk/gtkbox.c
@@ -1505,10 +1505,14 @@ gtk_box_reorder_child (GtkBox    *box,
  * gtk_box_query_child_packing:
  * @box: a #GtkBox
  * @child: the #GtkWidget of the child to query
- * @expand: pointer to return location for #GtkBox:expand child property
- * @fill: pointer to return location for #GtkBox:fill child property
- * @padding: pointer to return location for #GtkBox:padding child property
- * @pack_type: pointer to return location for #GtkBox:pack-type child property
+ * @expand: (out): pointer to return location for #GtkBox:expand child
+ *     property
+ * @fill: (out): pointer to return location for #GtkBox:fill child
+ *     property
+ * @padding: (out): pointer to return location for #GtkBox:padding
+ *     child property
+ * @pack_type: (out): pointer to return location for #GtkBox:pack-type
+ *     child property
  *
  * Obtains information about how @child is packed into @box.
  */
diff --git a/gtk/gtkbuildable.c b/gtk/gtkbuildable.c
index 25c9fc2e52..9dfb64cdbd 100644
--- a/gtk/gtkbuildable.c
+++ b/gtk/gtkbuildable.c
@@ -235,8 +235,8 @@ gtk_buildable_construct_child (GtkBuildable *buildable,
  * @builder: a #GtkBuilder used to construct this object
  * @child: (allow-none): child object or %NULL for non-child tags
  * @tagname: name of tag
- * @parser: a #GMarkupParser structure to fill in
- * @data: return location for user data that will be passed in 
+ * @parser: (out): a #GMarkupParser structure to fill in
+ * @data: (out): return location for user data that will be passed in 
  *   to parser functions
  *
  * This is called for each unknown element under <child>.
@@ -273,7 +273,7 @@ gtk_buildable_custom_tag_start (GtkBuildable  *buildable,
  * @builder: #GtkBuilder used to construct this object
  * @child: (allow-none): child object or %NULL for non-child tags
  * @tagname: name of tag
- * @data: user data that will be passed in to parser functions
+ * @data: (type gpointer): user data that will be passed in to parser functions
  *
  * This is called at the end of each custom element handled by 
  * the buildable.
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index faa3ef79ad..b658654abf 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -1341,7 +1341,7 @@ gtk_builder_connect_signals_full (GtkBuilder            *builder,
  * @builder: a #GtkBuilder
  * @pspec: the #GParamSpec for the property
  * @string: the string representation of the value
- * @value: the #GValue to store the result in
+ * @value: (out): the #GValue to store the result in
  * @error: (allow-none): return location for an error, or %NULL
  *
  * This function demarshals a value from a string. This function
@@ -1397,7 +1397,7 @@ gtk_builder_value_from_string (GtkBuilder   *builder,
  * @builder: a #GtkBuilder
  * @type: the #GType of the value
  * @string: the string representation of the value
- * @value: the #GValue to store the result in
+ * @value: (out): the #GValue to store the result in
  * @error: (allow-none): return location for an error, or %NULL
  *
  * Like gtk_builder_value_from_string(), this function demarshals 
diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index 116bfb7713..3d3bd8630c 100644
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -2240,8 +2240,8 @@ gtk_button_set_alignment (GtkButton *button,
 /**
  * gtk_button_get_alignment:
  * @button: a #GtkButton
- * @xalign: return location for horizontal alignment
- * @yalign: return location for vertical alignment
+ * @xalign: (out): return location for horizontal alignment
+ * @yalign: (out): return location for vertical alignment
  *
  * Gets the alignment of the child in the button.
  *
diff --git a/gtk/gtkcalendar.c b/gtk/gtkcalendar.c
index 50aa3e5f27..3aa1be4f3b 100644
--- a/gtk/gtkcalendar.c
+++ b/gtk/gtkcalendar.c
@@ -3878,9 +3878,12 @@ gtk_calendar_unmark_day (GtkCalendar *calendar,
 /**
  * gtk_calendar_get_date:
  * @calendar: a #GtkCalendar
- * @year: (out) (allow-none): location to store the year as a decimal number (e.g. 2011), or %NULL
- * @month: (out) (allow-none): location to store the month number (between 0 and 11), or %NULL
- * @day: (out) (allow-none): location to store the day number (between 1 and 31), or %NULL
+ * @year: (out) (allow-none): location to store the year as a decimal
+ *     number (e.g. 2011), or %NULL
+ * @month: (out) (allow-none): location to store the month number
+ *     (between 0 and 11), or %NULL
+ * @day: (out) (allow-none): location to store the day number (between
+ *     1 and 31), or %NULL
  *
  * Obtains the selected date from a #GtkCalendar.
  */
diff --git a/gtk/gtkcellarea.c b/gtk/gtkcellarea.c
index 39a4ebcf04..2315871969 100644
--- a/gtk/gtkcellarea.c
+++ b/gtk/gtkcellarea.c
@@ -2458,8 +2458,9 @@ gtk_cell_area_class_find_cell_property (GtkCellAreaClass   *aclass,
  *
  * Returns all cell properties of a cell area class.
  *
- * Return value: a newly allocated %NULL-terminated array of #GParamSpec*.
- *           The array must be freed with g_free().
+ * Return value: (array length=n_properties) (transfer container): a newly
+ *     allocated %NULL-terminated array of #GParamSpec*.  The array
+ *     must be freed with g_free().
  *
  * Since: 3.0
  */
diff --git a/gtk/gtkcellrenderer.c b/gtk/gtkcellrenderer.c
index 36a6120dc8..ced210e362 100644
--- a/gtk/gtkcellrenderer.c
+++ b/gtk/gtkcellrenderer.c
@@ -613,10 +613,10 @@ set_cell_bg_color (GtkCellRenderer *cell,
  * @cell: a #GtkCellRenderer
  * @widget: the widget the renderer is rendering to
  * @cell_area: (allow-none): The area a cell will be allocated, or %NULL
- * @x_offset: (allow-none): location to return x offset of cell relative to @cell_area, or %NULL
- * @y_offset: (allow-none): location to return y offset of cell relative to @cell_area, or %NULL
- * @width: (allow-none): location to return width needed to render a cell, or %NULL
- * @height: (allow-none): location to return height needed to render a cell, or %NULL
+ * @x_offset: (out) (allow-none): location to return x offset of cell relative to @cell_area, or %NULL
+ * @y_offset: (out) (allow-none): location to return y offset of cell relative to @cell_area, or %NULL
+ * @width: (out) (allow-none): location to return width needed to render a cell, or %NULL
+ * @height: (out) (allow-none): location to return height needed to render a cell, or %NULL
  *
  * Obtains the width and height needed to render the cell. Used by view 
  * widgets to determine the appropriate size for the cell_area passed to
@@ -857,8 +857,8 @@ gtk_cell_renderer_set_fixed_size (GtkCellRenderer *cell,
 /**
  * gtk_cell_renderer_get_fixed_size:
  * @cell: A #GtkCellRenderer
- * @width: (allow-none): location to fill in with the fixed width of the cell, or %NULL
- * @height: (allow-none): location to fill in with the fixed height of the cell, or %NULL
+ * @width: (out) (allow-none): location to fill in with the fixed width of the cell, or %NULL
+ * @height: (out) (allow-none): location to fill in with the fixed height of the cell, or %NULL
  *
  * Fills in @width and @height with the appropriate size of @cell.
  **/
@@ -925,8 +925,8 @@ gtk_cell_renderer_set_alignment (GtkCellRenderer *cell,
 /**
  * gtk_cell_renderer_get_alignment:
  * @cell: A #GtkCellRenderer
- * @xalign: (allow-none): location to fill in with the x alignment of the cell, or %NULL
- * @yalign: (allow-none): location to fill in with the y alignment of the cell, or %NULL
+ * @xalign: (out) (allow-none): location to fill in with the x alignment of the cell, or %NULL
+ * @yalign: (out) (allow-none): location to fill in with the y alignment of the cell, or %NULL
  *
  * Fills in @xalign and @yalign with the appropriate values of @cell.
  *
@@ -994,8 +994,8 @@ gtk_cell_renderer_set_padding (GtkCellRenderer *cell,
 /**
  * gtk_cell_renderer_get_padding:
  * @cell: A #GtkCellRenderer
- * @xpad: (allow-none): location to fill in with the x padding of the cell, or %NULL
- * @ypad: (allow-none): location to fill in with the y padding of the cell, or %NULL
+ * @xpad: (out) (allow-none): location to fill in with the x padding of the cell, or %NULL
+ * @ypad: (out) (allow-none): location to fill in with the y padding of the cell, or %NULL
  *
  * Fills in @xpad and @ypad with the appropriate values of @cell.
  *
@@ -1374,8 +1374,8 @@ gtk_cell_renderer_get_request_mode (GtkCellRenderer *cell)
  * gtk_cell_renderer_get_preferred_width:
  * @cell: a #GtkCellRenderer instance
  * @widget: the #GtkWidget this cell will be rendering to
- * @minimum_size: location to store the minimum size, or %NULL
- * @natural_size: location to store the natural size, or %NULL
+ * @minimum_size: (out) (allow-none): location to store the minimum size, or %NULL
+ * @natural_size: (out) (allow-none): location to store the natural size, or %NULL
  *
  * Retreives a renderer's natural size when rendered to @widget.
  *
@@ -1422,8 +1422,8 @@ gtk_cell_renderer_get_preferred_width (GtkCellRenderer *cell,
  * gtk_cell_renderer_get_preferred_height:
  * @cell: a #GtkCellRenderer instance
  * @widget: the #GtkWidget this cell will be rendering to
- * @minimum_size: location to store the minimum size, or %NULL
- * @natural_size: location to store the natural size, or %NULL
+ * @minimum_size: (out) (allow-none): location to store the minimum size, or %NULL
+ * @natural_size: (out) (allow-none): location to store the natural size, or %NULL
  *
  * Retreives a renderer's natural size when rendered to @widget.
  *
@@ -1471,8 +1471,8 @@ gtk_cell_renderer_get_preferred_height (GtkCellRenderer *cell,
  * @cell: a #GtkCellRenderer instance
  * @widget: the #GtkWidget this cell will be rendering to
  * @height: the size which is available for allocation
- * @minimum_width: location for storing the minimum size, or %NULL
- * @natural_width: location for storing the preferred size, or %NULL
+ * @minimum_width: (out) (allow-none): location for storing the minimum size, or %NULL
+ * @natural_width: (out) (allow-none): location for storing the preferred size, or %NULL
  *
  * Retreives a cell renderers's minimum and natural width if it were rendered to 
  * @widget with the specified @height.
@@ -1521,8 +1521,8 @@ gtk_cell_renderer_get_preferred_width_for_height (GtkCellRenderer *cell,
  * @cell: a #GtkCellRenderer instance
  * @widget: the #GtkWidget this cell will be rendering to
  * @width: the size which is available for allocation
- * @minimum_height: location for storing the minimum size, or %NULL
- * @natural_height: location for storing the preferred size, or %NULL
+ * @minimum_height: (out) (allow-none): location for storing the minimum size, or %NULL
+ * @natural_height: (out) (allow-none): location for storing the preferred size, or %NULL
  *
  * Retreives a cell renderers's minimum and natural height if it were rendered to 
  * @widget with the specified @width.
@@ -1633,8 +1633,8 @@ gtk_cell_renderer_get_preferred_size (GtkCellRenderer *cell,
  * @widget: the #GtkWidget this cell will be rendering to
  * @flags: render flags
  * @cell_area: cell area which would be passed to gtk_cell_renderer_render()
- * @aligned_area: the return location for the space inside @cell_area that
- *                would acually be used to render.
+ * @aligned_area: (out): the return location for the space inside @cell_area
+ *                that would acually be used to render.
  *
  * Gets the aligned area used by @cell inside @cell_area. Used for finding
  * the appropriate edit and focus rectangle.
diff --git a/gtk/gtkcellview.c b/gtk/gtkcellview.c
index e47d5eac71..e47f861823 100644
--- a/gtk/gtkcellview.c
+++ b/gtk/gtkcellview.c
@@ -1179,7 +1179,7 @@ gtk_cell_view_get_displayed_row (GtkCellView *cell_view)
  * gtk_cell_view_get_size_of_row:
  * @cell_view: a #GtkCellView
  * @path: a #GtkTreePath 
- * @requisition: return location for the size 
+ * @requisition: (out): return location for the size 
  *
  * Sets @requisition to the size needed by @cell_view to display 
  * the model row pointed to by @path.
diff --git a/gtk/gtkclipboard.c b/gtk/gtkclipboard.c
index 0c4063934e..1fdc44d727 100644
--- a/gtk/gtkclipboard.c
+++ b/gtk/gtkclipboard.c
@@ -1405,19 +1405,20 @@ clipboard_rich_text_received_func (GtkClipboard *clipboard,
  * gtk_clipboard_wait_for_rich_text:
  * @clipboard: a #GtkClipboard
  * @buffer: a #GtkTextBuffer
- * @format: return location for the format of the returned data
+ * @format: (out): return location for the format of the returned data
  * @length: return location for the length of the returned data
  *
  * Requests the contents of the clipboard as rich text.  This function
  * waits for the data to be received using the main loop, so events,
  * timeouts, etc, may be dispatched during the wait.
  *
- * Return value: a newly-allocated binary block of data which must
- *               be freed with g_free(), or %NULL if retrieving
- *               the selection data failed. (This could happen
- *               for various reasons, in particular if the
- *               clipboard was empty or if the contents of the
- *               clipboard could not be converted into text form.)
+ * Return value: (array length=length) (transfer full): a
+ *               newly-allocated binary block of data which must be
+ *               freed with g_free(), or %NULL if retrieving the
+ *               selection data failed. (This could happen for various
+ *               reasons, in particular if the clipboard was empty or
+ *               if the contents of the clipboard could not be
+ *               converted into text form.)
  *
  * Since: 2.10
  **/
@@ -1730,8 +1731,9 @@ gtk_clipboard_wait_is_uris_available (GtkClipboard *clipboard)
 /**
  * gtk_clipboard_wait_for_targets
  * @clipboard: a #GtkClipboard
- * @targets: location to store an array of targets. The result
- *           stored here must be freed with g_free().
+ * @targets: (out) (array length=n_targets) (transfer container): location
+ *           to store an array of targets. The result stored here must
+ *           be freed with g_free().
  * @n_targets: location to store number of items in @targets.
  *
  * Returns a list of targets that are present on the clipboard, or %NULL
@@ -1932,9 +1934,9 @@ gtk_clipboard_store_timeout (GtkClipboard *clipboard)
 /**
  * gtk_clipboard_set_can_store:
  * @clipboard: a #GtkClipboard
- * @targets: (allow-none): array containing information about which forms 
- *           should be stored or %NULL to indicate that all forms should 
- *           be stored.
+ * @targets: (allow-none) (array length=n_targets): array containing
+ *           information about which forms should be stored or %NULL
+ *           to indicate that all forms should be stored.
  * @n_targets: number of elements in @targets
  *
  * Hints that the clipboard data should be stored somewhere when the
diff --git a/gtk/gtkcolorsel.c b/gtk/gtkcolorsel.c
index f60d1e7805..ef2d2a8ad1 100644
--- a/gtk/gtkcolorsel.c
+++ b/gtk/gtkcolorsel.c
@@ -2650,7 +2650,7 @@ gtk_color_selection_set_previous_alpha (GtkColorSelection *colorsel,
 /**
  * gtk_color_selection_get_previous_color:
  * @colorsel: a #GtkColorSelection.
- * @color: a #GdkColor to fill in with the original color value.
+ * @color: (out): a #GdkColor to fill in with the original color value.
  *
  * Fills @color in with the original color value.
  **/
@@ -2802,7 +2802,7 @@ gtk_color_selection_set_previous_rgba (GtkColorSelection *colorsel,
 /**
  * gtk_color_selection_get_previous_rgba:
  * @colorsel: a #GtkColorSelection.
- * @rgba: a #GdkRGBA to fill in with the original color value.
+ * @rgba: (out): a #GdkRGBA to fill in with the original color value.
  *
  * Fills @rgba in with the original color value.
  *
@@ -2881,7 +2881,8 @@ gtk_color_selection_is_adjusting (GtkColorSelection *colorsel)
 /**
  * gtk_color_selection_palette_from_string:
  * @str: a string encoding a color palette.
- * @colors: return location for allocated array of #GdkColor.
+ * @colors: (out) (array length=n_colors): return location for allocated
+ *          array of #GdkColor.
  * @n_colors: return location for length of array.
  * 
  * Parses a color palette string; the string is a colon-separated
@@ -2966,7 +2967,7 @@ gtk_color_selection_palette_from_string (const gchar *str,
 
 /**
  * gtk_color_selection_palette_to_string:
- * @colors: an array of colors.
+ * @colors: (array length=n_colors): an array of colors.
  * @n_colors: length of the array.
  * 
  * Encodes a palette as a string, useful for persistent storage.
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index d6d1877330..d1c8c2aae9 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -1218,10 +1218,11 @@ gtk_container_class_find_child_property (GObjectClass *cclass,
 
 /**
  * gtk_container_class_list_child_properties:
- * @cclass: a #GtkContainerClass
+ * @cclass: (type GtkContainerClass): a #GtkContainerClass
  * @n_properties: location to return the number of child properties found
- * @returns: a newly allocated %NULL-terminated array of #GParamSpec*.
- *           The array must be freed with g_free().
+ * @returns: (array length=n_properties) (transfer container): a newly
+ *           allocated %NULL-terminated array of #GParamSpec*.  The
+ *           array must be freed with g_free().
  *
  * Returns all child properties of a container class.
  */
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 6a1d51f147..99d00b33a3 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -1323,7 +1323,8 @@ gtk_dialog_set_alternative_button_order (GtkDialog *dialog,
  * gtk_dialog_set_alternative_button_order_from_array:
  * @dialog: a #GtkDialog
  * @n_params: the number of response ids in @new_order
- * @new_order: an array of response ids of @dialog's buttons
+ * @new_order: (array length=n_params): an array of response ids of
+ *     @dialog's buttons
  *
  * Sets an alternative button order. If the
  * #GtkSettings:gtk-alternative-button-order setting is set to %TRUE,
diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c
index e85b1f16bf..f9be37ee25 100644
--- a/gtk/gtkeditable.c
+++ b/gtk/gtkeditable.c
@@ -113,10 +113,10 @@ gtk_editable_base_init (gpointer g_class)
        * @new_text: the new text to insert
        * @new_text_length: the length of the new text, in bytes,
        *     or -1 if new_text is nul-terminated
-       * @position: the position, in characters, at which to insert
-       *     the new text. this is an in-out parameter.
-       *     After the signal emission is finished, it should
-       *     point after the newly inserted text.
+       * @position: (inout) (type int): the position, in characters,
+       *     at which to insert the new text. this is an in-out
+       *     parameter.  After the signal emission is finished, it
+       *     should point after the newly inserted text.
        *
        * This signal is emitted when text is inserted into
        * the widget by the user. The default handler for
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index 0b905db13f..880db89716 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -6814,7 +6814,7 @@ gtk_entry_set_buffer (GtkEntry       *entry,
 /**
  * gtk_entry_get_text_area:
  * @entry: a #GtkEntry
- * @text_area: Return location for the text area.
+ * @text_area: (out): Return location for the text area.
  *
  * Gets the area where the entry's text is drawn. This function is
  * useful when drawing something to the entry in a draw callback.
@@ -7485,8 +7485,8 @@ gtk_entry_text_index_to_layout_index (GtkEntry *entry,
 /**
  * gtk_entry_get_layout_offsets:
  * @entry: a #GtkEntry
- * @x: (allow-none): location to store X offset of layout, or %NULL
- * @y: (allow-none): location to store Y offset of layout, or %NULL
+ * @x: (out) (allow-none): location to store X offset of layout, or %NULL
+ * @y: (out) (allow-none): location to store Y offset of layout, or %NULL
  *
  *
  * Obtains the position of the #PangoLayout used to render text
@@ -8293,7 +8293,7 @@ gtk_entry_get_current_icon_drag_source (GtkEntry *entry)
  * gtk_entry_get_icon_area:
  * @entry: A #GtkEntry
  * @icon_pos: Icon position
- * @icon_area: Return location for the icon's area
+ * @icon_area: (out): Return location for the icon's area
  *
  * Gets the area where entry's icon at @icon_pos is drawn.
  * This function is useful when drawing something to the
diff --git a/gtk/gtkframe.c b/gtk/gtkframe.c
index 5e6e2fc787..62e0dc160e 100644
--- a/gtk/gtkframe.c
+++ b/gtk/gtkframe.c
@@ -522,8 +522,10 @@ gtk_frame_set_label_align (GtkFrame *frame,
 /**
  * gtk_frame_get_label_align:
  * @frame: a #GtkFrame
- * @xalign: (allow-none): location to store X alignment of frame's label, or %NULL
- * @yalign: (allow-none): location to store X alignment of frame's label, or %NULL
+ * @xalign: (out) (allow-none): location to store X alignment of
+ *     frame's label, or %NULL
+ * @yalign: (out) (allow-none): location to store X alignment of
+ *     frame's label, or %NULL
  * 
  * Retrieves the X and Y alignment of the frame's label. See
  * gtk_frame_set_label_align().
diff --git a/gtk/gtkhsv.c b/gtk/gtkhsv.c
index 62356bc35b..427a7d5eea 100644
--- a/gtk/gtkhsv.c
+++ b/gtk/gtkhsv.c
@@ -1330,9 +1330,9 @@ gtk_hsv_set_color (GtkHSV *hsv,
 /**
  * gtk_hsv_get_color:
  * @hsv: An HSV color selector
- * @h: Return value for the hue
- * @s: Return value for the saturation
- * @v: Return value for the value
+ * @h: (out): Return value for the hue
+ * @s: (out): Return value for the saturation
+ * @v: (out): Return value for the value
  *
  * Queries the current color in an HSV color selector.
  * Returned values will be in the [0.0, 1.0] range.
@@ -1400,8 +1400,8 @@ gtk_hsv_set_metrics (GtkHSV *hsv,
 /**
  * gtk_hsv_get_metrics:
  * @hsv: An HSV color selector
- * @size: Return value for the diameter of the hue ring
- * @ring_width: Return value for the width of the hue ring
+ * @size: (out): Return value for the diameter of the hue ring
+ * @ring_width: (out): Return value for the width of the hue ring
  *
  * Queries the size and ring width of an HSV color selector.
  *
@@ -1457,9 +1457,9 @@ gtk_hsv_is_adjusting (GtkHSV *hsv)
  * @h: Hue
  * @s: Saturation
  * @v: Value
- * @r: Return value for the red component
- * @g: Return value for the green component
- * @b: Return value for the blue component
+ * @r: (out): Return value for the red component
+ * @g: (out): Return value for the green component
+ * @b: (out): Return value for the blue component
  *
  * Converts a color from HSV space to RGB.
  * Input values must be in the [0.0, 1.0] range; 
@@ -1496,9 +1496,9 @@ gtk_hsv_to_rgb (gdouble  h,
  * @r: Red
  * @g: Green
  * @b: Blue
- * @h: Return value for the hue component
- * @s: Return value for the saturation component
- * @v: Return value for the value component
+ * @h: (out): Return value for the hue component
+ * @s: (out): Return value for the saturation component
+ * @v: (out): Return value for the value component
  *
  * Converts a color from RGB space to HSV.
  * Input values must be in the [0.0, 1.0] range;
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index 62b842982c..f67762fcc1 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -688,7 +688,8 @@ gtk_icon_theme_finalize (GObject *object)
 /**
  * gtk_icon_theme_set_search_path:
  * @icon_theme: a #GtkIconTheme
- * @path: array of directories that are searched for icon themes
+ * @path: (array length=n_elements) (element-type filename): array of
+ *     directories that are searched for icon themes
  * @n_elements: number of elements in @path.
  * 
  * Sets the search path for the icon theme object. When looking
@@ -1440,7 +1441,8 @@ gtk_icon_theme_lookup_icon (GtkIconTheme       *icon_theme,
 /**
  * gtk_icon_theme_choose_icon:
  * @icon_theme: a #GtkIconTheme
- * @icon_names: %NULL-terminated array of icon names to lookup
+ * @icon_names: (array zero-terminated=1): %NULL-terminated array of
+ *     icon names to lookup
  * @size: desired icon size
  * @flags: flags modifying the behavior of the icon lookup
  * 
@@ -1616,9 +1618,9 @@ add_size (gpointer  key,
  * that the icon is available in a scalable format. The array 
  * is zero-terminated.
  * 
- * Return value: An newly allocated array describing the sizes at
- * which the icon is available. The array should be freed with g_free()
- * when it is no longer needed.
+ * Return value: (array zero-terminated=1): An newly allocated array
+ * describing the sizes at which the icon is available. The array
+ * should be freed with g_free() when it is no longer needed.
  *
  * Since: 2.6
  **/
@@ -3164,8 +3166,9 @@ _gtk_icon_info_load_symbolic_internal (GtkIconInfo  *icon_info,
  *     of the icon or %NULL to use the default color
  * @error_color: (allow-none): a #GdkRGBA representing the error color
  *     of the icon or %NULL to use the default color (allow-none)
- * @was_symbolic: (allow-none): a #gboolean, returns whether the loaded icon
- *     was a symbolic one and whether the @fg color was applied to it.
+ * @was_symbolic: (out) (allow-none): a #gboolean, returns whether the
+ *     loaded icon was a symbolic one and whether the @fg color was
+ *     applied to it.
  * @error: (allow-none): location to store error information on failure,
  *     or %NULL.
  *
@@ -3247,8 +3250,9 @@ gtk_icon_info_load_symbolic (GtkIconInfo  *icon_info,
  * gtk_icon_info_load_symbolic_for_context:
  * @icon_info: a #GtkIconInfo
  * @context: a #GtkStyleContext
- * @was_symbolic: (allow-none): a #gboolean, returns whether the loaded icon
- *     was a symbolic one and whether the @fg color was applied to it.
+ * @was_symbolic: (out) (allow-none): a #gboolean, returns whether the
+ *     loaded icon was a symbolic one and whether the @fg color was
+ *     applied to it.
  * @error: (allow-none): location to store error information on failure,
  *     or %NULL.
  *
@@ -3328,8 +3332,9 @@ gtk_icon_info_load_symbolic_for_context (GtkIconInfo      *icon_info,
  * @icon_info: a #GtkIconInfo
  * @style: a #GtkStyle to take the colors from
  * @state: the widget state to use for colors
- * @was_symbolic: (allow-none): a #gboolean, returns whether the loaded icon
- *     was a symbolic one and whether the @fg color was applied to it.
+ * @was_symbolic: (out) (allow-none): a #gboolean, returns whether the
+ *     loaded icon was a symbolic one and whether the @fg color was
+ *     applied to it.
  * @error: (allow-none): location to store error information on failure,
  *     or %NULL.
  *
@@ -3463,7 +3468,7 @@ icon_info_scale_point (GtkIconInfo  *icon_info,
 /**
  * gtk_icon_info_get_embedded_rect:
  * @icon_info: a #GtkIconInfo
- * @rectangle: #GdkRectangle in which to store embedded
+ * @rectangle: (out): #GdkRectangle in which to store embedded
  *   rectangle coordinates; coordinates are only stored
  *   when this function returns %TRUE.
  *
diff --git a/gtk/gtkiconview.c b/gtk/gtkiconview.c
index ee9be8bd74..161de84c01 100644
--- a/gtk/gtkiconview.c
+++ b/gtk/gtkiconview.c
@@ -1934,8 +1934,9 @@ gtk_icon_view_set_cursor (GtkIconView     *icon_view,
 /**
  * gtk_icon_view_get_cursor:
  * @icon_view: A #GtkIconView
- * @path: (allow-none) (out): Return location for the current cursor path, or %NULL
- * @cell: (allow-none) (out): Return location the current focus cell, or %NULL
+ * @path: (out) (allow-none): Return location for the current cursor path,
+ *        or %NULL
+ * @cell: (out) (allow-none): Return location the current focus cell, or %NULL
  *
  * Fills in @path and @cell with the current cursor path and cell. 
  * If the cursor isn't currently set, then *@path will be %NULL.  
@@ -4202,8 +4203,8 @@ gtk_icon_view_new_with_model (GtkTreeModel *model)
  * @icon_view: a #GtkIconView 
  * @wx: X coordinate relative to the widget
  * @wy: Y coordinate relative to the widget
- * @bx: return location for bin_window X coordinate
- * @by: return location for bin_window Y coordinate
+ * @bx: (out): return location for bin_window X coordinate
+ * @by: (out): return location for bin_window Y coordinate
  * 
  * Converts widget coordinates to coordinates for the bin_window,
  * as expected by e.g. gtk_icon_view_get_path_at_pos(). 
@@ -4274,9 +4275,9 @@ gtk_icon_view_get_path_at_pos (GtkIconView *icon_view,
  * @icon_view: A #GtkIconView.
  * @x: The x position to be identified
  * @y: The y position to be identified
- * @path: (allow-none) (out): Return location for the path, or %NULL
- * @cell: (allow-none) (out): Return location for the renderer responsible for
- *   the cell at (@x, @y), or %NULL
+ * @path: (out) (allow-none): Return location for the path, or %NULL
+ * @cell: (out) (allow-none): Return location for the renderer
+ *   responsible for the cell at (@x, @y), or %NULL
  * 
  * Finds the path at the point (@x, @y), relative to bin_window coordinates.
  * In contrast to gtk_icon_view_get_path_at_pos(), this function also 
@@ -4407,8 +4408,8 @@ gtk_icon_view_set_tooltip_cell (GtkIconView     *icon_view,
 /**
  * gtk_icon_view_get_tooltip_context:
  * @icon_view: an #GtkIconView
- * @x: the x coordinate (relative to widget coordinates)
- * @y: the y coordinate (relative to widget coordinates)
+ * @x: (inout): the x coordinate (relative to widget coordinates)
+ * @y: (inout): the y coordinate (relative to widget coordinates)
  * @keyboard_tip: whether this is a keyboard tooltip or not
  * @model: (out) (allow-none): a pointer to receive a #GtkTreeModel or %NULL
  * @path: (out) (allow-none): a pointer to receive a #GtkTreePath or %NULL
@@ -4585,8 +4586,9 @@ gtk_icon_view_get_tooltip_column (GtkIconView *icon_view)
 /**
  * gtk_icon_view_get_visible_range:
  * @icon_view: A #GtkIconView
- * @start_path: (allow-none) (out): Return location for start of region, or %NULL
- * @end_path: (allow-none) (out): Return location for end of region, or %NULL
+ * @start_path: (out) (allow-none): Return location for start of region,
+ *              or %NULL
+ * @end_path: (out) (allow-none): Return location for end of region, or %NULL
  * 
  * Sets @start_path and @end_path to be the first and last visible path. 
  * Note that there may be invisible paths in between.
@@ -6718,8 +6720,9 @@ gtk_icon_view_set_drag_dest_item (GtkIconView              *icon_view,
 /**
  * gtk_icon_view_get_drag_dest_item:
  * @icon_view: a #GtkIconView
- * @path: (allow-none) (out): Return location for the path of the highlighted item, or %NULL.
- * @pos: (allow-none) (out): Return location for the drop position, or %NULL
+ * @path: (out) (allow-none): Return location for the path of
+ *        the highlighted item, or %NULL.
+ * @pos: (out) (allow-none): Return location for the drop position, or %NULL
  * 
  * Gets information about the item that is highlighted for feedback.
  *
@@ -6749,8 +6752,9 @@ gtk_icon_view_get_drag_dest_item (GtkIconView              *icon_view,
  * @icon_view: a #GtkIconView
  * @drag_x: the position to determine the destination item for
  * @drag_y: the position to determine the destination item for
- * @path: (allow-none) (out): Return location for the path of the item, or %NULL.
- * @pos: (allow-none) (out): Return location for the drop position, or %NULL
+ * @path: (out) (allow-none): Return location for the path of the item,
+ *    or %NULL.
+ * @pos: (out) (allow-none): Return location for the drop position, or %NULL
  * 
  * Determines the destination item for a given position.
  * 
diff --git a/gtk/gtkimcontext.c b/gtk/gtkimcontext.c
index 245c59b35a..3569ba735d 100644
--- a/gtk/gtkimcontext.c
+++ b/gtk/gtkimcontext.c
@@ -419,12 +419,12 @@ gtk_im_context_set_client_window (GtkIMContext *context,
 /**
  * gtk_im_context_get_preedit_string:
  * @context:    a #GtkIMContext
- * @str:        location to store the retrieved string. The
- *              string retrieved must be freed with g_free ().
- * @attrs:      location to store the retrieved attribute list.
- *              When you are done with this list, you must
- *              unreference it with pango_attr_list_unref().
- * @cursor_pos: location to store position of cursor (in characters)
+ * @str:        (out) (transfer full): location to store the retrieved
+ *              string. The string retrieved must be freed with g_free().
+ * @attrs:      (out) (transfer full): location to store the retrieved
+ *              attribute list.  When you are done with this list, you
+ *              must unreference it with pango_attr_list_unref().
+ * @cursor_pos: (out): location to store position of cursor (in characters)
  *              within the preedit string.  
  * 
  * Retrieve the current preedit string for the input context,
@@ -620,12 +620,12 @@ gtk_im_context_set_surrounding (GtkIMContext  *context,
 /**
  * gtk_im_context_get_surrounding:
  * @context: a #GtkIMContext
- * @text: location to store a UTF-8 encoded string of text
- *        holding context around the insertion point.
- *        If the function returns %TRUE, then you must free
- *        the result stored in this location with g_free().
- * @cursor_index: location to store byte index of the insertion cursor
- *        within @text.
+ * @text: (out) (transfer full): location to store a UTF-8 encoded
+ *        string of text holding context around the insertion point.
+ *        If the function returns %TRUE, then you must free the result
+ *        stored in this location with g_free().
+ * @cursor_index: (out) location to store byte index of the insertion
+ *        cursor within @text.
  * 
  * Retrieves context around the insertion point. Input methods
  * typically want context in order to constrain input text based on
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 5f4ba06642..272e6de2d9 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -5469,8 +5469,8 @@ gtk_label_select_region  (GtkLabel *label,
 /**
  * gtk_label_get_selection_bounds:
  * @label: a #GtkLabel
- * @start: return location for start of selection, as a character offset
- * @end: return location for end of selection, as a character offset
+ * @start: (out): return location for start of selection, as a character offset
+ * @end: (out): return location for end of selection, as a character offset
  * 
  * Gets the selected range of characters in the label, returning %TRUE
  * if there's a selection.
@@ -5568,8 +5568,8 @@ gtk_label_get_layout (GtkLabel *label)
 /**
  * gtk_label_get_layout_offsets:
  * @label: a #GtkLabel
- * @x: (allow-none): location to store X offset of layout, or %NULL
- * @y: (allow-none): location to store Y offset of layout, or %NULL
+ * @x: (out) (allow-none): location to store X offset of layout, or %NULL
+ * @y: (out) (allow-none): location to store Y offset of layout, or %NULL
  *
  * Obtains the coordinates where the label will draw the #PangoLayout
  * representing the text in the label; useful to convert mouse events
diff --git a/gtk/gtklayout.c b/gtk/gtklayout.c
index 3cb0a8295d..f9ac989e9a 100644
--- a/gtk/gtklayout.c
+++ b/gtk/gtklayout.c
@@ -582,8 +582,10 @@ gtk_layout_set_size (GtkLayout     *layout,
 /**
  * gtk_layout_get_size:
  * @layout: a #GtkLayout
- * @width: (allow-none): location to store the width set on @layout, or %NULL
- * @height: (allow-none): location to store the height set on @layout, or %NULL
+ * @width: (out) (allow-none): location to store the width set on
+ *     @layout, or %NULL
+ * @height: (out) (allow-none): location to store the height set on
+ *     @layout, or %NULL
  *
  * Gets the size that has been set on the layout, and that determines
  * the total extents of the layout's scrollbar area. See
diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index 79077b8d91..7004e15759 100644
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -975,12 +975,13 @@ gtk_get_option_group (gboolean open_default_display)
 /**
  * gtk_init_with_args:
  * @argc: a pointer to the number of command line arguments
- * @argv: a pointer to the array of command line arguments
+ * @argv: (inout) (array length=argc): a pointer to the array of
+ * command line arguments
  * @parameter_string: a string which is displayed in
  *    the first line of <option>--help</option> output, after
  *    <literal><replaceable>programname</replaceable> [OPTION...]</literal>
- * @entries: a %NULL-terminated array of #GOptionEntrys
- *    describing the options of your program
+ * @entries: (array zero-terminated=1): a %NULL-terminated array
+ *    of #GOptionEntrys describing the options of your program
  * @translation_domain: a translation domain to use for translating
  *    the <option>--help</option> output for the options in @entries
  *    and the @parameter_string with gettext(), or %NULL
@@ -2417,7 +2418,7 @@ gtk_get_current_event_time (void)
 
 /**
  * gtk_get_current_event_state:
- * @state: a location to store the state of the current event
+ * @state: (out): a location to store the state of the current event
  *
  * If there is a current event and it has a state field, place
  * that state field in @state and return %TRUE, otherwise return
diff --git a/gtk/gtkmisc.c b/gtk/gtkmisc.c
index bc24ae68a2..c35bd73d21 100644
--- a/gtk/gtkmisc.c
+++ b/gtk/gtkmisc.c
@@ -239,8 +239,8 @@ gtk_misc_set_alignment (GtkMisc *misc,
 /**
  * gtk_misc_get_alignment:
  * @misc: a #GtkMisc
- * @xalign: (allow-none): location to store X alignment of @misc, or %NULL
- * @yalign: (allow-none): location to store Y alignment of @misc, or %NULL
+ * @xalign: (out) (allow-none): location to store X alignment of @misc, or %NULL
+ * @yalign: (out) (allow-none): location to store Y alignment of @misc, or %NULL
  *
  * Gets the X and Y alignment of the widget within its allocation. 
  * See gtk_misc_set_alignment().
@@ -300,8 +300,10 @@ gtk_misc_set_padding (GtkMisc *misc,
 /**
  * gtk_misc_get_padding:
  * @misc: a #GtkMisc
- * @xpad: (allow-none): location to store padding in the X direction, or %NULL
- * @ypad: (allow-none): location to store padding in the Y direction, or %NULL
+ * @xpad: (out) (allow-none): location to store padding in the X
+ *        direction, or %NULL
+ * @ypad: (out) (allow-none): location to store padding in the Y
+ *        direction, or %NULL
  *
  * Gets the padding in the X and Y directions of the widget. 
  * See gtk_misc_set_padding().
diff --git a/gtk/gtkprintcontext.c b/gtk/gtkprintcontext.c
index 9cd0298f46..d37278ccdb 100644
--- a/gtk/gtkprintcontext.c
+++ b/gtk/gtkprintcontext.c
@@ -383,10 +383,10 @@ gtk_print_context_get_dpi_y (GtkPrintContext *context)
 /**
  * gtk_print_context_get_hard_margins:
  * @context: a #GtkPrintContext
- * @top: top hardware printer margin
- * @bottom: bottom hardware printer margin
- * @left: left hardware printer margin
- * @right: right hardware printer margin
+ * @top: (out): top hardware printer margin
+ * @bottom: (out): bottom hardware printer margin
+ * @left: (out): left hardware printer margin
+ * @right: (out): right hardware printer margin
  *
  * Obtains the hardware printer margins of the #GtkPrintContext, in units.
  *
diff --git a/gtk/gtkprinter.c b/gtk/gtkprinter.c
index 0a416d69e2..95df2f0792 100644
--- a/gtk/gtkprinter.c
+++ b/gtk/gtkprinter.c
@@ -994,10 +994,10 @@ gtk_printer_get_default_page_size (GtkPrinter *printer)
 /**
  * gtk_printer_get_hard_margins:
  * @printer: a #GtkPrinter
- * @top: a location to store the top margin in
- * @bottom: a location to store the bottom margin in
- * @left: a location to store the left margin in
- * @right: a location to store the right margin in
+ * @top: (out): a location to store the top margin in
+ * @bottom: (out): a location to store the bottom margin in
+ * @left: (out): a location to store the left margin in
+ * @right: (out): a location to store the right margin in
  *
  * Retrieve the hard margins of @printer, i.e. the margins that define
  * the area at the borders of the paper that the printer cannot print to.
diff --git a/gtk/gtkprintjob.c b/gtk/gtkprintjob.c
index 062beaf19c..634e6b45ca 100644
--- a/gtk/gtkprintjob.c
+++ b/gtk/gtkprintjob.c
@@ -749,7 +749,8 @@ gtk_print_job_set_pages (GtkPrintJob   *job,
  *
  * Gets the page ranges for this job.
  *
- * Returns: a pointer to an array of #GtkPageRange structs
+ * Returns: (array length=n_ranges) (transfer none): a pointer to an
+ * array of #GtkPageRange structs
  *
  * Since: 3.0
  */
@@ -764,7 +765,9 @@ gtk_print_job_get_page_ranges (GtkPrintJob *job,
 /**
  * gtk_print_job_set_page_ranges:
  * @job: a #GtkPrintJob
- * @ranges: pointer to an array of #GtkPageRange structs
+
+ * @ranges: (array length=n_ranges): pointer to an array of
+ *          #GtkPageRange structs
  * @n_ranges: the length of the @ranges array
  *
  * Sets the page ranges for this job.
diff --git a/gtk/gtkprintsettings.c b/gtk/gtkprintsettings.c
index 655c971514..64c8e518a2 100644
--- a/gtk/gtkprintsettings.c
+++ b/gtk/gtkprintsettings.c
@@ -1409,12 +1409,13 @@ gtk_print_settings_set_print_pages (GtkPrintSettings *settings,
 /**
  * gtk_print_settings_get_page_ranges:
  * @settings: a #GtkPrintSettings
- * @num_ranges: return location for the length of the returned array
+ * @num_ranges: (out): return location for the length of the returned array
  *
  * Gets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES.
  *
- * Return value: (transfer full): an array of #GtkPageRange<!-- -->s.
- *     Use g_free() to free the array when it is no longer needed.
+ * Return value: (array length=num_ranges) (transfer full): an array
+ *     of #GtkPageRange<!-- -->s.  Use g_free() to free the array when
+ *     it is no longer needed.
  *
  * Since: 2.10
  */
@@ -1471,7 +1472,7 @@ gtk_print_settings_get_page_ranges (GtkPrintSettings *settings,
 /**
  * gtk_print_settings_set_page_ranges:
  * @settings: a #GtkPrintSettings
- * @page_ranges: an array of #GtkPageRange<!-- -->s
+ * @page_ranges: (array length=num_ranges): an array of #GtkPageRange<!-- -->s
  * @num_ranges: the length of @page_ranges
  * 
  * Sets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES.
diff --git a/gtk/gtkrange.c b/gtk/gtkrange.c
index dc4b60a7b2..e5bbaa994a 100644
--- a/gtk/gtkrange.c
+++ b/gtk/gtkrange.c
@@ -1031,7 +1031,7 @@ gtk_range_get_min_slider_size (GtkRange *range)
 /**
  * gtk_range_get_range_rect:
  * @range: a #GtkRange
- * @range_rect: return location for the range rectangle
+ * @range_rect: (out): return location for the range rectangle
  *
  * This function returns the area that contains the range's trough
  * and its steppers, in widget->window coordinates.
@@ -1059,8 +1059,10 @@ gtk_range_get_range_rect (GtkRange     *range,
 /**
  * gtk_range_get_slider_range:
  * @range: a #GtkRange
- * @slider_start: (allow-none): return location for the slider's start, or %NULL
- * @slider_end: (allow-none): return location for the slider's end, or %NULL
+ * @slider_start: (out) (allow-none): return location for the slider's
+ *     start, or %NULL
+ * @slider_end: (out) (allow-none): return location for the slider's
+ *     end, or %NULL
  *
  * This function returns sliders range along the long dimension,
  * in widget->window coordinates.
diff --git a/gtk/gtkrc.c b/gtk/gtkrc.c
index 5ed4cb1994..eccf8a321e 100644
--- a/gtk/gtkrc.c
+++ b/gtk/gtkrc.c
@@ -366,9 +366,10 @@ gtk_rc_set_default_files (gchar **filenames)
  * Retrieves the current list of RC files that will be parsed
  * at the end of gtk_init().
  *
- * Return value: (transfer none): A %NULL-terminated array of filenames.
- *     This memory is owned by GTK+ and must not be freed by the application.
- *     If you want to store this information, you should make a copy.
+ * Return value: (transfer none) (array zero-terminated=1) (element-type filename):
+ *      A %NULL-terminated array of filenames.  This memory is owned
+ *     by GTK+ and must not be freed by the application.  If you want
+ *     to store this information, you should make a copy.
  *
  * Deprecated:3.0: Use #GtkStyleContext instead
  **/
@@ -968,7 +969,7 @@ gtk_rc_find_module_in_path (const gchar *module_file)
 /**
  * gtk_rc_parse_state:
  * @scanner:
- * @state:
+ * @state: (out):
  *
  * Deprecated:3.0: Use #GtkCssProvider instead
  */
@@ -1026,7 +1027,7 @@ gtk_rc_parse_state (GScanner	 *scanner,
 /**
  * gtk_rc_parse_priority:
  * @scanner:
- * @priority:
+ * @priority: (out):
  *
  * Deprecated:3.0: Use #GtkCssProvider instead
  */
@@ -1083,7 +1084,8 @@ gtk_rc_parse_priority (GScanner	           *scanner,
 /**
  * gtk_rc_parse_color:
  * @scanner: a #GScanner
- * @color: a pointer to a #GdkColor structure in which to store the result
+ * @color: (out): a pointer to a #GdkColor structure in which to store
+ *     the result
  *
  * Parses a color in the <link linkend="color=format">format</link> expected
  * in a RC file. 
@@ -1107,7 +1109,8 @@ gtk_rc_parse_color (GScanner *scanner,
  * gtk_rc_parse_color_full:
  * @scanner: a #GScanner
  * @style: (allow-none): a #GtkRcStyle, or %NULL
- * @color: a pointer to a #GdkColor structure in which to store the result
+ * @color: (out): a pointer to a #GdkColor structure in which to store
+ *     the result
  *
  * Parses a color in the <link linkend="color=format">format</link> expected
  * in a RC file. If @style is not %NULL, it will be consulted to resolve
diff --git a/gtk/gtkrecentchooser.c b/gtk/gtkrecentchooser.c
index 6011ba634d..b6873ec5d4 100644
--- a/gtk/gtkrecentchooser.c
+++ b/gtk/gtkrecentchooser.c
@@ -859,8 +859,9 @@ gtk_recent_chooser_get_items (GtkRecentChooser *chooser)
  *
  * Since the returned array is %NULL terminated, @length may be %NULL.
  * 
- * Return value: (transfer full): A newly allocated, %NULL-terminated array
- *     of strings. Use g_strfreev() to free it.
+ * Return value: (array length=length zero-terminated=1) (transfer full):
+ *     A newly allocated, %NULL-terminated array of strings. Use
+ *     g_strfreev() to free it.
  *
  * Since: 2.10
  */
diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c
index a44dd9e1da..a69ae84036 100644
--- a/gtk/gtkscale.c
+++ b/gtk/gtkscale.c
@@ -1400,8 +1400,8 @@ gtk_scale_get_layout (GtkScale *scale)
 /**
  * gtk_scale_get_layout_offsets:
  * @scale: a #GtkScale
- * @x: (allow-none): location to store X offset of layout, or %NULL
- * @y: (allow-none): location to store Y offset of layout, or %NULL
+ * @x: (out) (allow-none): location to store X offset of layout, or %NULL
+ * @y: (out) (allow-none): location to store Y offset of layout, or %NULL
  *
  * Obtains the coordinates where the scale will draw the 
  * #PangoLayout representing the text in the scale. Remember
diff --git a/gtk/gtkscalebutton.c b/gtk/gtkscalebutton.c
index 7be5660ead..a688705338 100644
--- a/gtk/gtkscalebutton.c
+++ b/gtk/gtkscalebutton.c
@@ -559,8 +559,9 @@ gtk_scale_button_dispose (GObject *object)
  * @max: the maximum value of the scale (usually 100)
  * @step: the stepping of value when a scroll-wheel event,
  *        or up/down arrow event occurs (usually 2)
- * @icons: (allow-none): a %NULL-terminated array of icon names, or %NULL if
- *         you want to set the list later with gtk_scale_button_set_icons()
+ * @icons: (allow-none) (array zero-terminated=1): a %NULL-terminated
+ *         array of icon names, or %NULL if you want to set the list
+ *         later with gtk_scale_button_set_icons()
  *
  * Creates a #GtkScaleButton, with a range between @min and @max, with
  * a stepping of @step.
@@ -640,7 +641,7 @@ gtk_scale_button_set_value (GtkScaleButton *button,
 /**
  * gtk_scale_button_set_icons:
  * @button: a #GtkScaleButton
- * @icons: a %NULL-terminated array of icon names
+ * @icons: (array zero-terminated=1): a %NULL-terminated array of icon names
  *
  * Sets the icons to be used by the scale button.
  * For details, see the #GtkScaleButton:icons property.
diff --git a/gtk/gtkscrolledwindow.c b/gtk/gtkscrolledwindow.c
index f4a02994af..c8f4539440 100644
--- a/gtk/gtkscrolledwindow.c
+++ b/gtk/gtkscrolledwindow.c
@@ -796,10 +796,10 @@ gtk_scrolled_window_set_policy (GtkScrolledWindow *scrolled_window,
 /**
  * gtk_scrolled_window_get_policy:
  * @scrolled_window: a #GtkScrolledWindow
- * @hscrollbar_policy: location to store the policy for the horizontal 
- *     scrollbar, or %NULL.
- * @vscrollbar_policy: location to store the policy for the vertical
- *     scrollbar, or %NULL.
+ * @hscrollbar_policy: (out) (allow-none): location to store the policy 
+ *     for the horizontal scrollbar, or %NULL.
+ * @vscrollbar_policy: (out) (allow-none): location to store the policy
+ *     for the vertical scrollbar, or %NULL.
  * 
  * Retrieves the current policy values for the horizontal and vertical
  * scrollbars. See gtk_scrolled_window_set_policy().
diff --git a/gtk/gtkselection.c b/gtk/gtkselection.c
index 1970bc855a..105acb8a31 100644
--- a/gtk/gtkselection.c
+++ b/gtk/gtkselection.c
@@ -216,8 +216,8 @@ static const char gtk_selection_handler_key[] = "gtk-selection-handlers";
 
 /**
  * gtk_target_list_new:
- * @targets: Pointer to an array of #GtkTargetEntry
- * @ntargets:  number of entries in @targets.
+ * @targets: (array length=ntargets): Pointer to an array of #GtkTargetEntry
+ * @ntargets: number of entries in @targets.
  * 
  * Creates a new #GtkTargetList from an array of #GtkTargetEntry.
  * 
@@ -499,7 +499,7 @@ gtk_target_list_add_uri_targets (GtkTargetList *list,
 /**
  * gtk_target_list_add_table:
  * @list: a #GtkTargetList
- * @targets: the table of #GtkTargetEntry
+ * @targets: (array length=ntargets): the table of #GtkTargetEntry
  * @ntargets: number of targets in the table
  * 
  * Prepends a table of #GtkTargetEntry to a target list.
@@ -598,14 +598,14 @@ gtk_target_list_find (GtkTargetList *list,
 /**
  * gtk_target_table_new_from_list:
  * @list: a #GtkTargetList
- * @n_targets: return location for the number ot targets in the table
+ * @n_targets: (out): return location for the number ot targets in the table
  *
  * This function creates an #GtkTargetEntry array that contains the
  * same targets as the passed %list. The returned table is newly
  * allocated and should be freed using gtk_target_table_free() when no
  * longer needed.
  *
- * Return value: the new table.
+ * Return value: (array length=n_targets) (transfer full): the new table.
  *
  * Since: 2.10
  **/
@@ -639,7 +639,7 @@ gtk_target_table_new_from_list (GtkTargetList *list,
 
 /**
  * gtk_target_table_free:
- * @targets: a #GtkTargetEntry array
+ * @targets: (array length=n_targets): a #GtkTargetEntry array
  * @n_targets: the number of entries in the array
  *
  * This function frees a target table as returned by
@@ -931,7 +931,7 @@ gtk_selection_add_target (GtkWidget	    *widget,
  * gtk_selection_add_targets:
  * @widget: a #GtkWidget
  * @selection: the selection
- * @targets: a table of targets to add
+ * @targets: (array length=ntargets): a table of targets to add
  * @ntargets:  number of entries in @targets
  * 
  * Prepends a table of targets to the list of supported targets
@@ -1251,7 +1251,7 @@ gtk_selection_data_get_length (const GtkSelectionData *selection_data)
 /**
  * gtk_selection_data_get_data_with_length:
  * @selection_data: a pointer to a #GtkSelectionData structure
- * @length: return location for length of the data segment
+ * @length: (out): return location for length of the data segment
  *
  * Retrieves the raw data of the selection along with its length.
  *
@@ -1752,7 +1752,8 @@ gtk_selection_data_get_pixbuf (const GtkSelectionData *selection_data)
 /**
  * gtk_selection_data_set_uris:
  * @selection_data: a #GtkSelectionData
- * @uris: a %NULL-terminated array of strings holding URIs
+ * @uris: (array zero-terminated=1): a %NULL-terminated array of
+ *     strings holding URIs
  * 
  * Sets the contents of the selection from a list of URIs.
  * The string is converted to the form determined by
@@ -1852,8 +1853,9 @@ gtk_selection_data_get_uris (const GtkSelectionData *selection_data)
 /**
  * gtk_selection_data_get_targets:
  * @selection_data: a #GtkSelectionData object
- * @targets: location to store an array of targets. The result
- *           stored here must be freed with g_free().
+ * @targets: (out) (array length=n_atoms) (transfer container):
+ *           location to store an array of targets. The result stored
+ *           here must be freed with g_free().
  * @n_atoms: location to store number of items in @targets.
  * 
  * Gets the contents of @selection_data as an array of targets.
@@ -1895,7 +1897,7 @@ gtk_selection_data_get_targets (const GtkSelectionData  *selection_data,
 
 /**
  * gtk_targets_include_text:
- * @targets: an array of #GdkAtom<!-- -->s
+ * @targets: (array length=n_targets): an array of #GdkAtom<!-- -->s
  * @n_targets: the length of @targets
  * 
  * Determines if any of the targets in @targets can be used to
@@ -1940,7 +1942,7 @@ gtk_targets_include_text (GdkAtom *targets,
 
 /**
  * gtk_targets_include_rich_text:
- * @targets: an array of #GdkAtom<!-- -->s
+ * @targets: (array length=n_targets): an array of #GdkAtom<!-- -->s
  * @n_targets: the length of @targets
  * @buffer: a #GtkTextBuffer
  *
@@ -2058,7 +2060,7 @@ gtk_selection_data_targets_include_rich_text (const GtkSelectionData *selection_
 
 /**
  * gtk_targets_include_image:
- * @targets: an array of #GdkAtom<!-- -->s
+ * @targets: (array length=n_targets): an array of #GdkAtom<!-- -->s
  * @n_targets: the length of @targets
  * @writable: whether to accept only targets for which GTK+ knows
  *   how to convert a pixbuf into the format
@@ -2140,7 +2142,7 @@ gtk_selection_data_targets_include_image (const GtkSelectionData *selection_data
 
 /**
  * gtk_targets_include_uri:
- * @targets: an array of #GdkAtom<!-- -->s
+ * @targets: (array length=n_targets): an array of #GdkAtom<!-- -->s
  * @n_targets: the length of @targets
  * 
  * Determines if any of the targets in @targets can be used to
diff --git a/gtk/gtkspinbutton.c b/gtk/gtkspinbutton.c
index 5ba8036d47..e31796855d 100644
--- a/gtk/gtkspinbutton.c
+++ b/gtk/gtkspinbutton.c
@@ -397,7 +397,7 @@ gtk_spin_button_class_init (GtkSpinButtonClass *class)
   /**
    * GtkSpinButton::input:
    * @spin_button: the object on which the signal was emitted
-   * @new_value: return location for the new value
+   * @new_value: (out) (type double): return location for the new value
    *
    * The ::input signal can be used to influence the conversion of
    * the users input into a double value. The signal handler is
@@ -2133,8 +2133,8 @@ gtk_spin_button_set_increments (GtkSpinButton *spin_button,
 /**
  * gtk_spin_button_get_increments:
  * @spin_button: a #GtkSpinButton
- * @step: (allow-none): location to store step increment, or %NULL
- * @page: (allow-none): location to store page increment, or %NULL
+ * @step: (out) (allow-none): location to store step increment, or %NULL
+ * @page: (out) (allow-none): location to store page increment, or %NULL
  *
  * Gets the current step and page the increments used by @spin_button. See
  * gtk_spin_button_set_increments().
@@ -2187,8 +2187,8 @@ gtk_spin_button_set_range (GtkSpinButton *spin_button,
 /**
  * gtk_spin_button_get_range:
  * @spin_button: a #GtkSpinButton
- * @min: (allow-none): location to store minimum allowed value, or %NULL
- * @max: (allow-none): location to store maximum allowed value, or %NULL
+ * @min: (out) (allow-none): location to store minimum allowed value, or %NULL
+ * @max: (out) (allow-none): location to store maximum allowed value, or %NULL
  *
  * Gets the range allowed for @spin_button.
  * See gtk_spin_button_set_range().
diff --git a/gtk/gtkstock.c b/gtk/gtkstock.c
index d6977194b5..fb8deff85e 100644
--- a/gtk/gtkstock.c
+++ b/gtk/gtkstock.c
@@ -122,7 +122,7 @@ real_add (const GtkStockItem *items,
 
 /**
  * gtk_stock_add:
- * @items: a #GtkStockItem or array of items
+ * @items: (array length=n_items): a #GtkStockItem or array of items
  * @n_items: number of #GtkStockItem in @items
  *
  * Registers each of the stock items in @items. If an item already
@@ -144,7 +144,7 @@ gtk_stock_add (const GtkStockItem *items,
 
 /**
  * gtk_stock_add_static:
- * @items: a #GtkStockItem or array of #GtkStockItem
+ * @items: (array length=n_items): a #GtkStockItem or array of #GtkStockItem
  * @n_items: number of items
  *
  * Same as gtk_stock_add(), but doesn't copy @items, so
@@ -163,7 +163,7 @@ gtk_stock_add_static (const GtkStockItem *items,
 /**
  * gtk_stock_lookup:
  * @stock_id: a stock item name
- * @item: stock item to initialize with values
+ * @item: (out): stock item to initialize with values
  * 
  * Fills @item with the registered values for @stock_id, returning %TRUE
  * if @stock_id was known.
diff --git a/gtk/gtkstyle.c b/gtk/gtkstyle.c
index 7d9e5ef6b4..dd445ec5f9 100644
--- a/gtk/gtkstyle.c
+++ b/gtk/gtkstyle.c
@@ -944,7 +944,7 @@ gtk_style_lookup_icon_set (GtkStyle   *style,
  * gtk_style_lookup_color:
  * @style: a #GtkStyle
  * @color_name: the name of the logical color to look up
- * @color: the #GdkColor to fill in
+ * @color: (out): the #GdkColor to fill in
  *
  * Looks up @color_name in the style's logical color mappings,
  * filling in @color and returning %TRUE if found, otherwise
diff --git a/gtk/gtktestutils.c b/gtk/gtktestutils.c
index e1fe5e79ac..bdd374b497 100644
--- a/gtk/gtktestutils.c
+++ b/gtk/gtktestutils.c
@@ -39,7 +39,8 @@
  * gtk_test_init:
  * @argcp: Address of the <parameter>argc</parameter> parameter of the
  *        main() function. Changed if any arguments were handled.
- * @argvp: Address of the <parameter>argv</parameter> parameter of main().
+ * @argvp: (inout) (array length=argcp): Address of the 
+ *        <parameter>argv</parameter> parameter of main().
  *        Any parameters understood by g_test_init() or gtk_init() are
  *        stripped before return.
  * @Varargs: currently unused
@@ -642,7 +643,8 @@ static guint  n_all_registered_types = 0;
 /**
  * gtk_test_list_all_types
  * @n_types: location to store number of types
- * @returns: 0-terminated array of type ids
+ * @returns: (array length=n_types zero-terminated=1) (transfer none):
+ *    0-terminated array of type ids
  *
  * Return the type ids that have been registered after
  * calling gtk_test_register_all_types().
diff --git a/gtk/gtktextbufferrichtext.c b/gtk/gtktextbufferrichtext.c
index 74a934fd35..e4e6836afc 100644
--- a/gtk/gtktextbufferrichtext.c
+++ b/gtk/gtktextbufferrichtext.c
@@ -408,8 +408,8 @@ gtk_text_buffer_deserialize_get_can_create_tags (GtkTextBuffer *buffer,
  * with @buffer using gtk_text_buffer_register_serialize_format() or
  * gtk_text_buffer_register_serialize_tagset()
  *
- * Return value: an array of #GdkAtom<!-- -->s representing the registered
- *               formats.
+ * Return value: (array length=n_formats) (transfer container): an array of
+ *               #GdkAtom<!-- -->s representing the registered formats.
  *
  * Since: 2.10
  **/
@@ -436,8 +436,8 @@ gtk_text_buffer_get_serialize_formats (GtkTextBuffer *buffer,
  * with @buffer using gtk_text_buffer_register_deserialize_format() or
  * gtk_text_buffer_register_deserialize_tagset()
  *
- * Return value: an array of #GdkAtom<!-- -->s representing the registered
- *               formats.
+ * Return value: (array length=n_formats) (transfer container): an array of
+ *               #GdkAtom<!-- -->s representing the registered formats.
  *
  * Since: 2.10
  **/
@@ -471,7 +471,8 @@ gtk_text_buffer_get_deserialize_formats (GtkTextBuffer *buffer,
  * gtk_text_buffer_register_serialize_format() or
  * gtk_text_buffer_register_serialize_tagset() beforehand.
  *
- * Return value: the serialized data, encoded as @format
+ * Return value: (array length=length) (transfer full): the serialized
+ *               data, encoded as @format
  *
  * Since: 2.10
  **/
@@ -520,7 +521,7 @@ gtk_text_buffer_serialize (GtkTextBuffer     *register_buffer,
  * @content_buffer: the #GtkTextBuffer to deserialize into
  * @format: the rich text format to use for deserializing
  * @iter: insertion point for the deserialized text
- * @data: data to deserialize
+ * @data: (array length=length): data to deserialize
  * @length: length of @data
  * @error: return location for a #GError
  *
diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c
index 6ee68bd83b..51c8f8f032 100644
--- a/gtk/gtktextiter.c
+++ b/gtk/gtktextiter.c
@@ -1717,7 +1717,7 @@ gtk_text_iter_get_bytes_in_line (const GtkTextIter   *iter)
 /**
  * gtk_text_iter_get_attributes:
  * @iter: an iterator
- * @values: a #GtkTextAttributes to be filled in
+ * @values: (out): a #GtkTextAttributes to be filled in
  *
  * Computes the effect of any tags applied to this spot in the
  * text. The @values parameter should be initialized to the default
diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c
index e68ca2a11d..7d3d639c3c 100644
--- a/gtk/gtktextview.c
+++ b/gtk/gtktextview.c
@@ -2346,7 +2346,7 @@ gtk_text_view_move_mark_onscreen (GtkTextView *text_view,
 /**
  * gtk_text_view_get_visible_rect:
  * @text_view: a #GtkTextView
- * @visible_rect: rectangle to fill
+ * @visible_rect: (out): rectangle to fill
  *
  * Fills @visible_rect with the currently-visible
  * region of the buffer, in buffer coordinates. Convert to window coordinates
diff --git a/gtk/gtktreednd.c b/gtk/gtktreednd.c
index 68cc171177..367fbd6e66 100644
--- a/gtk/gtktreednd.c
+++ b/gtk/gtktreednd.c
@@ -159,7 +159,8 @@ gtk_tree_drag_source_drag_data_delete (GtkTreeDragSource *drag_source,
  * gtk_tree_drag_source_drag_data_get:
  * @drag_source: a #GtkTreeDragSource
  * @path: row that was dragged
- * @selection_data: a #GtkSelectionData to fill with data from the dragged row
+ * @selection_data: (out): a #GtkSelectionData to fill with data
+ *                  from the dragged row
  * 
  * Asks the #GtkTreeDragSource to fill in @selection_data with a
  * representation of the row at @path. @selection_data->target gives
@@ -306,8 +307,8 @@ gtk_tree_set_row_drag_data (GtkSelectionData *selection_data,
 /**
  * gtk_tree_get_row_drag_data:
  * @selection_data: a #GtkSelectionData
- * @tree_model: a #GtkTreeModel
- * @path: row in @tree_model
+ * @tree_model: (out): a #GtkTreeModel
+ * @path: (out): row in @tree_model
  * 
  * Obtains a @tree_model and @path from selection data of target type
  * %GTK_TREE_MODEL_ROW. Normally called from a drag_data_received handler.
diff --git a/gtk/gtktreemodelfilter.c b/gtk/gtktreemodelfilter.c
index 18e0d594d5..37886ba528 100644
--- a/gtk/gtktreemodelfilter.c
+++ b/gtk/gtktreemodelfilter.c
@@ -3171,7 +3171,7 @@ gtk_tree_model_filter_set_visible_func (GtkTreeModelFilter            *filter,
  * gtk_tree_model_filter_set_modify_func:
  * @filter: A #GtkTreeModelFilter.
  * @n_columns: The number of columns in the filter model.
- * @types: The #GType<!-- -->s of the columns.
+ * @types: (array length=n_columns): The #GType<!-- -->s of the columns.
  * @func: A #GtkTreeModelFilterModifyFunc
  * @data: (allow-none): User data to pass to the modify function, or %NULL.
  * @destroy: (allow-none): Destroy notifier of @data, or %NULL.
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index b3f6c6fc83..7391549095 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -13583,7 +13583,7 @@ gtk_tree_view_get_cell_area_y_offset (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @path: (allow-none): a #GtkTreePath for the row, or %NULL to get only horizontal coordinates
  * @column: (allow-none): a #GtkTreeViewColumn for the column, or %NULL to get only vertical coordinates
- * @rect: rectangle to fill with cell rect
+ * @rect: (out): rectangle to fill with cell rect
  *
  * Fills the bounding rectangle in bin_window coordinates for the cell at the
  * row specified by @path and the column specified by @column.  If @path is
@@ -13716,7 +13716,7 @@ gtk_tree_view_get_row_y_offset (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @path: (allow-none): a #GtkTreePath for the row, or %NULL to get only horizontal coordinates
  * @column: (allow-none): a #GtkTreeViewColumn for the column, or %NULL to get only vertical coordiantes
- * @rect: rectangle to fill with cell background rect
+ * @rect: (out): rectangle to fill with cell background rect
  *
  * Fills the bounding rectangle in bin_window coordinates for the cell at the
  * row specified by @path and the column specified by @column.  If @path is
@@ -13771,7 +13771,7 @@ gtk_tree_view_get_background_area (GtkTreeView        *tree_view,
 /**
  * gtk_tree_view_get_visible_rect:
  * @tree_view: a #GtkTreeView
- * @visible_rect: rectangle to fill
+ * @visible_rect: (out): rectangle to fill
  *
  * Fills @visible_rect with the currently-visible region of the
  * buffer, in tree coordinates. Convert to bin_window coordinates with
@@ -13805,8 +13805,8 @@ gtk_tree_view_get_visible_rect (GtkTreeView  *tree_view,
  * @tree_view: a #GtkTreeView
  * @wx: X coordinate relative to the widget
  * @wy: Y coordinate relative to the widget
- * @tx: return location for tree X coordinate
- * @ty: return location for tree Y coordinate
+ * @tx: (out): return location for tree X coordinate
+ * @ty: (out): return location for tree Y coordinate
  *
  * Converts widget coordinates to coordinates for the
  * tree (the full scrollable area of the tree).
@@ -13837,8 +13837,8 @@ gtk_tree_view_convert_widget_to_tree_coords (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @tx: X coordinate relative to the tree
  * @ty: Y coordinate relative to the tree
- * @wx: return location for widget X coordinate
- * @wy: return location for widget Y coordinate
+ * @wx: (out): return location for widget X coordinate
+ * @wy: (out): return location for widget Y coordinate
  *
  * Converts tree coordinates (coordinates in full scrollable area of the tree)
  * to widget coordinates.
@@ -13869,8 +13869,8 @@ gtk_tree_view_convert_tree_to_widget_coords (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @wx: X coordinate relative to the widget
  * @wy: Y coordinate relative to the widget
- * @bx: return location for bin_window X coordinate
- * @by: return location for bin_window Y coordinate
+ * @bx: (out): return location for bin_window X coordinate
+ * @by: (out): return location for bin_window Y coordinate
  *
  * Converts widget coordinates to coordinates for the bin_window
  * (see gtk_tree_view_get_bin_window()).
@@ -13897,8 +13897,8 @@ gtk_tree_view_convert_widget_to_bin_window_coords (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @bx: bin_window X coordinate
  * @by: bin_window Y coordinate
- * @wx: return location for widget X coordinate
- * @wy: return location for widget Y coordinate
+ * @wx: (out): return location for widget X coordinate
+ * @wy: (out): return location for widget Y coordinate
  *
  * Converts bin_window coordinates (see gtk_tree_view_get_bin_window())
  * to widget relative coordinates.
@@ -13925,8 +13925,8 @@ gtk_tree_view_convert_bin_window_to_widget_coords (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @tx: tree X coordinate
  * @ty: tree Y coordinate
- * @bx: return location for X coordinate relative to bin_window
- * @by: return location for Y coordinate relative to bin_window
+ * @bx: (out): return location for X coordinate relative to bin_window
+ * @by: (out): return location for Y coordinate relative to bin_window
  *
  * Converts tree coordinates (coordinates in full scrollable area of the tree)
  * to bin_window coordinates.
@@ -13953,8 +13953,8 @@ gtk_tree_view_convert_tree_to_bin_window_coords (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @bx: X coordinate relative to bin_window
  * @by: Y coordinate relative to bin_window
- * @tx: return location for tree X coordinate
- * @ty: return location for tree Y coordinate
+ * @tx: (out): return location for tree X coordinate
+ * @ty: (out): return location for tree Y coordinate
  *
  * Converts bin_window coordinates to coordinates for the
  * tree (the full scrollable area of the tree).
@@ -13981,8 +13981,9 @@ gtk_tree_view_convert_bin_window_to_tree_coords (GtkTreeView *tree_view,
 /**
  * gtk_tree_view_get_visible_range:
  * @tree_view: A #GtkTreeView
- * @start_path: (allow-none): Return location for start of region, or %NULL.
- * @end_path: (allow-none): Return location for end of region, or %NULL.
+ * @start_path: (out) (allow-none): Return location for start of region,
+ *              or %NULL.
+ * @end_path: (out) (allow-none): Return location for end of region, or %NULL.
  *
  * Sets @start_path and @end_path to be the first and last visible path.
  * Note that there may be invisible paths in between.
@@ -16267,8 +16268,8 @@ gtk_tree_view_set_tooltip_cell (GtkTreeView       *tree_view,
 /**
  * gtk_tree_view_get_tooltip_context:
  * @tree_view: a #GtkTreeView
- * @x: the x coordinate (relative to widget coordinates)
- * @y: the y coordinate (relative to widget coordinates)
+ * @x: (inout): the x coordinate (relative to widget coordinates)
+ * @y: (inout): the y coordinate (relative to widget coordinates)
  * @keyboard_tip: whether this is a keyboard tooltip or not
  * @model: (out) (allow-none): a pointer to receive a #GtkTreeModel or %NULL
  * @path: (out) (allow-none): a pointer to receive a #GtkTreePath or %NULL
diff --git a/gtk/gtktreeviewcolumn.c b/gtk/gtktreeviewcolumn.c
index 370eb8ab95..ad338e8dc7 100644
--- a/gtk/gtktreeviewcolumn.c
+++ b/gtk/gtktreeviewcolumn.c
@@ -2792,10 +2792,10 @@ gtk_tree_view_column_cell_set_cell_data (GtkTreeViewColumn *tree_column,
  * gtk_tree_view_column_cell_get_size:
  * @tree_column: A #GtkTreeViewColumn.
  * @cell_area: (allow-none): The area a cell in the column will be allocated, or %NULL
- * @x_offset: (allow-none): location to return x offset of a cell relative to @cell_area, or %NULL
- * @y_offset: (allow-none): location to return y offset of a cell relative to @cell_area, or %NULL
- * @width: (allow-none): location to return width needed to render a cell, or %NULL
- * @height: (allow-none): location to return height needed to render a cell, or %NULL
+ * @x_offset: (out) (allow-none): location to return x offset of a cell relative to @cell_area, or %NULL
+ * @y_offset: (out) (allow-none): location to return y offset of a cell relative to @cell_area, or %NULL
+ * @width: (out) (allow-none): location to return width needed to render a cell, or %NULL
+ * @height: (out) (allow-none): location to return height needed to render a cell, or %NULL
  * 
  * Obtains the width and height needed to render the column.  This is used
  * primarily by the #GtkTreeView.
@@ -2994,9 +2994,10 @@ _gtk_tree_view_column_cell_get_dirty (GtkTreeViewColumn  *tree_column)
  * gtk_tree_view_column_cell_get_position:
  * @tree_column: a #GtkTreeViewColumn
  * @cell_renderer: a #GtkCellRenderer
- * @x_offset: return location for the horizontal position of @cell within
- *            @tree_column, may be %NULL
- * @width: return location for the width of @cell, may be %NULL
+ * @x_offset: (out) (allow-none): return location for the horizontal
+ *            position of @cell within @tree_column, may be %NULL
+ * @width: (out) (allow-none): return location for the width of @cell,
+ *         may be %NULL
  *
  * Obtains the horizontal position and size of a cell in a column. If the
  * cell is not found in the column, @start_pos and @width are not changed and
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 90c0ad9cbb..07eaba78d8 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -11538,8 +11538,9 @@ gtk_widget_class_find_style_property (GtkWidgetClass *klass,
  * gtk_widget_class_list_style_properties:
  * @klass: a #GtkWidgetClass
  * @n_properties: location to return the number of style properties found
- * @returns: an newly allocated array of #GParamSpec*. The array must
- *       be freed with g_free().
+ * @returns: (array length=n_properties) (transfer container): an
+ *       newly allocated array of #GParamSpec*. The array must be
+ *       freed with g_free().
  *
  * Returns all style properties of a widget class.
  *
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 48b776cd69..0e8570a6d9 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -3426,7 +3426,7 @@ gtk_window_unrealize_icon (GtkWindow *window)
 /**
  * gtk_window_set_icon_list:
  * @window: a #GtkWindow
- * @list: (element-type GdkPixbuf) (transfer container): list of #GdkPixbuf
+ * @list: (element-type GdkPixbuf): list of #GdkPixbuf
  *
  * Sets up the icon representing a #GtkWindow. The icon is used when
  * the window is minimized (also known as iconified).  Some window
@@ -5581,8 +5581,8 @@ gtk_window_get_has_resize_grip (GtkWindow *window)
 /**
  * gtk_window_get_resize_grip_area:
  * @window: a #GtkWindow
- * @rect: a pointer to a #GdkRectangle which we should store the
- *     resize grip area
+ * @rect: (out): a pointer to a #GdkRectangle which we should store
+ *     the resize grip area
  *
  * If a window has a resize grip, this will retrieve the grip
  * position, width and height into the specified #GdkRectangle.