[introspection] Merge in Gtk-custom.c annotations

The Gtk-custom.c file in gir-repository contained a number of
introspection annotations.  Merge those into the GTK source files.

Some documentation was moved from the tmpl/ files to accomodate
the addition of annotations.

82 files changed, 705 insertions, 561 deletions

diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index 92aad3db66..346b89403d 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -933,7 +933,7 @@ update_name_version (GtkAboutDialog *about)
 /**
  * gtk_about_dialog_set_name:
  * @about: a #GtkAboutDialog
- * @name: the program name
+ * @name: (allow-none): the program name
  *
  * Sets the name to display in the about dialog.
  * If this is not set, it defaults to g_get_application_name().
@@ -1005,7 +1005,7 @@ gtk_about_dialog_get_version (GtkAboutDialog *about)
 /**
  * gtk_about_dialog_set_version:
  * @about: a #GtkAboutDialog
- * @version: the version string
+ * @version: (allow-none): the version string
  *
  * Sets the version string to display in the about dialog.
  *
@@ -1057,7 +1057,7 @@ gtk_about_dialog_get_copyright (GtkAboutDialog *about)
 /**
  * gtk_about_dialog_set_copyright:
  * @about: a #GtkAboutDialog
- * @copyright: the copyright string
+ * @copyright: (allow-none) the copyright string
  *
  * Sets the copyright string to display in the about dialog.
  * This should be a short string of one or two lines.
@@ -1120,7 +1120,7 @@ gtk_about_dialog_get_comments (GtkAboutDialog *about)
 /**
  * gtk_about_dialog_set_comments:
  * @about: a #GtkAboutDialog
- * @comments: a comments string
+ * @comments: (allow-none): a comments string
  *
  * Sets the comments string to display in the about dialog.
  * This should be a short string of one or two lines.
@@ -1181,7 +1181,7 @@ gtk_about_dialog_get_license (GtkAboutDialog *about)
 /**
  * gtk_about_dialog_set_license:
  * @about: a #GtkAboutDialog
- * @license: the license information or %NULL
+ * @license: (allow-none): the license information or %NULL
  *
  * Sets the license information to be displayed in the secondary
  * license dialog. If @license is %NULL, the license button is
@@ -1295,7 +1295,7 @@ gtk_about_dialog_get_website (GtkAboutDialog *about)
 /**
  * gtk_about_dialog_set_website:
  * @about: a #GtkAboutDialog
- * @website: a URL string starting with "http://"
+ * @website: (allow-none): a URL string starting with "http://"
  *
  * Sets the URL to use for the website link.
  *
@@ -1587,7 +1587,7 @@ gtk_about_dialog_get_translator_credits (GtkAboutDialog *about)
 /**
  * gtk_about_dialog_set_translator_credits:
  * @about: a #GtkAboutDialog
- * @translator_credits: the translator credits
+ * @translator_credits: (allow-none): the translator credits
  *
  * Sets the translator credits string which is displayed in
  * the translators tab of the secondary credits dialog.
@@ -1674,7 +1674,7 @@ icon_set_new_from_pixbufs (GList *pixbufs)
 /**
  * gtk_about_dialog_set_logo:
  * @about: a #GtkAboutDialog
- * @logo: a #GdkPixbuf, or %NULL
+ * @logo: (allow-none): a #GdkPixbuf, or %NULL
  *
  * Sets the pixbuf to be displayed as logo in the about dialog.
  * If it is %NULL, the default window icon set with
@@ -1751,7 +1751,7 @@ gtk_about_dialog_get_logo_icon_name (GtkAboutDialog *about)
 /**
  * gtk_about_dialog_set_logo_icon_name:
  * @about: a #GtkAboutDialog
- * @icon_name: an icon name, or %NULL
+ * @icon_name: (allow-none): an icon name, or %NULL
  *
  * Sets the pixbuf to be displayed as logo in the about dialog.
  * If it is %NULL, the default window icon set with
diff --git a/gtk/gtkaccelgroup.c b/gtk/gtkaccelgroup.c
index 29e34eb3f3..4d760b5880 100644
--- a/gtk/gtkaccelgroup.c
+++ b/gtk/gtkaccelgroup.c
@@ -351,10 +351,11 @@ _gtk_accel_group_detach (GtkAccelGroup *accel_group,
 
 /**
  * gtk_accel_groups_from_object:
- * @object:        a #GObject, usually a #GtkWindow 
- * @returns: a list of all accel groups which are attached to @object
+ * @object:        a #GObject, usually a #GtkWindow
  *
  * Gets a list of all accel groups which are attached to @object.
+ *
+ * Returns: (element-type GtkAccelGroup) (transfer none): a list of all accel groups which are attached to @object
  */
 GSList*
 gtk_accel_groups_from_object (GObject *object)
diff --git a/gtk/gtkaction.c b/gtk/gtkaction.c
index 6e9dfa2557..48417a2bfc 100644
--- a/gtk/gtkaction.c
+++ b/gtk/gtkaction.c
@@ -978,8 +978,8 @@ gtk_action_disconnect_proxy (GtkAction *action,
  * 
  * Returns the proxy widgets for an action.
  * See also gtk_widget_get_action().
- * 
- * Return value: a #GSList of proxy widgets. The list is owned by GTK+
+ *
+ * Return value: (element-type GtkWidget) (transfer none): a #GSList of proxy widgets. The list is owned by GTK+
  * and must not be modified.
  *
  * Since: 2.4
@@ -1811,8 +1811,8 @@ gtk_action_get_accel_closure (GtkAction *action)
 /**
  * gtk_action_set_accel_group:
  * @action: the action object
- * @accel_group: a #GtkAccelGroup or %NULL
- * 
+ * @accel_group: (allow-none): a #GtkAccelGroup or %NULL
+ *
  * Sets the #GtkAccelGroup in which the accelerator for this action
  * will be installed.
  *
diff --git a/gtk/gtkactiongroup.c b/gtk/gtkactiongroup.c
index 2fd87e0969..a8003803c1 100644
--- a/gtk/gtkactiongroup.c
+++ b/gtk/gtkactiongroup.c
@@ -731,7 +731,7 @@ gtk_action_group_set_visible (GtkActionGroup *action_group,
  *
  * Looks up an action in the action group by name.
  *
- * Returns: the action, or %NULL if no action by that name exists
+ * Returns: (transfer-none): the action, or %NULL if no action by that name exists
  *
  * Since: 2.4
  */
@@ -805,11 +805,11 @@ gtk_action_group_add_action (GtkActionGroup *action_group,
 
 /**
  * gtk_action_group_add_action_with_accel:
- * @action_group: the action group 
- * @action: the action to add 
- * @accelerator: the accelerator for the action, in
- *   the format understood by gtk_accelerator_parse(), or "" for no accelerator, or 
- *   %NULL to use the stock accelerator 
+ * @action_group: the action group
+ * @action: the action to add
+ * @accelerator: (allow-none): the accelerator for the action, in
+ *   the format understood by gtk_accelerator_parse(), or "" for no accelerator, or
+ *   %NULL to use the stock accelerator
  *
  * Adds an action object to the action group and sets up the accelerator.
  *
@@ -920,8 +920,8 @@ add_single_action (gpointer key,
  *
  * Lists the actions in the action group.
  *
- * Returns: an allocated list of the action objects in the action group
- * 
+ * Returns: (element-type GtkAction) (transfer container): an allocated list of the action objects in the action group
+ *
  * Since: 2.4
  */
 GList *
diff --git a/gtk/gtkassistant.c b/gtk/gtkassistant.c
index 452d0b4fa3..f43193e68c 100644
--- a/gtk/gtkassistant.c
+++ b/gtk/gtkassistant.c
@@ -1980,8 +1980,8 @@ gtk_assistant_get_page_type (GtkAssistant *assistant,
  * gtk_assistant_set_page_header_image:
  * @assistant: a #GtkAssistant
  * @page: a page of @assistant
- * @pixbuf: the new header image @page
- * 
+ * @pixbuf: (allow-none): the new header image @page
+ *
  * Sets a header image for @page. This image is displayed in the header
  * area of the assistant when @page is the current page.
  *
@@ -2060,8 +2060,8 @@ gtk_assistant_get_page_header_image (GtkAssistant *assistant,
  * gtk_assistant_set_page_side_image:
  * @assistant: a #GtkAssistant
  * @page: a page of @assistant
- * @pixbuf: the new header image @page
- * 
+ * @pixbuf: (allow-none): the new header image @page
+ *
  * Sets a header image for @page. This image is displayed in the side
  * area of the assistant when @page is the current page.
  *
diff --git a/gtk/gtkbin.c b/gtk/gtkbin.c
index e8138137cc..e025994718 100644
--- a/gtk/gtkbin.c
+++ b/gtk/gtkbin.c
@@ -135,8 +135,8 @@ gtk_bin_forall (GtkContainer *container,
  * Gets the child of the #GtkBin, or %NULL if the bin contains
  * no child widget. The returned widget does not have a reference
  * added, so you do not need to unref it.
- * 
- * Return value: pointer to child of the #GtkBin
+ *
+ * Return value: (transfer none): pointer to child of the #GtkBin
  **/
 GtkWidget*
 gtk_bin_get_child (GtkBin *bin)
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index 9dff20e38a..a692b751e4 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -888,7 +888,7 @@ object_add_to_list (gchar    *object_id,
  * this function does not increment the reference counts of the returned
  * objects.
  *
- * Return value: a newly-allocated #GSList containing all the objects
+ * Return value: (element-type GObject) (transfer container): a newly-allocated #GSList containing all the objects
  *   constructed by the #GtkBuilder instance. It should be freed by
  *   g_slist_free()
  *
diff --git a/gtk/gtkcelllayout.c b/gtk/gtkcelllayout.c
index 2783ce8b50..2fa3c2d320 100644
--- a/gtk/gtkcelllayout.c
+++ b/gtk/gtkcelllayout.c
@@ -292,10 +292,10 @@ gtk_cell_layout_reorder (GtkCellLayout   *cell_layout,
  * 
  * Returns the cell renderers which have been added to @cell_layout.
  *
- * Return value: a list of cell renderers. The list, but not the
+ * Return value: (element-type GtkCellRenderer) (transfer container): a list of cell renderers. The list, but not the
  *   renderers has been newly allocated and should be freed with
  *   g_list_free() when no longer needed.
- * 
+ *
  * Since: 2.12
  */
 GList *
diff --git a/gtk/gtkcellview.c b/gtk/gtkcellview.c
index 5f8fe39574..7704495fbc 100644
--- a/gtk/gtkcellview.c
+++ b/gtk/gtkcellview.c
@@ -857,10 +857,10 @@ gtk_cell_view_set_value (GtkCellView     *cell_view,
 /**
  * gtk_cell_view_set_model:
  * @cell_view: a #GtkCellView
- * @model: a #GtkTreeModel
+ * @model: (allow-none): a #GtkTreeModel
  *
  * Sets the model for @cell_view.  If @cell_view already has a model
- * set, it will remove it before setting the new model.  If @model is 
+ * set, it will remove it before setting the new model.  If @model is
  * %NULL, then it will unset the old model.
  *
  * Since: 2.6
@@ -910,8 +910,8 @@ gtk_cell_view_get_model (GtkCellView *cell_view)
 /**
  * gtk_cell_view_set_displayed_row:
  * @cell_view: a #GtkCellView
- * @path: a #GtkTreePath or %NULL to unset.
- * 
+ * @path: (allow-none): a #GtkTreePath or %NULL to unset.
+ *
  * Sets the row of the model that is currently displayed
  * by the #GtkCellView. If the path is unset, then the
  * contents of the cellview "stick" at their last value;
diff --git a/gtk/gtkclipboard.c b/gtk/gtkclipboard.c
index c964b60d77..a8972127aa 100644
--- a/gtk/gtkclipboard.c
+++ b/gtk/gtkclipboard.c
@@ -1526,12 +1526,13 @@ clipboard_uris_received_func (GtkClipboard *clipboard,
  * Requests the contents of the clipboard as URIs. 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 %NULL-terminated array of strings which must
+ *
+ * Return value: (array zero-terminated=1) (element-type utf8) (transfer full): a newly-allocated
+ * 		 %NULL-terminated array of strings which must
  *               be freed with g_strfreev(), 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 
+ *               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 URI form.)
  *
  * Since: 2.14
diff --git a/gtk/gtkclist.c b/gtk/gtkclist.c
index 9117f8c781..7d7aec55b4 100644
--- a/gtk/gtkclist.c
+++ b/gtk/gtkclist.c
@@ -2274,6 +2274,10 @@ gtk_clist_get_text (GtkCList  *clist,
   return 1;
 }
 
+/**
+ * gtk_clist_set_pixmap:
+ * @mask: (allow-none):
+ */
 void
 gtk_clist_set_pixmap (GtkCList  *clist,
 		      gint       row,
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index 666cb7fb00..8df31ed239 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -5020,9 +5020,9 @@ gtk_combo_box_set_active_iter (GtkComboBox     *combo_box,
 /**
  * gtk_combo_box_set_model:
  * @combo_box: A #GtkComboBox
- * @model: A #GtkTreeModel
+ * @model: (allow-none): A #GtkTreeModel
  *
- * Sets the model used by @combo_box to be @model. Will unset a previously set 
+ * Sets the model used by @combo_box to be @model. Will unset a previously set
  * model (if applicable). If model is %NULL, then it will unset the model.
  *
  * Note that this function does not clear the cell renderers, you have to 
@@ -5104,7 +5104,7 @@ out:
  *
  * Returns the #GtkTreeModel which is acting as data source for @combo_box.
  *
- * Return value: A #GtkTreeModel which was passed during construction.
+ * Return value: (transfer none): A #GtkTreeModel which was passed during construction.
  *
  * Since: 2.4
  */
@@ -5129,7 +5129,7 @@ gtk_combo_box_get_model (GtkComboBox *combo_box)
  * gtk_combo_box_insert_text(), gtk_combo_box_prepend_text() and
  * gtk_combo_box_remove_text().
  *
- * Return value: A new text combo box.
+ * Return value: (transfer none): A new text combo box.
  *
  * Since: 2.4
  */
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 8b721d0282..d997cf78ba 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -1586,7 +1586,7 @@ gtk_container_foreach_full (GtkContainer       *container,
 /**
  * gtk_container_set_focus_child:
  * @container: a #GtkContainer
- * @child: a #GtkWidget, or %NULL
+ * @child: (allow-none): a #GtkWidget, or %NULL
  *
  * Sets, or unsets if @child is %NULL, the focused child of @container.
  *
@@ -1629,9 +1629,9 @@ gtk_container_get_focus_child (GtkContainer *container)
  * @container: a #GtkContainer
  * 
  * Returns the container's non-internal children. See
- * gtk_container_forall() for details on what constitutes an "internal" child. 
+ * gtk_container_forall() for details on what constitutes an "internal" child.
  *
- * Return value: a newly-allocated list of the container's non-internal children.
+ * Return value: (element-type GtkWidget) (transfer container): a newly-allocated list of the container's non-internal children.
  **/
 GList*
 gtk_container_get_children (GtkContainer *container)
@@ -2403,7 +2403,8 @@ gtk_container_set_focus_chain (GtkContainer *container,
 /**
  * gtk_container_get_focus_chain:
  * @container:         a #GtkContainer
- * @focusable_widgets: location to store the focus chain of the
+ * @focusable_widgets: (element-type GtkWidget) (out) (transfer container): location
+ *                     to store the focus chain of the
  *                     container, or %NULL. You should free this list
  *                     using g_list_free() when you are done with it, however
  *                     no additional reference count is added to the
@@ -2513,7 +2514,7 @@ gtk_container_set_focus_vadjustment (GtkContainer  *container,
  * Retrieves the vertical focus adjustment for the container. See
  * gtk_container_set_focus_vadjustment().
  *
- * Return value: the vertical focus adjustment, or %NULL if
+ * Return value: (transfer none): the vertical focus adjustment, or %NULL if
  *   none has been set.
  **/
 GtkAdjustment *
@@ -2568,7 +2569,7 @@ gtk_container_set_focus_hadjustment (GtkContainer  *container,
  * Retrieves the horizontal focus adjustment for the container. See
  * gtk_container_set_focus_hadjustment ().
  *
- * Return value: the horizontal focus adjustment, or %NULL if
+ * Return value: (transfer none): the horizontal focus adjustment, or %NULL if
  *   none has been set.
  **/
 GtkAdjustment *
diff --git a/gtk/gtkctree.c b/gtk/gtkctree.c
index a396db543a..48511e3ce6 100644
--- a/gtk/gtkctree.c
+++ b/gtk/gtkctree.c
@@ -3626,9 +3626,17 @@ real_insert_row (GtkCList *clist,
   return row;
 }
 
-GtkCTreeNode * 
+
+/**
+ * gtk_ctree_insert_node:
+ * @pixmap_closed: (allow-none):
+ * @mask_closed: (allow-none):
+ * @pixmap_opened: (allow-none):
+ * @mask_opened: (allow-none):
+ */
+GtkCTreeNode *
 gtk_ctree_insert_node (GtkCTree     *ctree,
-		       GtkCTreeNode *parent, 
+		       GtkCTreeNode *parent,
 		       GtkCTreeNode *sibling,
 		       gchar        *text[],
 		       guint8        spacing,
@@ -4286,10 +4294,15 @@ gtk_ctree_is_hot_spot (GtkCTree *ctree,
  ***********************************************************/
 
 
+/**
+ * gtk_ctree_move:
+ * @new_parent: (allow-none):
+ * @new_sibling: (allow-none):
+ */
 void
 gtk_ctree_move (GtkCTree     *ctree,
 		GtkCTreeNode *node,
-		GtkCTreeNode *new_parent, 
+		GtkCTreeNode *new_parent,
 		GtkCTreeNode *new_sibling)
 {
   g_return_if_fail (GTK_IS_CTREE (ctree));
@@ -4599,7 +4612,12 @@ gtk_ctree_node_set_text (GtkCTree     *ctree,
   tree_draw_node (ctree, node);
 }
 
-void 
+
+/**
+ * gtk_ctree_node_set_pixmap:
+ * @mask: (allow-none):
+ */
+void
 gtk_ctree_node_set_pixmap (GtkCTree     *ctree,
 			   GtkCTreeNode *node,
 			   gint          column,
@@ -4628,7 +4646,12 @@ gtk_ctree_node_set_pixmap (GtkCTree     *ctree,
   tree_draw_node (ctree, node);
 }
 
-void 
+
+/**
+ * gtk_ctree_node_set_pixtext:
+ * @mask: (allow-none):
+ */
+void
 gtk_ctree_node_set_pixtext (GtkCTree     *ctree,
 			    GtkCTreeNode *node,
 			    gint          column,
@@ -4662,7 +4685,15 @@ gtk_ctree_node_set_pixtext (GtkCTree     *ctree,
   tree_draw_node (ctree, node);
 }
 
-void 
+
+/**
+ * gtk_ctree_set_node_info:
+ * @pixmap_closed: (allow-none):
+ * @mask_closed: (allow-none):
+ * @pixmap_opened: (allow-none):
+ * @mask_opened: (allow-none):
+ */
+void
 gtk_ctree_set_node_info (GtkCTree     *ctree,
 			 GtkCTreeNode *node,
 			 const gchar  *text,
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index eb25f5224b..8d9dfe3fd7 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -529,12 +529,12 @@ gtk_dialog_new_empty (const gchar     *title,
 
 /**
  * gtk_dialog_new_with_buttons:
- * @title: Title of the dialog, or %NULL
- * @parent: Transient parent of the dialog, or %NULL
+ * @title: (allow-none): Title of the dialog, or %NULL
+ * @parent: (allow-none): Transient parent of the dialog, or %NULL
  * @flags: from #GtkDialogFlags
- * @first_button_text: stock ID or text to go in first button, or %NULL
+ * @first_button_text: (allow-none): stock ID or text to go in first button, or %NULL
  * @Varargs: response ID for first button, then additional buttons, ending with %NULL
- * 
+ *
  * Creates a new #GtkDialog with title @title (or %NULL for the default
  * title; see gtk_window_set_title()) and transient parent @parent (or
  * %NULL for none; see gtk_window_set_transient_for()). The @flags
@@ -1191,10 +1191,10 @@ gtk_dialog_get_response_for_widget (GtkDialog *dialog,
 
 /**
  * gtk_alternative_dialog_button_order:
- * @screen: a #GdkScreen, or %NULL to use the default screen
+ * @screen: (allow-none): a #GdkScreen, or %NULL to use the default screen
  *
  * Returns %TRUE if dialogs are expected to use an alternative
- * button order on the screen @screen. See 
+ * button order on the screen @screen. See
  * gtk_dialog_set_alternative_button_order() for more details
  * about alternative button order. 
  *
@@ -1519,7 +1519,7 @@ gtk_dialog_buildable_custom_finished (GtkBuildable *buildable,
  *
  * Returns the action area of @dialog.
  *
- * Returns: the action area.
+ * Returns: (transfer none): the action area.
  *
  * Since: 2.14
  **/
@@ -1537,7 +1537,7 @@ gtk_dialog_get_action_area (GtkDialog *dialog)
  *
  * Returns the content area of @dialog.
  *
- * Returns: the content area #GtkVBox.
+ * Returns: (transfer none): the content area #GtkVBox.
  *
  * Since: 2.14
  **/
diff --git a/gtk/gtkdnd.c b/gtk/gtkdnd.c
index c3a95d8432..3b300e16f1 100644
--- a/gtk/gtkdnd.c
+++ b/gtk/gtkdnd.c
@@ -2831,10 +2831,10 @@ gtk_drag_source_unset_icon (GtkDragSourceSite *site)
  * @widget: a #GtkWidget
  * @colormap: the colormap of the icon
  * @pixmap: the image data for the icon
- * @mask: the transparency mask for an image.
- * 
+ * @mask: (allow-none): the transparency mask for an image.
+ *
  * Sets the icon that will be used for drags from a particular widget
- * from a pixmap/mask. GTK+ retains references for the arguments, and 
+ * from a pixmap/mask. GTK+ retains references for the arguments, and
  * will release them when they are no longer needed.
  * Use gtk_drag_source_set_icon_pixbuf() instead.
  **/
diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c
index 8887b8ef62..4fc7b744a0 100644
--- a/gtk/gtkeditable.c
+++ b/gtk/gtkeditable.c
@@ -149,10 +149,10 @@ gtk_editable_base_init (gpointer g_class)
  * @editable: a #GtkEditable
  * @new_text: the text to append
  * @new_text_length: the length of the text in bytes, or -1
- * @position: location of the position text will be inserted at
+ * @position: (in-out): location of the position text will be inserted at
  *
- * Inserts @new_text_length bytes of @new_text into the contents of the 
- * widget, at position @position. 
+ * Inserts @new_text_length bytes of @new_text into the contents of the
+ * widget, at position @position.
  *
  * Note that the position is in characters, not in bytes. 
  * The function updates @position to point after the newly inserted text.
@@ -266,12 +266,12 @@ gtk_editable_get_position (GtkEditable *editable)
 /**
  * gtk_editable_get_selection_bounds:
  * @editable: a #GtkEditable
- * @start_pos: location to store the starting position, or %NULL 
- * @end_pos: location to store the end position, or %NULL 
+ * @start_pos: (out) (allow-none): location to store the starting position, or %NULL
+ * @end_pos: (out) (allow-none): location to store the end position, or %NULL
  *
  * Retrieves the selection bound of the editable. start_pos will be filled
- * with the start of the selection and @end_pos with end. If no text was 
- * selected both will be identical and %FALSE will be returned. 
+ * with the start of the selection and @end_pos with end. If no text was
+ * selected both will be identical and %FALSE will be returned.
  *
  * Note that positions are specified in characters, not bytes.
  *
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index 9c885ca54d..962fd41b98 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -7238,7 +7238,7 @@ gtk_entry_get_has_frame (GtkEntry *entry)
 /**
  * gtk_entry_set_inner_border:
  * @entry: a #GtkEntry
- * @border: a #GtkBorder, or %NULL
+ * @border: (allow-none): a #GtkBorder, or %NULL
  *
  * Sets %entry's inner-border property to %border, or clears it if %NULL
  * is passed. The inner-border is the area around the entry's text, but
@@ -7276,7 +7276,7 @@ gtk_entry_set_inner_border (GtkEntry        *entry,
  * This function returns the entry's #GtkEntry:inner-border property. See
  * gtk_entry_set_inner_border() for more information.
  *
- * Return value: the entry's #GtkBorder, or %NULL if none was set.
+ * Return value: (transfer none): the entry's #GtkBorder, or %NULL if none was set.
  *
  * Since: 2.10
  **/
@@ -7302,8 +7302,8 @@ gtk_entry_get_inner_border (GtkEntry *entry)
  * gtk_entry_layout_index_to_text_index() and
  * gtk_entry_text_index_to_layout_index() are needed to convert byte
  * indices in the layout to byte indices in the entry contents.
- * 
- * Return value: the #PangoLayout for this entry
+ *
+ * Return value: (transfer none): the #PangoLayout for this entry
  **/
 PangoLayout*
 gtk_entry_get_layout (GtkEntry *entry)
@@ -9626,7 +9626,7 @@ connect_completion_signals (GtkEntry           *entry,
 /**
  * gtk_entry_set_completion:
  * @entry: A #GtkEntry
- * @completion: The #GtkEntryCompletion or %NULL
+ * @completion: (allow-none): The #GtkEntryCompletion or %NULL
  *
  * Sets @completion to be the auxiliary completion object to use with @entry.
  * All further configuration of the completion mechanism is done on
@@ -9743,9 +9743,9 @@ gtk_entry_set_cursor_hadjustment (GtkEntry      *entry,
  * Retrieves the horizontal cursor adjustment for the entry. 
  * See gtk_entry_set_cursor_hadjustment().
  *
- * Return value: the horizontal cursor adjustment, or %NULL 
+ * Return value: (transfer none): the horizontal cursor adjustment, or %NULL
  *   if none has been set.
- * 
+ *
  * Since: 2.12
  */
 GtkAdjustment*
diff --git a/gtk/gtkentrycompletion.c b/gtk/gtkentrycompletion.c
index a3a01be9ff..bb5dda8b2e 100644
--- a/gtk/gtkentrycompletion.c
+++ b/gtk/gtkentrycompletion.c
@@ -1013,7 +1013,7 @@ gtk_entry_completion_get_entry (GtkEntryCompletion *completion)
 /**
  * gtk_entry_completion_set_model:
  * @completion: A #GtkEntryCompletion.
- * @model: The #GtkTreeModel.
+ * @model: (allow-none): The #GtkTreeModel.
  *
  * Sets the model for a #GtkEntryCompletion. If @completion already has
  * a model set, it will remove it before setting the new model.
diff --git a/gtk/gtkexpander.c b/gtk/gtkexpander.c
index 6866f982c9..2341123017 100644
--- a/gtk/gtkexpander.c
+++ b/gtk/gtkexpander.c
@@ -1288,9 +1288,9 @@ gtk_expander_new (const gchar *label)
 
 /**
  * gtk_expander_new_with_mnemonic:
- * @label: the text of the label with an underscore in front of the
+ * @label: (allow-none): the text of the label with an underscore in front of the
  *         mnemonic character
- * 
+ *
  * Creates a new expander using @label as the text of the label.
  * If characters in @label are preceded by an underscore, they are underlined.
  * If you need a literal underscore character in a label, use '__' (two 
@@ -1495,7 +1495,7 @@ gtk_expander_get_spacing (GtkExpander *expander)
 /**
  * gtk_expander_set_label:
  * @expander: a #GtkExpander
- * @label: a string
+ * @label: (allow-none): a string
  *
  * Sets the text of the label of the expander to @label.
  *
@@ -1674,7 +1674,7 @@ gtk_expander_get_use_markup (GtkExpander *expander)
 /**
  * gtk_expander_set_label_widget:
  * @expander: a #GtkExpander
- * @label_widget: the new label widget
+ * @label_widget: (allow-none): the new label widget
  *
  * Set the label widget for the expander. This is the widget
  * that will appear embedded alongside the expander arrow.
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index 6c7de57225..760c24ce78 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -660,8 +660,8 @@ files_to_strings (GSList  *files,
  * @chooser. The returned names are full absolute paths. If files in the current
  * folder cannot be represented as local filenames they will be ignored. (See
  * gtk_file_chooser_get_uris())
- * 
- * Return value: a #GSList containing the filenames of all selected
+ *
+ * Return value: (element-type utf8) (transfer full): a #GSList containing the filenames of all selected
  *   files and subfolders in the current folder. Free the returned list
  *   with g_slist_free(), and the filenames with g_free().
  *
@@ -964,8 +964,8 @@ gtk_file_chooser_unselect_all (GtkFileChooser *chooser)
  * 
  * Lists all the selected files and subfolders in the current folder of
  * @chooser. The returned names are full absolute URIs.
- * 
- * Return value: a #GSList containing the URIs of all selected
+ *
+ * Return value: (element-type utf8) (transfer full): a #GSList containing the URIs of all selected
  *   files and subfolders in the current folder. Free the returned list
  *   with g_slist_free(), and the filenames with g_free().
  *
@@ -1155,8 +1155,8 @@ gtk_file_chooser_unselect_file (GtkFileChooser *chooser,
  * 
  * Lists all the selected files and subfolders in the current folder of @chooser
  * as #GFile. An internal function, see gtk_file_chooser_get_uris().
- * 
- * Return value: a #GSList containing a #GFile for each selected
+ *
+ * Return value: (element-type utf8) (transfer full): a #GSList containing a #GFile for each selected
  *   file and subfolder in the current folder.  Free the returned list
  *   with g_slist_free(), and the files with g_object_unref().
  *
@@ -1665,8 +1665,8 @@ gtk_file_chooser_remove_filter (GtkFileChooser *chooser,
  * 
  * Lists the current set of user-selectable filters; see
  * gtk_file_chooser_add_filter(), gtk_file_chooser_remove_filter().
- * 
- * Return value: a #GSList containing the current set of
+ *
+ * Return value: (element-type utf8) (transfer container): a #GSList containing the current set of
  *  user selectable filters. The contents of the list are
  *  owned by GTK+, but you must free the list itself with
  *  g_slist_free() when you are done with it.
@@ -1806,8 +1806,8 @@ gtk_file_chooser_remove_shortcut_folder (GtkFileChooser    *chooser,
  * 
  * Queries the list of shortcut folders in the file chooser, as set by
  * gtk_file_chooser_add_shortcut_folder().
- * 
- * Return value: A list of folder filenames, or %NULL if there are no shortcut
+ *
+ * Return value: (element-type utf8) (transfer full): A list of folder filenames, or %NULL if there are no shortcut
  * folders.  Free the returned list with g_slist_free(), and the filenames with
  * g_free().
  *
@@ -1903,8 +1903,8 @@ gtk_file_chooser_remove_shortcut_folder_uri (GtkFileChooser    *chooser,
  * 
  * Queries the list of shortcut folders in the file chooser, as set by
  * gtk_file_chooser_add_shortcut_folder_uri().
- * 
- * Return value: A list of folder URIs, or %NULL if there are no shortcut
+ *
+ * Return value: (element-type utf8) (transfer full): A list of folder URIs, or %NULL if there are no shortcut
  * folders.  Free the returned list with g_slist_free(), and the URIs with
  * g_free().
  *
diff --git a/gtk/gtkframe.c b/gtk/gtkframe.c
index c76745572b..eba0fd9c4d 100644
--- a/gtk/gtkframe.c
+++ b/gtk/gtkframe.c
@@ -306,8 +306,8 @@ gtk_frame_forall (GtkContainer *container,
 /**
  * gtk_frame_set_label:
  * @frame: a #GtkFrame
- * @label: the text to use as the label of the frame
- * 
+ * @label: (allow-none): the text to use as the label of the frame
+ *
  * Sets the text of the label. If @label is %NULL,
  * the current label is removed.
  **/
diff --git a/gtk/gtkiconfactory.c b/gtk/gtkiconfactory.c
index 145d935e8e..906a757656 100644
--- a/gtk/gtkiconfactory.c
+++ b/gtk/gtkiconfactory.c
@@ -1620,7 +1620,7 @@ render_fallback_image (GtkStyle          *style,
 /**
  * gtk_icon_set_render_icon:
  * @icon_set: a #GtkIconSet
- * @style: a #GtkStyle associated with @widget, or %NULL
+ * @style: (allow-none): a #GtkStyle associated with @widget, or %NULL
  * @direction: text direction
  * @state: widget state
  * @size: icon size. A size of (GtkIconSize)-1
@@ -1762,7 +1762,7 @@ gtk_icon_set_add_source (GtkIconSet          *icon_set,
 /**
  * gtk_icon_set_get_sizes:
  * @icon_set: a #GtkIconSet
- * @sizes: return location for array of sizes
+ * @sizes: (array length=n_sizes) (out): return location for array of sizes
  * @n_sizes: location to store number of elements in returned array
  *
  * Obtains a list of icon sizes this icon set can render. The returned
@@ -2033,7 +2033,7 @@ gtk_icon_source_set_filename (GtkIconSource *source,
 /**
  * gtk_icon_source_set_icon_name
  * @source: a #GtkIconSource
- * @icon_name: name of icon to use
+ * @icon_name: (allow-none): name of icon to use
  *
  * Sets the name of an icon to look up in the current icon theme
  * to use as a base image when creating icon variants for #GtkIconSet.
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index c4196cde1b..bb678d0b75 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -275,8 +275,8 @@ gtk_icon_theme_new (void)
  * 
  * Gets the icon theme for the default screen. See
  * gtk_icon_theme_get_for_screen().
- * 
- * Return value: A unique #GtkIconTheme associated with
+ *
+ * Return value: (transfer none): A unique #GtkIconTheme associated with
  *  the default screen. This icon theme is associated with
  *  the screen and can be used as long as the screen
  *  is open. Do not ref or unref it.
@@ -301,8 +301,8 @@ gtk_icon_theme_get_default (void)
  * is usually a better choice than calling than gtk_icon_theme_new()
  * and setting the screen yourself; by using this function
  * a single icon theme object will be shared between users.
- * 
- * Return value: A unique #GtkIconTheme associated with
+ *
+ * Return value: (transfer none): A unique #GtkIconTheme associated with
  *  the given screen. This icon theme is associated with
  *  the screen and can be used as long as the screen
  *  is open. Do not ref or unref it.
@@ -1738,8 +1738,8 @@ add_key_to_list (gpointer  key,
  * The set of values for the context string is system dependent,
  * but will typically include such values as "Applications" and
  * "MimeTypes".
- * 
- * Return value: a #GList list holding the names of all the
+ *
+ * Return value: (element-type utf8) (transfer none): a #GList list holding the names of all the
  *  icons in the theme. You must first free each element
  *  in the list with g_free(), then free the list itself
  *  with g_list_free().
@@ -1801,7 +1801,7 @@ gtk_icon_theme_list_icons (GtkIconTheme *icon_theme,
  * Gets the list of contexts available within the current
  * hierarchy of icon themes
  *
- * Return value: a #GList list holding the names of all the
+ * Return value: (element-type utf8) (transfer full): a #GList list holding the names of all the
  *  contexts in the theme. You must first free each element
  *  in the list with g_free(), then free the list itself
  *  with g_list_free().
@@ -2749,8 +2749,8 @@ gtk_icon_info_get_filename (GtkIconInfo *icon_info)
  * GTK+ to use built in icon images, you must pass the
  * %GTK_ICON_LOOKUP_USE_BUILTIN to
  * gtk_icon_theme_lookup_icon().
- * 
- * Return value: the built-in image pixbuf, or %NULL. No
+ *
+ * Return value: (transfer none): the built-in image pixbuf, or %NULL. No
  *  extra reference is added to the returned pixbuf, so if
  *  you want to keep it around, you must use g_object_ref().
  *  The returned image must not be modified.
diff --git a/gtk/gtkiconview.c b/gtk/gtkiconview.c
index 14ee4891c4..14a574ce03 100644
--- a/gtk/gtkiconview.c
+++ b/gtk/gtkiconview.c
@@ -1992,11 +1992,11 @@ gtk_icon_view_stop_editing (GtkIconView *icon_view,
  * gtk_icon_view_set_cursor:
  * @icon_view: A #GtkIconView
  * @path: A #GtkTreePath
- * @cell: One of the cell renderers of @icon_view, or %NULL
+ * @cell: (allow-none): One of the cell renderers of @icon_view, or %NULL
  * @start_editing: %TRUE if the specified cell should start being edited.
  *
  * Sets the current keyboard focus to be at @path, and selects it.  This is
- * useful when you want to focus the user's attention on a particular item.  
+ * useful when you want to focus the user's attention on a particular item.
  * If @cell is not %NULL, then focus is given to the cell specified by 
  * it. Additionally, if @start_editing is %TRUE, then editing should be 
  * started in the specified cell.  
@@ -5266,10 +5266,10 @@ gtk_icon_view_get_selection_mode (GtkIconView *icon_view)
 /**
  * gtk_icon_view_set_model:
  * @icon_view: A #GtkIconView.
- * @model: The model.
+ * @model: (allow-none): The model.
  *
- * Sets the model for a #GtkIconView.  
- * If the @icon_view already has a model set, it will remove 
+ * Sets the model for a #GtkIconView.
+ * If the @icon_view already has a model set, it will remove
  * it before setting the new model.  If @model is %NULL, then
  * it will unset the old model.
  *
@@ -5798,7 +5798,7 @@ gtk_icon_view_unselect_path (GtkIconView *icon_view,
  * g_list_free (list);
  * ]|
  *
- * Return value: A #GList containing a #GtkTreePath for each selected row.
+ * Return value: (element-type GtkTreePath) (transfer full): A #GList containing a #GtkTreePath for each selected row.
  *
  * Since: 2.6
  **/
@@ -7199,9 +7199,9 @@ gtk_icon_view_unset_model_drag_dest (GtkIconView *icon_view)
 /**
  * gtk_icon_view_set_drag_dest_item:
  * @icon_view: a #GtkIconView
- * @path: The path of the item to highlight, or %NULL.
+ * @path: (allow-none): The path of the item to highlight, or %NULL.
  * @pos: Specifies where to drop, relative to the item
- * 
+ *
  * Sets the item that is highlighted for feedback.
  *
  * Since: 2.8
diff --git a/gtk/gtkimage.c b/gtk/gtkimage.c
index 6c53d30721..5f3e7145ad 100644
--- a/gtk/gtkimage.c
+++ b/gtk/gtkimage.c
@@ -492,9 +492,9 @@ gtk_image_get_property (GObject     *object,
 
 /**
  * gtk_image_new_from_pixmap:
- * @pixmap: a #GdkPixmap, or %NULL
- * @mask: a #GdkBitmap, or %NULL
- * 
+ * @pixmap: (allow-none): a #GdkPixmap, or %NULL
+ * @mask: (allow-none): a #GdkBitmap, or %NULL
+ *
  * Creates a #GtkImage widget displaying @pixmap with a @mask.
  * A #GdkPixmap is a server-side image buffer in the pixel format of the
  * current display. The #GtkImage does not assume a reference to the
@@ -518,9 +518,9 @@ gtk_image_new_from_pixmap (GdkPixmap *pixmap,
 
 /**
  * gtk_image_new_from_image:
- * @image: a #GdkImage, or %NULL
- * @mask: a #GdkBitmap, or %NULL 
- * 
+ * @image: (allow-none): a #GdkImage, or %NULL
+ * @mask: (allow-none): a #GdkBitmap, or %NULL
+ *
  * Creates a #GtkImage widget displaying a @image with a @mask.
  * A #GdkImage is a client-side image buffer in the pixel format of the
  * current display. The #GtkImage does not assume a reference to the
@@ -579,8 +579,8 @@ gtk_image_new_from_file   (const gchar *filename)
 
 /**
  * gtk_image_new_from_pixbuf:
- * @pixbuf: a #GdkPixbuf, or %NULL
- * 
+ * @pixbuf: (allow-none): a #GdkPixbuf, or %NULL
+ *
  * Creates a new #GtkImage displaying @pixbuf.
  * The #GtkImage does not assume a reference to the
  * pixbuf; you still need to unref it if you own references.
@@ -750,8 +750,8 @@ gtk_image_new_from_gicon (GIcon *icon,
 /**
  * gtk_image_set_from_pixmap:
  * @image: a #GtkImage
- * @pixmap: a #GdkPixmap or %NULL
- * @mask: a #GdkBitmap or %NULL
+ * @pixmap: (allow-none): a #GdkPixmap or %NULL
+ * @mask: (allow-none): a #GdkBitmap or %NULL
  *
  * See gtk_image_new_from_pixmap() for details.
  **/
@@ -801,8 +801,8 @@ gtk_image_set_from_pixmap (GtkImage  *image,
 /**
  * gtk_image_set_from_image:
  * @image: a #GtkImage
- * @gdk_image: a #GdkImage or %NULL
- * @mask: a #GdkBitmap or %NULL
+ * @gdk_image: (allow-none): a #GdkImage or %NULL
+ * @mask:  (allow-none): a #GdkBitmap or %NULL
  *
  * See gtk_image_new_from_image() for details.
  **/
@@ -852,7 +852,7 @@ gtk_image_set_from_image  (GtkImage  *image,
 /**
  * gtk_image_set_from_file:
  * @image: a #GtkImage
- * @filename: a filename or %NULL
+ * @filename: (allow-none): a filename or %NULL
  *
  * See gtk_image_new_from_file() for details.
  **/
@@ -908,9 +908,9 @@ gtk_image_set_from_file   (GtkImage    *image,
 /**
  * gtk_image_set_from_pixbuf:
  * @image: a #GtkImage
- * @pixbuf: a #GdkPixbuf or %NULL
+ * @pixbuf: (allow-none): a #GdkPixbuf or %NULL
  *
- * See gtk_image_new_from_pixbuf() for details. 
+ * See gtk_image_new_from_pixbuf() for details.
  **/
 void
 gtk_image_set_from_pixbuf (GtkImage  *image,
diff --git a/gtk/gtkimagemenuitem.c b/gtk/gtkimagemenuitem.c
index 9116a4840e..4441145051 100644
--- a/gtk/gtkimagemenuitem.c
+++ b/gtk/gtkimagemenuitem.c
@@ -916,8 +916,8 @@ gtk_image_menu_item_set_accel_group (GtkImageMenuItem *image_menu_item,
 /** 
  * gtk_image_menu_item_set_image:
  * @image_menu_item: a #GtkImageMenuItem.
- * @image: a widget to set as the image for the menu item.
- * 
+ * @image: (allow-none): a widget to set as the image for the menu item.
+ *
  * Sets the image of @image_menu_item to the given widget.
  * Note that it depends on the show-menu-images setting whether
  * the image will be displayed or not.
diff --git a/gtk/gtkitemfactory.c b/gtk/gtkitemfactory.c
index 70c01a6223..2eab969869 100644
--- a/gtk/gtkitemfactory.c
+++ b/gtk/gtkitemfactory.c
@@ -147,12 +147,12 @@ gtk_item_factory_init (GtkItemFactory	    *ifactory)
  * gtk_item_factory_new:
  * @container_type: the kind of menu to create; can be
  *    #GTK_TYPE_MENU_BAR, #GTK_TYPE_MENU or #GTK_TYPE_OPTION_MENU
- * @path: the factory path of the new item factory, a string of the form 
+ * @path: the factory path of the new item factory, a string of the form
  *    <literal>"&lt;name&gt;"</literal>
- * @accel_group: a #GtkAccelGroup to which the accelerators for the
+ * @accel_group: (allow-none): a #GtkAccelGroup to which the accelerators for the
  *    menu items will be added, or %NULL to create a new one
  * @returns: a new #GtkItemFactory
- * 
+ *
  * Creates a new #GtkItemFactory.
  *
  * Beware that the returned object does not have a floating reference.
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index c3df84a2dc..73fa93a35b 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -1610,7 +1610,7 @@ label_mnemonic_widget_weak_notify (gpointer      data,
 /**
  * gtk_label_set_mnemonic_widget:
  * @label: a #GtkLabel
- * @widget: the target #GtkWidget 
+ * @widget: (allow-none): the target #GtkWidget
  *
  * If the label has been set so that it has an mnemonic key (using
  * i.e. gtk_label_set_markup_with_mnemonic(),
@@ -4850,8 +4850,8 @@ gtk_label_get_selection_bounds (GtkLabel  *label,
  * pixel positions, in combination with gtk_label_get_layout_offsets().
  * The returned layout is owned by the label so need not be
  * freed by the caller.
- * 
- * Return value: the #PangoLayout for this label
+ *
+ * Return value: (transfer none): the #PangoLayout for this label
  **/
 PangoLayout*
 gtk_label_get_layout (GtkLabel *label)
diff --git a/gtk/gtklayout.c b/gtk/gtklayout.c
index 153a2dfca4..0a11f48112 100644
--- a/gtk/gtklayout.c
+++ b/gtk/gtklayout.c
@@ -285,7 +285,7 @@ gtk_layout_finalize (GObject *object)
 /**
  * gtk_layout_set_hadjustment:
  * @layout: a #GtkLayout
- * @adjustment: new scroll adjustment
+ * @adjustment: (allow-none): new scroll adjustment
  *
  * Sets the horizontal scroll adjustment for the layout.
  *
@@ -305,7 +305,7 @@ gtk_layout_set_hadjustment (GtkLayout     *layout,
 /**
  * gtk_layout_set_vadjustment:
  * @layout: a #GtkLayout
- * @adjustment: new scroll adjustment
+ * @adjustment: (allow-none): new scroll adjustment
  *
  * Sets the vertical scroll adjustment for the layout.
  *
diff --git a/gtk/gtklinkbutton.c b/gtk/gtklinkbutton.c
index 60ce24a8e2..eaa6678dc2 100644
--- a/gtk/gtklinkbutton.c
+++ b/gtk/gtklinkbutton.c
@@ -600,11 +600,11 @@ gtk_link_button_new (const gchar *uri)
 /**
  * gtk_link_button_new_with_label:
  * @uri: a valid URI
- * @label: the text of the button
+ * @label: (allow-none): the text of the button
  *
  * Creates a new #GtkLinkButton containing a label.
  *
- * Return value: a new link button widget.
+ * Return value: (transfer none): a new link button widget.
  *
  * Since: 2.10
  */
diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c
index 8ab1f18fbf..71ceb1cad0 100644
--- a/gtk/gtkliststore.c
+++ b/gtk/gtkliststore.c
@@ -267,11 +267,11 @@ gtk_list_store_new (gint n_columns,
 /**
  * gtk_list_store_newv:
  * @n_columns: number of columns in the list store
- * @types: an array of #GType types for the columns, from first to last
+ * @types: (array length=n_columns): an array of #GType types for the columns, from first to last
  *
  * Non-vararg creation function.  Used primarily by language bindings.
  *
- * Return value: a new #GtkListStore
+ * Return value: (transfer none): a new #GtkListStore
  **/
 GtkListStore *
 gtk_list_store_newv (gint   n_columns,
@@ -304,8 +304,8 @@ gtk_list_store_newv (gint   n_columns,
  * gtk_list_store_set_column_types:
  * @list_store: A #GtkListStore
  * @n_columns: Number of columns for the list store
- * @types: An array length n of #GTypes
- * 
+ * @types: (array length=n_columns): An array length n of #GTypes
+ *
  * This function is meant primarily for #GObjects that inherit from #GtkListStore,
  * and should only be used when constructing a new #GtkListStore.  It will not
  * function after a row has been added, or a method on the #GtkTreeModel
@@ -832,10 +832,10 @@ gtk_list_store_set_valist_internal (GtkListStore *list_store,
  * gtk_list_store_set_valuesv:
  * @list_store: A #GtkListStore
  * @iter: A valid #GtkTreeIter for the row being modified
- * @columns: an array of column numbers
- * @values: an array of GValues 
+ * @columns: (array length=n_values): an array of column numbers
+ * @values: (array length=n_values): an array of GValues
  * @n_values: the length of the @columns and @values arrays
- * 
+ *
  * A variant of gtk_list_store_set_valist() which
  * takes the columns and values as two arrays, instead of
  * varargs. This function is mainly intended for 
@@ -1579,7 +1579,7 @@ gtk_list_store_move_to (GtkListStore *store,
  * gtk_list_store_move_before:
  * @store: A #GtkListStore.
  * @iter: A #GtkTreeIter.
- * @position: A #GtkTreeIter, or %NULL.
+ * @position: (allow-none): A #GtkTreeIter, or %NULL.
  *
  * Moves @iter in @store to the position before @position. Note that this
  * function only works with unsorted stores. If @position is %NULL, @iter
@@ -1612,7 +1612,7 @@ gtk_list_store_move_before (GtkListStore *store,
  * gtk_list_store_move_after:
  * @store: A #GtkListStore.
  * @iter: A #GtkTreeIter.
- * @position: A #GtkTreeIter or %NULL.
+ * @position: (allow-none): A #GtkTreeIter or %NULL.
  *
  * Moves @iter in @store to the position after @position. Note that this
  * function only works with unsorted stores. If @position is %NULL, @iter
diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index 5a8a0ef1fc..581403b541 100644
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -882,9 +882,9 @@ gtk_init_with_args (int            *argc,
 
 /**
  * gtk_parse_args:
- * @argc: a pointer to the number of command line arguments.
- * @argv: a pointer to the array of command line arguments.
- * 
+ * @argc: (inout): a pointer to the number of command line arguments.
+ * @argv: (array) (inout): a pointer to the array of command line arguments.
+ *
  * Parses command line arguments, and initializes global
  * attributes of GTK+, but does not actually open a connection
  * to a display. (See gdk_display_open(), gdk_get_display_arg_name())
@@ -935,13 +935,13 @@ gtk_parse_args (int    *argc,
 
 /**
  * gtk_init_check:
- * @argc: Address of the <parameter>argc</parameter> parameter of your 
+ * @argc: (inout): Address of the <parameter>argc</parameter> parameter of your
  *   main() function. Changed if any arguments were handled.
- * @argv: Address of the <parameter>argv</parameter> parameter of main(). 
+ * @argv: (array length=argc) (inout) (allow-none): Address of the <parameter>argv</parameter> parameter of main().
  *   Any parameters understood by gtk_init() are stripped before return.
- * 
- * This function does the same work as gtk_init() with only 
- * a single change: It does not terminate the program if the GUI can't be 
+ *
+ * This function does the same work as gtk_init() with only
+ * a single change: It does not terminate the program if the GUI can't be
  * initialized. Instead it returns %FALSE on failure.
  *
  * This way the application can fall back to some other means of communication 
@@ -966,13 +966,13 @@ gtk_init_check (int	 *argc,
 
 /**
  * gtk_init:
- * @argc: Address of the <parameter>argc</parameter> parameter of your 
+ * @argc: (inout): Address of the <parameter>argc</parameter> parameter of your
  *   main() function. Changed if any arguments were handled.
- * @argv: Address of the <parameter>argv</parameter> parameter of main(). 
+ * @argv: (array length=argc) (inout) (allow-none): Address of the <parameter>argv</parameter> parameter of main().
  *   Any parameters understood by gtk_init() are stripped before return.
- * 
+ *
  * Call this function before using any other GTK+ functions in your GUI
- * applications.  It will initialize everything needed to operate the 
+ * applications.  It will initialize everything needed to operate the
  * toolkit and parses some standard command line options. @argc and 
  * @argv are adjusted accordingly so your own code will 
  * never see those standard arguments. 
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index 0bdf1dea76..e8813c9f0d 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -1747,6 +1747,11 @@ gtk_menu_set_active (GtkMenu *menu,
     }
 }
 
+
+/**
+ * gtk_menu_set_accel_group:
+ * @accel_group: (allow-none):
+ */
 void
 gtk_menu_set_accel_group (GtkMenu	*menu,
 			  GtkAccelGroup *accel_group)
@@ -1793,7 +1798,7 @@ gtk_menu_real_can_activate_accel (GtkWidget *widget,
 /**
  * gtk_menu_set_accel_path
  * @menu:       a valid #GtkMenu
- * @accel_path: a valid accelerator path
+ * @accel_path: (allow-none): a valid accelerator path
  *
  * Sets an accelerator path for this menu from which accelerator paths
  * for its immediate children, its menu items, can be constructed.
@@ -4810,11 +4815,11 @@ gtk_menu_hide_all (GtkWidget *widget)
 /**
  * gtk_menu_set_screen:
  * @menu: a #GtkMenu.
- * @screen: a #GdkScreen, or %NULL if the screen should be
+ * @screen: (allow-none): a #GdkScreen, or %NULL if the screen should be
  *          determined by the widget the menu is attached to.
  *
  * Sets the #GdkScreen on which the menu will be displayed.
- * 
+ *
  * Since: 2.2
  **/
 void
@@ -5282,7 +5287,7 @@ gtk_menu_get_monitor (GtkMenu *menu)
  * Returns a list of the menus which are attached to this widget.
  * This list is owned by GTK+ and must not be modified.
  *
- * Return value: the list of menus attached to his widget.
+ * Return value: (element-type GtkWidget) (transfer none): the list of menus attached to his widget.
  *
  * Since: 2.6
  **/
diff --git a/gtk/gtkmenuitem.c b/gtk/gtkmenuitem.c
index 1ab96b00a2..13db059bd4 100644
--- a/gtk/gtkmenuitem.c
+++ b/gtk/gtkmenuitem.c
@@ -2001,7 +2001,7 @@ _gtk_menu_item_refresh_accel_path (GtkMenuItem   *menu_item,
 /**
  * gtk_menu_item_set_accel_path
  * @menu_item:  a valid #GtkMenuItem
- * @accel_path: accelerator path, corresponding to this menu item's
+ * @accel_path: (allow-none): accelerator path, corresponding to this menu item's
  *              functionality, or %NULL to unset the current path.
  *
  * Set the accelerator path on @menu_item, through which runtime changes of the
diff --git a/gtk/gtkmenutoolbutton.c b/gtk/gtkmenutoolbutton.c
index bc6e5cb6a8..c0022fe0f5 100644
--- a/gtk/gtkmenutoolbutton.c
+++ b/gtk/gtkmenutoolbutton.c
@@ -596,8 +596,8 @@ gtk_menu_tool_button_get_menu (GtkMenuToolButton *button)
  * gtk_menu_tool_button_set_arrow_tooltip:
  * @button: a #GtkMenuToolButton
  * @tooltips: the #GtkTooltips object to be used
- * @tip_text: text to be used as tooltip text for tool_item
- * @tip_private: text to be used as private tooltip text
+ * @tip_text: (allow-none): text to be used as tooltip text for tool_item
+ * @tip_private: (allow-none): text to be used as private tooltip text
  *
  * Sets the #GtkTooltips object to be used for arrow button which
  * pops up the menu. See gtk_tool_item_set_tooltip() for setting
diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index ecae119220..b721aded36 100644
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -475,20 +475,20 @@ gtk_message_dialog_get_property (GObject     *object,
 
 /**
  * gtk_message_dialog_new:
- * @parent: transient parent, or %NULL for none 
+ * @parent: (allow-none): transient parent, or %NULL for none
  * @flags: flags
  * @type: type of message
  * @buttons: set of buttons to use
- * @message_format: printf()-style format string, or %NULL
+ * @message_format: (allow-none): printf()-style format string, or %NULL
  * @Varargs: arguments for @message_format
- * 
+ *
  * Creates a new message dialog, which is a simple dialog with an icon
  * indicating the dialog type (error, warning, etc.) and some text the
  * user may want to see. When the user clicks a button a "response"
  * signal is emitted with response IDs from #GtkResponseType. See
  * #GtkDialog for more details.
- * 
- * Return value: a new #GtkMessageDialog
+ *
+ * Return value: (transfer none): a new #GtkMessageDialog
  **/
 GtkWidget*
 gtk_message_dialog_new (GtkWindow     *parent,
diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c
index b51388cca4..ed48977ec4 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -6384,9 +6384,9 @@ gtk_notebook_set_tab_vborder_internal (GtkNotebook *notebook,
  * gtk_notebook_append_page:
  * @notebook: a #GtkNotebook
  * @child: the #GtkWidget to use as the contents of the page.
- * @tab_label: the #GtkWidget to be used as the label for the page,
+ * @tab_label: (allow-none): the #GtkWidget to be used as the label for the page,
  *             or %NULL to use the default label, 'page N'.
- * 
+ *
  * Appends a page to @notebook.
  *
  * Return value: the index (starting from 0) of the appended
@@ -6408,9 +6408,9 @@ gtk_notebook_append_page (GtkNotebook *notebook,
  * gtk_notebook_append_page_menu:
  * @notebook: a #GtkNotebook
  * @child: the #GtkWidget to use as the contents of the page.
- * @tab_label: the #GtkWidget to be used as the label for the page,
+ * @tab_label: (allow-none): the #GtkWidget to be used as the label for the page,
  *             or %NULL to use the default label, 'page N'.
- * @menu_label: the widget to use as a label for the page-switch
+ * @menu_label: (allow-none): the widget to use as a label for the page-switch
  *              menu, if that is enabled. If %NULL, and @tab_label
  *              is a #GtkLabel or %NULL, then the menu label will be
  *              a newly created label with the same text as @tab_label;
@@ -6441,7 +6441,7 @@ gtk_notebook_append_page_menu (GtkNotebook *notebook,
  * gtk_notebook_prepend_page:
  * @notebook: a #GtkNotebook
  * @child: the #GtkWidget to use as the contents of the page.
- * @tab_label: the #GtkWidget to be used as the label for the page,
+ * @tab_label: (allow-none): the #GtkWidget to be used as the label for the page,
  *             or %NULL to use the default label, 'page N'.
  *
  * Prepends a page to @notebook.
@@ -6465,9 +6465,9 @@ gtk_notebook_prepend_page (GtkNotebook *notebook,
  * gtk_notebook_prepend_page_menu:
  * @notebook: a #GtkNotebook
  * @child: the #GtkWidget to use as the contents of the page.
- * @tab_label: the #GtkWidget to be used as the label for the page,
+ * @tab_label: (allow-none): the #GtkWidget to be used as the label for the page,
  *             or %NULL to use the default label, 'page N'.
- * @menu_label: the widget to use as a label for the page-switch
+ * @menu_label: (allow-none): the widget to use as a label for the page-switch
  *              menu, if that is enabled. If %NULL, and @tab_label
  *              is a #GtkLabel or %NULL, then the menu label will be
  *              a newly created label with the same text as @tab_label;
@@ -6498,11 +6498,11 @@ gtk_notebook_prepend_page_menu (GtkNotebook *notebook,
  * gtk_notebook_insert_page:
  * @notebook: a #GtkNotebook
  * @child: the #GtkWidget to use as the contents of the page.
- * @tab_label: the #GtkWidget to be used as the label for the page,
+ * @tab_label: (allow-none): the #GtkWidget to be used as the label for the page,
  *             or %NULL to use the default label, 'page N'.
  * @position: the index (starting at 0) at which to insert the page,
  *            or -1 to append the page after all other pages.
- * 
+ *
  * Insert a page into @notebook at the given position.
  *
  * Return value: the index (starting from 0) of the inserted
@@ -6555,9 +6555,9 @@ gtk_notebook_mnemonic_activate_switch_page (GtkWidget *child,
  * gtk_notebook_insert_page_menu:
  * @notebook: a #GtkNotebook
  * @child: the #GtkWidget to use as the contents of the page.
- * @tab_label: the #GtkWidget to be used as the label for the page,
+ * @tab_label: (allow-none): the #GtkWidget to be used as the label for the page,
  *             or %NULL to use the default label, 'page N'.
- * @menu_label: the widget to use as a label for the page-switch
+ * @menu_label: (allow-none): the widget to use as a label for the page-switch
  *              menu, if that is enabled. If %NULL, and @tab_label
  *              is a #GtkLabel or %NULL, then the menu label will be
  *              a newly created label with the same text as @tab_label;
@@ -6654,8 +6654,8 @@ gtk_notebook_get_current_page (GtkNotebook *notebook)
  *            to get the last page.
  * 
  * Returns the child widget contained in page number @page_num.
- * 
- * Return value: the child widget, or %NULL if @page_num is
+ *
+ * Return value: (transfer none): the child widget, or %NULL if @page_num is
  * out of bounds.
  **/
 GtkWidget*
@@ -7173,8 +7173,8 @@ gtk_notebook_popup_disable  (GtkNotebook *notebook)
  * Returns the tab label widget for the page @child. %NULL is returned
  * if @child is not in @notebook or if no tab label has specifically
  * been set for @child.
- * 
- * Return value: the tab label
+ *
+ * Return value: (transfer none): the tab label
  **/
 GtkWidget *
 gtk_notebook_get_tab_label (GtkNotebook *notebook,
@@ -7199,9 +7199,9 @@ gtk_notebook_get_tab_label (GtkNotebook *notebook,
  * gtk_notebook_set_tab_label:
  * @notebook: a #GtkNotebook
  * @child: the page
- * @tab_label: the tab label widget to use, or %NULL for default tab
+ * @tab_label: (allow-none): the tab label widget to use, or %NULL for default tab
  *             label.
- * 
+ *
  * Changes the tab label for @child. If %NULL is specified
  * for @tab_label, then the page will have the label 'page N'.
  **/
@@ -7358,9 +7358,9 @@ gtk_notebook_get_menu_label (GtkNotebook *notebook,
  * gtk_notebook_set_menu_label:
  * @notebook: a #GtkNotebook
  * @child: the child widget
- * @menu_label: the menu label, or NULL for default
- * 
- * Changes the menu label for the page containing @child. 
+ * @menu_label: (allow-none): the menu label, or NULL for default
+ *
+ * Changes the menu label for the page containing @child.
  **/
 void
 gtk_notebook_set_menu_label (GtkNotebook *notebook,
diff --git a/gtk/gtkpapersize.c b/gtk/gtkpapersize.c
index a806ae8d95..f24b15f0b2 100644
--- a/gtk/gtkpapersize.c
+++ b/gtk/gtkpapersize.c
@@ -191,11 +191,11 @@ gtk_paper_size_new_from_info (const PaperInfo *info)
 
 /**
  * gtk_paper_size_new:
- * @name: a paper size name, or %NULL
- * 
- * Creates a new #GtkPaperSize object by parsing a 
+ * @name: (allow-none): a paper size name, or %NULL
+ *
+ * Creates a new #GtkPaperSize object by parsing a
  * <ulink url="ftp://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn10-20020226-5101.1.pdf">PWG 5101.1-2002</ulink>
- * paper name. 
+ * paper name.
  *
  * If @name is %NULL, the default paper size is returned,
  * see gtk_paper_size_get_default().
@@ -443,8 +443,8 @@ GList * _gtk_load_custom_papers (void);
  *     as defined in the page setup dialog
  *
  * Creates a list of known paper sizes.
- * 
- * Return value: a newly allocated list of newly 
+ *
+ * Return value:  (element-type GtkPaperSize) (transfer full): a newly allocated list of newly
  *    allocated #GtkPaperSize objects
  *
  * Since: 2.12
diff --git a/gtk/gtkpixmap.c b/gtk/gtkpixmap.c
index 74a05aa5a4..60e4bd0ed8 100644
--- a/gtk/gtkpixmap.c
+++ b/gtk/gtkpixmap.c
@@ -69,6 +69,10 @@ gtk_pixmap_init (GtkPixmap *pixmap)
   pixmap->mask = NULL;
 }
 
+/**
+ * gtk_pixmap_new:
+ * @mask: (allow-none):
+ */
 GtkWidget*
 gtk_pixmap_new (GdkPixmap *val,
 		GdkBitmap *mask)
diff --git a/gtk/gtkprintbackend.c b/gtk/gtkprintbackend.c
index 648a47248c..9e310226b2 100644
--- a/gtk/gtkprintbackend.c
+++ b/gtk/gtkprintbackend.c
@@ -304,6 +304,11 @@ _gtk_print_backend_create (const gchar *backend_name)
   return pb;
 }
 
+/**
+ * gtk_printer_backend_load_modules:
+ *
+ * Return value: (element-type GtkPrintBackend) (transfer container):
+ */
 GList *
 gtk_print_backend_load_modules (void)
 {
@@ -587,6 +592,11 @@ gtk_print_backend_set_list_done (GtkPrintBackend *backend)
 }
 
 
+/**
+ * gtk_print_backend_get_printer_list:
+ *
+ * Return value: (element-type GtkPrinter) (transfer container):
+ */
 GList *
 gtk_print_backend_get_printer_list (GtkPrintBackend *backend)
 {
diff --git a/gtk/gtkprinter.c b/gtk/gtkprinter.c
index 3ad30ccad6..9ef7dc892d 100644
--- a/gtk/gtkprinter.c
+++ b/gtk/gtkprinter.c
@@ -932,8 +932,8 @@ _gtk_printer_create_cairo_surface (GtkPrinter       *printer,
  * Lists all the paper sizes @printer supports.
  * This will return and empty list unless the printer's details are 
  * available, see gtk_printer_has_details() and gtk_printer_request_details().
- * 
- * Return value: a newly allocated list of newly allocated #GtkPageSetup s.
+ *
+ * Return value: (element-type GtkPageSetup) (transfer full): a newly allocated list of newly allocated #GtkPageSetup s.
  *
  * Since: 2.12
  */
diff --git a/gtk/gtkprinteroptionset.c b/gtk/gtkprinteroptionset.c
index eb84a3448e..391e5a6548 100644
--- a/gtk/gtkprinteroptionset.c
+++ b/gtk/gtkprinteroptionset.c
@@ -155,6 +155,11 @@ safe_strcmp (const char *a, const char *b)
   return strcmp (a, b);
 }
 
+/**
+ * gtk_printer_option_set_get_groups:
+ *
+ * Return value: (element-type utf8) (transfer full):
+ */
 GList *
 gtk_printer_option_set_get_groups (GtkPrinterOptionSet *set)
 {
diff --git a/gtk/gtkprintoperation-unix.c b/gtk/gtkprintoperation-unix.c
index fb3b51adc0..4ac60de879 100644
--- a/gtk/gtkprintoperation-unix.c
+++ b/gtk/gtkprintoperation-unix.c
@@ -967,12 +967,12 @@ get_page_setup_dialog (GtkWindow        *parent,
 
 /**
  * gtk_print_run_page_setup_dialog:
- * @parent: transient parent, or %NULL
- * @page_setup: an existing #GtkPageSetup, or %NULL
+ * @parent: (allow-none): transient parent
+ * @page_setup: (allow-none): an existing #GtkPageSetup
  * @settings: a #GtkPrintSettings
- * 
- * Runs a page setup dialog, letting the user modify the values from 
- * @page_setup. If the user cancels the dialog, the returned #GtkPageSetup 
+ *
+ * Runs a page setup dialog, letting the user modify the values from
+ * @page_setup. If the user cancels the dialog, the returned #GtkPageSetup
  * is identical to the passed in @page_setup, otherwise it contains the 
  * modifications done in the dialog.
  *
diff --git a/gtk/gtkprintoperation.c b/gtk/gtkprintoperation.c
index 9e7b58137c..bc1b27f57d 100644
--- a/gtk/gtkprintoperation.c
+++ b/gtk/gtkprintoperation.c
@@ -1361,8 +1361,8 @@ gtk_print_operation_new (void)
 /**
  * gtk_print_operation_set_default_page_setup:
  * @op: a #GtkPrintOperation
- * @default_page_setup: a #GtkPageSetup, or %NULL
- * 
+ * @default_page_setup: (allow-none): a #GtkPageSetup, or %NULL
+ *
  * Makes @default_page_setup the default page setup for @op.
  *
  * This page setup will be used by gtk_print_operation_run(),
@@ -1420,8 +1420,8 @@ gtk_print_operation_get_default_page_setup (GtkPrintOperation *op)
 /**
  * gtk_print_operation_set_print_settings:
  * @op: a #GtkPrintOperation
- * @print_settings: #GtkPrintSettings, or %NULL
- * 
+ * @print_settings: (allow-none): #GtkPrintSettings
+ *
  * Sets the print settings for @op. This is typically used to
  * re-establish print settings from a previous print operation,
  * see gtk_print_operation_run().
@@ -2992,9 +2992,9 @@ gtk_print_operation_get_error (GtkPrintOperation  *op,
  * gtk_print_operation_run:
  * @op: a #GtkPrintOperation
  * @action: the action to start
- * @parent: Transient parent of the dialog, or %NULL
+ * @parent: (allow-none): Transient parent of the dialog
  * @error: Return location for errors, or %NULL
- * 
+ *
  * Runs the print operation, by first letting the user modify
  * print settings in the print dialog, and then print the document.
  *
diff --git a/gtk/gtkprintsettings.c b/gtk/gtkprintsettings.c
index ee7d6c69d2..748c6ee0d0 100644
--- a/gtk/gtkprintsettings.c
+++ b/gtk/gtkprintsettings.c
@@ -155,11 +155,11 @@ gtk_print_settings_get (GtkPrintSettings *settings,
  * gtk_print_settings_set:
  * @settings: a #GtkPrintSettings
  * @key: a key
- * @value: a string value, or %NULL
- * 
+ * @value: (allow-none): a string value, or %NULL
+ *
  * Associates @value with @key.
  *
- * Since: 2.10 
+ * Since: 2.10
  */
 void
 gtk_print_settings_set (GtkPrintSettings *settings,
@@ -473,9 +473,9 @@ gtk_print_settings_set_int (GtkPrintSettings *settings,
 /**
  * gtk_print_settings_foreach:
  * @settings: a #GtkPrintSettings
- * @func: the function to call
+ * @func: (scope call) the function to call
  * @user_data: user data for @func
- * 
+ *
  * Calls @func for each key-value pair of @settings.
  *
  * Since: 2.10
diff --git a/gtk/gtkprogressbar.c b/gtk/gtkprogressbar.c
index 96b316748a..f2c51d8d69 100644
--- a/gtk/gtkprogressbar.c
+++ b/gtk/gtkprogressbar.c
@@ -398,6 +398,14 @@ gtk_progress_bar_new (void)
   return pbar;
 }
 
+/**
+ * gtk_progress_bar_new_with_adjustment:
+ * @adjustment: (allow-none):
+ *
+ * Creates a new #GtkProgressBar with an associated #GtkAdjustment.
+ *
+ * Returns: (transfer none): a #GtkProgressBar.
+ */
 GtkWidget*
 gtk_progress_bar_new_with_adjustment (GtkAdjustment *adjustment)
 {
diff --git a/gtk/gtkradioaction.c b/gtk/gtkradioaction.c
index 48784c40d8..1d9cfc56e6 100644
--- a/gtk/gtkradioaction.c
+++ b/gtk/gtkradioaction.c
@@ -395,7 +395,7 @@ create_menu_item (GtkAction *action)
  *     }
  * ]|
  *
- * Returns: the list representing the radio group for this object
+ * Returns:  (element-type GtkAction) (transfer none): the list representing the radio group for this object
  *
  * Since: 2.4
  */
diff --git a/gtk/gtkradiobutton.c b/gtk/gtkradiobutton.c
index f07113fe22..cef0bb216b 100644
--- a/gtk/gtkradiobutton.c
+++ b/gtk/gtkradiobutton.c
@@ -341,6 +341,18 @@ gtk_radio_button_new_with_mnemonic_from_widget (GtkRadioButton *radio_group_memb
   return gtk_radio_button_new_with_mnemonic (l, label);
 }
 
+
+/**
+ * gtk_radio_button_get_group:
+ * @radio_button: a #GtkRadioButton.
+ *
+ * Retrieves the group assigned to a radio button.
+ *
+ * Return value: (element-type GtkRadioButton) (transfer none): a linked list
+ * containing all the radio buttons in the same group
+ * as @radio_button. The returned list is owned by the radio button
+ * and must not be modified or freed.
+ */
 GSList*
 gtk_radio_button_get_group (GtkRadioButton *radio_button)
 {
diff --git a/gtk/gtkradiomenuitem.c b/gtk/gtkradiomenuitem.c
index f17b5ed2b7..9bb5c112fd 100644
--- a/gtk/gtkradiomenuitem.c
+++ b/gtk/gtkradiomenuitem.c
@@ -180,6 +180,16 @@ gtk_radio_menu_item_set_group (GtkRadioMenuItem *radio_menu_item,
   g_object_unref (radio_menu_item);
 }
 
+
+/**
+ * gtk_radio_menu_item_new_with_label:
+ * @group: (element-type GtkRadioMenuItem) (transfer full):
+ * @label: the text for the label
+ *
+ * Creates a new #GtkRadioMenuItem whose child is a simple #GtkLabel.
+ *
+ * Returns: (transfer none): A new #GtkRadioMenuItem
+ */
 GtkWidget*
 gtk_radio_menu_item_new_with_label (GSList *group,
 				    const gchar *label)
diff --git a/gtk/gtkrc.c b/gtk/gtkrc.c
index 70540a3130..691cbf1049 100644
--- a/gtk/gtkrc.c
+++ b/gtk/gtkrc.c
@@ -2028,13 +2028,13 @@ gtk_rc_get_style (GtkWidget *widget)
 /**
  * gtk_rc_get_style_by_paths:
  * @settings: a #GtkSettings object
- * @widget_path: the widget path to use when looking up the style, or %NULL
+ * @widget_path: (allow-none): the widget path to use when looking up the style, or %NULL
  *               if no matching against the widget path should be done
- * @class_path: the class path to use when looking up the style, or %NULL
+ * @class_path: (allow-none): the class path to use when looking up the style, or %NULL
  *               if no matching against the class path should be done.
  * @type: a type that will be used along with parent types of this type
  *        when matching against class styles, or #G_TYPE_NONE
- * 
+ *
  * Creates up a #GtkStyle from styles defined in a RC file by providing
  * the raw components used in matching. This function may be useful
  * when creating pseudo-widgets that should be themed like widgets but
diff --git a/gtk/gtkrecentchooser.c b/gtk/gtkrecentchooser.c
index 5975353b2f..a69b1c21fb 100644
--- a/gtk/gtkrecentchooser.c
+++ b/gtk/gtkrecentchooser.c
@@ -898,7 +898,8 @@ gtk_recent_chooser_unselect_all (GtkRecentChooser *chooser)
  * The return value of this function is affected by the "sort-type" and
  * "limit" properties of @chooser.
  *
- * Return value: A newly allocated list of #GtkRecentInfo objects.  You should
+ * Return value:  (element-type GtkRecentInfo) (transfer full): A newly allocated
+ *   list of #GtkRecentInfo objects.  You should
  *   use gtk_recent_info_unref() on every item of the list, and then free
  *   the list itself using g_list_free().
  *
@@ -1014,7 +1015,8 @@ gtk_recent_chooser_remove_filter (GtkRecentChooser *chooser,
  *
  * Gets the #GtkRecentFilter objects held by @chooser.
  *
- * Return value: A singly linked list of #GtkRecentFilter objects.  You
+ * Return value: (element-type GtkRecentFilter) (transfer container): A singly linked list
+ *   of #GtkRecentFilter objects.  You
  *   should just free the returned list using g_slist_free().
  *
  * Since: 2.10
diff --git a/gtk/gtkrecentmanager.c b/gtk/gtkrecentmanager.c
index 5cedaa0e54..3fd7d34fee 100644
--- a/gtk/gtkrecentmanager.c
+++ b/gtk/gtkrecentmanager.c
@@ -627,7 +627,7 @@ gtk_recent_manager_new (void)
  * in your application without caring about memory management. The
  * returned instance will be freed when you application terminates.
  *
- * Return value: A unique #GtkRecentManager. Do not ref or unref it.
+ * Return value: (transfer none): A unique #GtkRecentManager. Do not ref or unref it.
  *
  * Since: 2.10
  */
@@ -1273,7 +1273,8 @@ gtk_recent_manager_move_item (GtkRecentManager  *recent_manager,
  *
  * Gets the list of recently used resources.
  *
- * Return value: a list of newly allocated #GtkRecentInfo objects. Use
+ * Return value:  (element-type GtkRecentInfo) (transfer full): a list of
+ *   newly allocated #GtkRecentInfo objects. Use
  *   gtk_recent_info_unref() on each item inside the list, and then
  *   free the list itself using g_list_free().
  *
@@ -1723,9 +1724,9 @@ recent_app_info_free (RecentAppInfo *app_info)
  * gtk_recent_info_get_application_info:
  * @info: a #GtkRecentInfo
  * @app_name: the name of the application that has registered this item
- * @app_exec: return location for the string containing the command line
- * @count: return location for the number of times this item was registered
- * @time_: return location for the timestamp this item was last registered
+ * @app_exec: (transfer none) (out): return location for the string containing the command line
+ * @count: (out): return location for the number of times this item was registered
+ * @time_: (out): return location for the timestamp this item was last registered
  *    for this application
  *
  * Gets the data regarding the application that has registered the resource
@@ -1779,15 +1780,15 @@ gtk_recent_info_get_application_info (GtkRecentInfo  *info,
 /**
  * gtk_recent_info_get_applications:
  * @info: a #GtkRecentInfo
- * @length: return location for the length of the returned list, or %NULL
+ * @length: (out) (allow-none): return location for the length of the returned list
  *
  * Retrieves the list of applications that have registered this resource.
  *
- * Return value: a newly allocated %NULL-terminated array of strings.
- *   Use g_strfreev() to free it.
+ * Return value: (array length=length zero-terminated=1): a newly allocated
+ *  %NULL-terminated array of strings. Use g_strfreev() to free it.
  *
  * Since: 2.10
- */ 			      
+ */
 gchar **
 gtk_recent_info_get_applications (GtkRecentInfo *info,
 				  gsize         *length)
@@ -2274,14 +2275,14 @@ gtk_recent_info_get_age (GtkRecentInfo *info)
 /**
  * gtk_recent_info_get_groups:
  * @info: a #GtkRecentInfo
- * @length: return location for the number of groups returned, or %NULL
+ * @length: (out) (allow-none): return location for the number of groups returned
  *
  * Returns all groups registered for the recently used item @info.  The
  * array of returned group names will be %NULL terminated, so length might
  * optionally be %NULL.
  *
- * Return value: a newly allocated %NULL terminated array of strings.  Use
- *   g_strfreev() to free it.
+ * Return value:  (array length=length zero-terminated=1): a newly allocated
+ * %NULL terminated array of strings.  Use g_strfreev() to free it.
  *
  * Since: 2.10
  */
diff --git a/gtk/gtkscrolledwindow.c b/gtk/gtkscrolledwindow.c
index e1ef6333bb..b4112ae5f7 100644
--- a/gtk/gtkscrolledwindow.c
+++ b/gtk/gtkscrolledwindow.c
@@ -377,12 +377,12 @@ gtk_scrolled_window_init (GtkScrolledWindow *scrolled_window)
 
 /**
  * gtk_scrolled_window_new:
- * @hadjustment: horizontal adjustment
- * @vadjustment: vertical adjustment
- * 
- * Creates a new scrolled window. 
+ * @hadjustment: (allow-none): horizontal adjustment
+ * @vadjustment: (allow-none): vertical adjustment
+ *
+ * Creates a new scrolled window.
  *
- * The two arguments are the scrolled window's adjustments; these will be 
+ * The two arguments are the scrolled window's adjustments; these will be
  * shared with the scrollbars and the child widget to keep the bars in sync 
  * with the child. Usually you want to pass %NULL for the adjustments, which 
  * will cause the scrolled window to create them for you.
diff --git a/gtk/gtkselection.c b/gtk/gtkselection.c
index 541d5e5d95..1c350ee7da 100644
--- a/gtk/gtkselection.c
+++ b/gtk/gtkselection.c
@@ -635,8 +635,8 @@ gtk_target_table_free (GtkTargetEntry *targets,
 
 /**
  * gtk_selection_owner_set_for_display:
- * @display: the #Gdkdisplay where the selection is set 
- * @widget: new selection owner (a #GdkWidget), or %NULL.
+ * @display: the #Gdkdisplay where the selection is set
+ * @widget: (allow-none): new selection owner (a #GdkWidget), or %NULL.
  * @selection: an interned atom representing the selection to claim.
  * @time_: timestamp with which to claim the selection
  *
@@ -1756,10 +1756,11 @@ gtk_selection_data_set_uris (GtkSelectionData  *selection_data,
  * @selection_data: a #GtkSelectionData
  * 
  * Gets the contents of the selection data as array of URIs.
- * 
- * Return value: if the selection data contains a list of
+ *
+ * Return value:  (array zero-terminated=1) (element-type utf8) (transfer full): if
+ *   the selection data contains a list of
  *   URIs, a newly allocated %NULL-terminated string array
- *   containing the URIs, otherwise %NULL. If the result is 
+ *   containing the URIs, otherwise %NULL. If the result is
  *   non-%NULL it must be freed with g_strfreev().
  *
  * Since: 2.6
diff --git a/gtk/gtksettings.c b/gtk/gtksettings.c
index 9c744daef7..9e28fb9229 100644
--- a/gtk/gtksettings.c
+++ b/gtk/gtksettings.c
@@ -1063,8 +1063,8 @@ gtk_settings_get_for_screen (GdkScreen *screen)
  * 
  * Gets the #GtkSettings object for the default GDK screen, creating
  * it if necessary. See gtk_settings_get_for_screen().
- * 
- * Return value: a #GtkSettings object. If there is no default
+ *
+ * Return value: (transfer none): a #GtkSettings object. If there is no default
  *  screen, then returns %NULL.
  **/
 GtkSettings*
diff --git a/gtk/gtksizegroup.c b/gtk/gtksizegroup.c
index 6cd02c0e2e..645cdef358 100644
--- a/gtk/gtksizegroup.c
+++ b/gtk/gtksizegroup.c
@@ -585,8 +585,8 @@ gtk_size_group_remove_widget (GtkSizeGroup *size_group,
  * 
  * Returns the list of widgets associated with @size_group.
  *
- * Return value: a #GSList of widgets. The list is owned by GTK+ 
- *   and should not be modified.
+ * Return value:  (element-type GtkWidget) (transfer none): a #GSList of
+ *   widgets. The list is owned by GTK+ and should not be modified.
  *
  * Since: 2.10
  **/
diff --git a/gtk/gtkspinbutton.c b/gtk/gtkspinbutton.c
index a61ea841ec..ebae4c0fca 100644
--- a/gtk/gtkspinbutton.c
+++ b/gtk/gtkspinbutton.c
@@ -1596,6 +1596,16 @@ gtk_spin_button_default_output (GtkSpinButton *spin_button)
  ***********************************************************/
 
 
+/**
+ * gtk_spin_button_configure:
+ * @spin_button: a #GtkSpinButton
+ * @adjustment: (allow-none):  a #GtkAdjustment.
+ * @climb_rate: the new climb rate.
+ * @digits: the number of decimal places to display in the spin button.
+ *
+ * Changes the properties of an existing spin button. The adjustment, climb rate,
+ * and number of decimal places are all changed accordingly, after this function call.
+ */
 void
 gtk_spin_button_configure (GtkSpinButton  *spin_button,
 			   GtkAdjustment  *adjustment,
diff --git a/gtk/gtkstatusicon.c b/gtk/gtkstatusicon.c
index f400bff73c..2492af8850 100644
--- a/gtk/gtkstatusicon.c
+++ b/gtk/gtkstatusicon.c
@@ -1875,9 +1875,9 @@ gtk_status_icon_set_image (GtkStatusIcon *status_icon,
 /**
  * gtk_status_icon_set_from_pixbuf:
  * @status_icon: a #GtkStatusIcon
- * @pixbuf: a #GdkPixbuf or %NULL
- * 
- * Makes @status_icon display @pixbuf. 
+ * @pixbuf: (allow-none): a #GdkPixbuf or %NULL
+ *
+ * Makes @status_icon display @pixbuf.
  * See gtk_status_icon_new_from_pixbuf() for details.
  *
  * Since: 2.10
@@ -2212,7 +2212,7 @@ gtk_status_icon_get_screen (GtkStatusIcon *status_icon)
 /**
  * gtk_status_icon_set_tooltip:
  * @status_icon: a #GtkStatusIcon
- * @tooltip_text: the tooltip text, or %NULL
+ * @tooltip_text: (allow-none): the tooltip text, or %NULL
  *
  * Sets the tooltip of the status icon.
  *
@@ -2561,13 +2561,13 @@ gtk_status_icon_position_menu (GtkMenu  *menu,
 /**
  * gtk_status_icon_get_geometry:
  * @status_icon: a #GtkStatusIcon
- * @screen: return location for the screen, or %NULL if the
- *          information is not needed 
- * @area: return location for the area occupied by the status 
+ * @screen: (out) (transfer none) (allow-none): return location for the screen, or %NULL if the
+ *          information is not needed
+ * @area: (out) (allow-none): return location for the area occupied by the status
  *        icon, or %NULL
- * @orientation: return location for the orientation of the panel 
- *    in which the status icon is embedded, or %NULL. A panel 
- *    at the top or bottom of the screen is horizontal, a panel 
+ * @orientation: (out) (allow-none): return location for the orientation of the panel
+ *    in which the status icon is embedded, or %NULL. A panel
+ *    at the top or bottom of the screen is horizontal, a panel
  *    at the left or right is vertical.
  *
  * Obtains information about the location of the status icon
diff --git a/gtk/gtkstock.c b/gtk/gtkstock.c
index dfff951ba8..2ba74ae2cc 100644
--- a/gtk/gtkstock.c
+++ b/gtk/gtkstock.c
@@ -215,8 +215,8 @@ gtk_stock_lookup (const gchar  *stock_id,
  * Retrieves a list of all known stock IDs added to a #GtkIconFactory
  * or registered with gtk_stock_add(). The list must be freed with g_slist_free(),
  * and each string in the list must be freed with g_free().
- * 
- * Return value: a list of known stock IDs
+ *
+ * Return value: (element-type utf8) (transfer full): a list of known stock IDs
  **/
 GSList*
 gtk_stock_list_ids (void)
diff --git a/gtk/gtkstyle.c b/gtk/gtkstyle.c
index c806aeee44..70b05c1c23 100644
--- a/gtk/gtkstyle.c
+++ b/gtk/gtkstyle.c
@@ -2169,12 +2169,12 @@ gtk_style_real_set_background (GtkStyle    *style,
  * @state: a state
  * @size: the size to render the icon at. A size of (GtkIconSize)-1
  *        means render at the size of the source and don't scale.
- * @widget: the widget 
- * @detail: a style detail
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @returns: a newly-created #GdkPixbuf containing the rendered icon
  *
- * Renders the icon specified by @source at the given @size 
- * according to the given parameters and returns the result in a 
+ * Renders the icon specified by @source at the given @size
+ * according to the given parameters and returns the result in a
  * pixbuf.
  */
 GdkPixbuf *
@@ -2200,6 +2200,19 @@ gtk_style_render_icon (GtkStyle            *style,
 }
 
 /* Default functions */
+
+/**
+ * gtk_style_apply_default_background:
+ * @style:
+ * @window:
+ * @set_bg:
+ * @state_type:
+ * @area: (allow-none):
+ * @x:
+ * @y:
+ * @width:
+ * @height:
+ */
 void
 gtk_style_apply_default_background (GtkStyle          *style,
                                     GdkWindow         *window,
@@ -5878,14 +5891,14 @@ hls_to_rgb (gdouble *h,
  * @style: a #GtkStyle
  * @window: a #GdkWindow
  * @state_type: a state
- * @area: rectangle to which the output is clipped, or %NULL if the
+ * @area: (allow-none): rectangle to which the output is clipped, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x1: the starting x coordinate
  * @x2: the ending x coordinate
  * @y: the y coordinate
- * 
+ *
  * Draws a horizontal line from (@x1, @y) to (@x2, @y) in @window
  * using the given style and state.
  **/ 
@@ -5914,14 +5927,14 @@ gtk_paint_hline (GtkStyle           *style,
  * @style: a #GtkStyle
  * @window: a #GdkWindow
  * @state_type: a state
- * @area: rectangle to which the output is clipped, or %NULL if the
+ * @area: (allow-none): rectangle to which the output is clipped, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @y1_: the starting y coordinate
  * @y2_: the ending y coordinate
  * @x: the x coordinate
- * 
+ *
  * Draws a vertical line from (@x, @y1_) to (@x, @y2_) in @window
  * using the given style and state.
  */
@@ -5951,14 +5964,14 @@ gtk_paint_vline (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: type of shadow to draw
- * @area: clip rectangle or %NULL if the
+ * @area: (allow-none): clip rectangle or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: x origin of the rectangle
  * @y: y origin of the rectangle
- * @width: width of the rectangle 
- * @height: width of the rectangle 
+ * @width: width of the rectangle
+ * @height: width of the rectangle
  *
  * Draws a shadow around the given rectangle in @window 
  * using the given style and state and shadow type.
@@ -5991,14 +6004,14 @@ gtk_paint_shadow (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: type of shadow to draw
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @points: an array of #GdkPoint<!-- -->s
  * @n_points: length of @points
  * @fill: %TRUE if the polygon should be filled
- * 
+ *
  * Draws a polygon on @window with the given parameters.
  */ 
 void
@@ -6028,10 +6041,10 @@ gtk_paint_polygon (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: the type of shadow to draw
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @arrow_type: the type of arrow to draw
  * @fill: %TRUE if the arrow tip should be filled
  * @x: x origin of the rectangle to draw the arrow in
@@ -6072,10 +6085,10 @@ gtk_paint_arrow (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: the type of shadow to draw
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: x origin of the rectangle to draw the diamond in
  * @y: y origin of the rectangle to draw the diamond in
  * @width: width of the rectangle to draw the diamond in
@@ -6111,14 +6124,14 @@ gtk_paint_diamond (GtkStyle           *style,
  * @style: a #GtkStyle
  * @window: a #GdkWindow
  * @state_type: a state
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: x origin
  * @y: y origin
  * @string: the string to draw
- * 
+ *
  * Draws a text string on @window with the given parameters.
  *
  * Deprecated: 2.0: Use gtk_paint_layout() instead.
@@ -6149,10 +6162,10 @@ gtk_paint_string (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: the type of shadow to draw
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: x origin of the box
  * @y: y origin of the box
  * @width: the width of the box
@@ -6188,10 +6201,10 @@ gtk_paint_box (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: the type of shadow to draw
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: x origin of the box
  * @y: y origin of the box
  * @width: the width of the box
@@ -6227,10 +6240,10 @@ gtk_paint_flat_box (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: the type of shadow to draw
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: x origin of the rectangle to draw the check in
  * @y: y origin of the rectangle to draw the check in
  * @width: the width of the rectangle to draw the check in
@@ -6267,10 +6280,10 @@ gtk_paint_check (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: the type of shadow to draw
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: x origin of the rectangle to draw the option in
  * @y: y origin of the rectangle to draw the option in
  * @width: the width of the rectangle to draw the option in
@@ -6307,10 +6320,10 @@ gtk_paint_option (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: the type of shadow to draw
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: x origin of the rectangle to draw the tab in
  * @y: y origin of the rectangle to draw the tab in
  * @width: the width of the rectangle to draw the tab in
@@ -6347,14 +6360,14 @@ gtk_paint_tab (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: type of shadow to draw
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: x origin of the rectangle
  * @y: y origin of the rectangle
- * @width: width of the rectangle 
- * @height: width of the rectangle 
+ * @width: width of the rectangle
+ * @height: width of the rectangle
  * @gap_side: side in which to leave the gap
  * @gap_x: starting position of the gap
  * @gap_width: width of the gap
@@ -6395,14 +6408,14 @@ gtk_paint_shadow_gap (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: type of shadow to draw
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: x origin of the rectangle
  * @y: y origin of the rectangle
- * @width: width of the rectangle 
- * @height: width of the rectangle 
+ * @width: width of the rectangle
+ * @height: width of the rectangle
  * @gap_side: side in which to leave the gap
  * @gap_x: starting position of the gap
  * @gap_width: width of the gap
@@ -6441,14 +6454,14 @@ gtk_paint_box_gap (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: type of shadow to draw
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: x origin of the extension
  * @y: y origin of the extension
- * @width: width of the extension 
- * @height: width of the extension 
+ * @width: width of the extension
+ * @height: width of the extension
  * @gap_side: the side on to which the extension is attached
  * 
  * Draws an extension, i.e. a notebook tab.
@@ -6481,10 +6494,10 @@ gtk_paint_extension (GtkStyle           *style,
  * @style: a #GtkStyle
  * @window: a #GdkWindow
  * @state_type: a state
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none):  clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: the x origin of the rectangle around which to draw a focus indicator
  * @y: the y origin of the rectangle around which to draw a focus indicator
  * @width: the width of the rectangle around which to draw a focus indicator
@@ -6520,10 +6533,10 @@ gtk_paint_focus (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: a shadow
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: the x origin of the rectangle in which to draw a slider
  * @y: the y origin of the rectangle in which to draw a slider
  * @width: the width of the rectangle in which to draw a slider
@@ -6562,10 +6575,10 @@ gtk_paint_slider (GtkStyle           *style,
  * @window: a #GdkWindow
  * @state_type: a state
  * @shadow_type: type of shadow to draw
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: x origin of the handle
  * @y: y origin of the handle
  * @width: with of the handle
@@ -6602,10 +6615,10 @@ gtk_paint_handle (GtkStyle           *style,
  * @style: a #GtkStyle
  * @window: a #GdkWindow
  * @state_type: a state
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: the x position to draw the expander at
  * @y: the y position to draw the expander at
  * @expander_style: the style to draw the expander in; determines
@@ -6649,14 +6662,14 @@ gtk_paint_expander (GtkStyle           *style,
  * @state_type: a state
  * @use_text: whether to use the text or foreground
  *            graphics context of @style
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @x: x origin
  * @y: y origin
  * @layout: the layout to draw
- * 
+ *
  * Draws a layout on @window using the given parameters.
  **/
 void
@@ -6685,10 +6698,10 @@ gtk_paint_layout (GtkStyle           *style,
  * @style: a #GtkStyle
  * @window: a #GdkWindow
  * @state_type: a state
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget
+ * @detail: (allow-none): a style detail
  * @edge: the edge in which to draw the resize grip
  * @x: the x origin of the rectangle in which to draw the resize grip
  * @y: the y origin of the rectangle in which to draw the resize grip
@@ -7136,8 +7149,8 @@ draw_insertion_cursor (GtkWidget          *widget,
 /**
  * gtk_draw_insertion_cursor:
  * @widget:  a #GtkWidget
- * @drawable: a #GdkDrawable 
- * @area: rectangle to which the output is clipped, or %NULL if the
+ * @drawable: a #GdkDrawable
+ * @area: (allow-none): rectangle to which the output is clipped, or %NULL if the
  *        output should not be clipped
  * @location: location where to draw the cursor (@location->width is ignored)
  * @is_primary: if the cursor should be the primary cursor color.
diff --git a/gtk/gtktextbuffer.c b/gtk/gtktextbuffer.c
index f82b6d875b..e223d92527 100644
--- a/gtk/gtktextbuffer.c
+++ b/gtk/gtktextbuffer.c
@@ -805,7 +805,7 @@ _gtk_text_buffer_get_btree (GtkTextBuffer *buffer)
  *
  * Get the #GtkTextTagTable associated with this buffer.
  *
- * Return value: the buffer's tag table
+ * Return value: (transfer none): the buffer's tag table
  **/
 GtkTextTagTable*
 gtk_text_buffer_get_tag_table (GtkTextBuffer *buffer)
@@ -2061,7 +2061,7 @@ gtk_text_buffer_set_mark (GtkTextBuffer     *buffer,
 /**
  * gtk_text_buffer_create_mark:
  * @buffer: a #GtkTextBuffer
- * @mark_name: name for mark, or %NULL
+ * @mark_name: (allow-none): name for mark, or %NULL
  * @where: location to place mark
  * @left_gravity: whether the mark has left gravity
  *
@@ -2224,7 +2224,7 @@ gtk_text_buffer_delete_mark (GtkTextBuffer *buffer,
  * Returns the mark named @name in buffer @buffer, or %NULL if no such
  * mark exists in the buffer.
  *
- * Return value: a #GtkTextMark, or %NULL
+ * Return value: (transfer none): a #GtkTextMark, or %NULL
  **/
 GtkTextMark*
 gtk_text_buffer_get_mark (GtkTextBuffer *buffer,
@@ -2307,7 +2307,7 @@ gtk_text_buffer_delete_mark_by_name (GtkTextBuffer *buffer,
  * named "insert", but very slightly more efficient, and involves less
  * typing.
  *
- * Return value: insertion point mark
+ * Return value: (transfer none): insertion point mark
  **/
 GtkTextMark*
 gtk_text_buffer_get_insert (GtkTextBuffer *buffer)
@@ -2333,7 +2333,7 @@ gtk_text_buffer_get_insert (GtkTextBuffer *buffer)
  * for handling the selection, if you just want to know whether there's a
  * selection and what its bounds are.
  *
- * Return value: selection bound mark
+ * Return value: (transfer none): selection bound mark
  **/
 GtkTextMark*
 gtk_text_buffer_get_selection_bound (GtkTextBuffer *buffer)
@@ -3732,11 +3732,11 @@ remove_all_selection_clipboards (GtkTextBuffer *buffer)
  * gtk_text_buffer_paste_clipboard:
  * @buffer: a #GtkTextBuffer
  * @clipboard: the #GtkClipboard to paste from
- * @override_location: location to insert pasted text, or %NULL for 
+ * @override_location: (allow-none): location to insert pasted text, or %NULL for
  *                     at the cursor
  * @default_editable: whether the buffer is editable by default
  *
- * Pastes the contents of a clipboard at the insertion point, or at 
+ * Pastes the contents of a clipboard at the insertion point, or at
  * @override_location. (Note: pasting is asynchronous, that is, we'll 
  * ask for the paste data and return, and at some point later after 
  * the main loop runs, the paste data will be inserted.)
diff --git a/gtk/gtktextbufferrichtext.c b/gtk/gtktextbufferrichtext.c
index 22de4db05b..16501f7681 100644
--- a/gtk/gtktextbufferrichtext.c
+++ b/gtk/gtktextbufferrichtext.c
@@ -104,7 +104,7 @@ gtk_text_buffer_register_serialize_format (GtkTextBuffer              *buffer,
 /**
  * gtk_text_buffer_register_serialize_tagset:
  * @buffer: a #GtkTextBuffer
- * @tagset_name: an optional tagset name, on %NULL
+ * @tagset_name: (allow-none): an optional tagset name, on %NULL
  *
  * This function registers GTK+'s internal rich text serialization
  * format with the passed @buffer. The internal format does not comply
@@ -202,7 +202,7 @@ gtk_text_buffer_register_deserialize_format (GtkTextBuffer                *buffe
 /**
  * gtk_text_buffer_register_deserialize_tagset:
  * @buffer: a #GtkTextBuffer
- * @tagset_name: an optional tagset name, on %NULL
+ * @tagset_name: (allow-none): an optional tagset name, on %NULL
  *
  * This function registers GTK+'s internal rich text serialization
  * format with the passed @buffer. See
diff --git a/gtk/gtktextchild.c b/gtk/gtktextchild.c
index 163954f6e4..aaf171576d 100644
--- a/gtk/gtktextchild.c
+++ b/gtk/gtktextchild.c
@@ -384,9 +384,9 @@ gtk_text_child_anchor_finalize (GObject *obj)
  * 
  * Gets a list of all widgets anchored at this child anchor.
  * The returned list should be freed with g_list_free().
- * 
- * 
- * Return value: list of widgets anchored at @anchor
+ *
+ *
+ * Return value: (element-type GtkWidget) (transfer container): list of widgets anchored at @anchor
  **/
 GList*
 gtk_text_child_anchor_get_widgets (GtkTextChildAnchor *anchor)
diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c
index 37d4c2d4d2..360c855a3e 100644
--- a/gtk/gtktextiter.c
+++ b/gtk/gtktextiter.c
@@ -371,7 +371,7 @@ check_invariants (const GtkTextIter *iter)
  *
  * Returns the #GtkTextBuffer this iterator is associated with.
  *
- * Return value: the buffer
+ * Return value: (transfer none): the buffer
  **/
 GtkTextBuffer*
 gtk_text_iter_get_buffer (const GtkTextIter *iter)
@@ -972,7 +972,7 @@ gtk_text_iter_get_visible_text (const GtkTextIter  *start,
  * (with no new reference count added). Otherwise,
  * %NULL is returned.
  *
- * Return value: the pixbuf at @iter
+ * Return value: (transfer none): the pixbuf at @iter
  **/
 GdkPixbuf*
 gtk_text_iter_get_pixbuf (const GtkTextIter *iter)
@@ -1034,7 +1034,7 @@ gtk_text_iter_get_child_anchor (const GtkTextIter *iter)
  * can exist in the same place. The returned list is not in any
  * meaningful order.
  *
- * Return value: list of #GtkTextMark
+ * Return value: (element-type GtkTextMark) (transfer container): list of #GtkTextMark
  **/
 GSList*
 gtk_text_iter_get_marks (const GtkTextIter *iter)
@@ -1080,7 +1080,7 @@ gtk_text_iter_get_marks (const GtkTextIter *iter)
  * a tag is toggled off, then some non-empty range following @iter
  * does <emphasis>not</emphasis> have the tag applied to it.
  *
- * Return value: tags toggled at this point
+ * Return value: (element-type GtkTextTag) (transfer container): tags toggled at this point
  **/
 GSList*
 gtk_text_iter_get_toggled_tags  (const GtkTextIter  *iter,
@@ -1129,7 +1129,7 @@ gtk_text_iter_get_toggled_tags  (const GtkTextIter  *iter,
 /**
  * gtk_text_iter_begins_tag:
  * @iter: an iterator
- * @tag: a #GtkTextTag, or %NULL
+ * @tag: (allow-none): a #GtkTextTag, or %NULL
  *
  * Returns %TRUE if @tag is toggled on at exactly this point. If @tag
  * is %NULL, returns %TRUE if any tag is toggled on at this point. Note
@@ -1222,7 +1222,7 @@ gtk_text_iter_ends_tag   (const GtkTextIter  *iter,
 /**
  * gtk_text_iter_toggles_tag:
  * @iter: an iterator
- * @tag: a #GtkTextTag, or %NULL
+ * @tag: (allow-none): a #GtkTextTag, or %NULL
  *
  * This is equivalent to (gtk_text_iter_begins_tag () ||
  * gtk_text_iter_ends_tag ()), i.e. it tells you whether a range with
@@ -1307,8 +1307,8 @@ gtk_text_iter_has_tag (const GtkTextIter   *iter,
  * priority (highest-priority tags are last). The #GtkTextTag in the
  * list don't have a reference added, but you have to free the list
  * itself.
- * 
- * Return value: list of #GtkTextTag
+ *
+ * Return value: (element-type GtkTextTag) (transfer container): list of #GtkTextTag
  **/
 GSList*
 gtk_text_iter_get_tags (const GtkTextIter *iter)
@@ -4111,7 +4111,7 @@ gtk_text_iter_forward_to_line_end (GtkTextIter *iter)
 /**
  * gtk_text_iter_forward_to_tag_toggle:
  * @iter: a #GtkTextIter
- * @tag: a #GtkTextTag, or %NULL
+ * @tag: (allow-none): a #GtkTextTag, or %NULL
  *
  * Moves forward to the next toggle (on or off) of the
  * #GtkTextTag @tag, or to the next toggle of any tag if
@@ -4193,7 +4193,7 @@ gtk_text_iter_forward_to_tag_toggle (GtkTextIter *iter,
 /**
  * gtk_text_iter_backward_to_tag_toggle:
  * @iter: a #GtkTextIter
- * @tag: a #GtkTextTag, or %NULL
+ * @tag: (allow-none): a #GtkTextTag, or %NULL
  *
  * Moves backward to the next toggle (on or off) of the
  * #GtkTextTag @tag, or to the next toggle of any tag if
@@ -4571,12 +4571,12 @@ strbreakup (const char *string,
  * @iter: start of search
  * @str: a search string
  * @flags: flags affecting how the search is done
- * @match_start: return location for start of match, or %NULL
- * @match_end: return location for end of match, or %NULL
- * @limit: bound for the search, or %NULL for the end of the buffer
- * 
- * Searches forward for @str. Any match is returned by setting 
- * @match_start to the first character of the match and @match_end to the 
+ * @match_start: (allow-none): return location for start of match, or %NULL
+ * @match_end: (allow-none): return location for end of match, or %NULL
+ * @limit: (allow-none): bound for the search, or %NULL for the end of the buffer
+ *
+ * Searches forward for @str. Any match is returned by setting
+ * @match_start to the first character of the match and @match_end to the
  * first character after the match. The search will not continue past
  * @limit. Note that a search is a linear or O(n) operation, so you
  * may wish to use @limit to avoid locking up your UI on large
@@ -4868,12 +4868,12 @@ lines_window_free (LinesWindow *win)
  * @iter: a #GtkTextIter where the search begins
  * @str: search string
  * @flags: bitmask of flags affecting the search
- * @match_start: return location for start of match, or %NULL
- * @match_end: return location for end of match, or %NULL
- * @limit: location of last possible @match_start, or %NULL for start of buffer
- * 
+ * @match_start: (allow-none): return location for start of match, or %NULL
+ * @match_end: (allow-none): return location for end of match, or %NULL
+ * @limit: (allow-none): location of last possible @match_start, or %NULL for start of buffer
+ *
  * Same as gtk_text_iter_forward_search(), but moves backward.
- * 
+ *
  * Return value: whether a match was found
  **/
 gboolean
diff --git a/gtk/gtktextlayout.c b/gtk/gtktextlayout.c
index 8c5d419b63..c4c7143984 100644
--- a/gtk/gtktextlayout.c
+++ b/gtk/gtktextlayout.c
@@ -299,6 +299,10 @@ gtk_text_layout_finalize (GObject *object)
   G_OBJECT_CLASS (gtk_text_layout_parent_class)->finalize (object);
 }
 
+/**
+ * gtk_text_layout_set_buffer:
+ * @buffer: (allow-none):
+ */
 void
 gtk_text_layout_set_buffer (GtkTextLayout *layout,
                             GtkTextBuffer *buffer)
@@ -703,6 +707,12 @@ gtk_text_layout_wrap (GtkTextLayout *layout,
   return GTK_TEXT_LAYOUT_GET_CLASS (layout)->wrap (layout, line, line_data);
 }
 
+
+/**
+ * gtk_text_layout_get_lines:
+ *
+ * Return value: (element-type GtkTextLine) (transfer container):
+ */
 GSList*
 gtk_text_layout_get_lines (GtkTextLayout *layout,
                            /* [top_y, bottom_y) */
diff --git a/gtk/gtktextmark.c b/gtk/gtktextmark.c
index 359e310d24..5964108a57 100644
--- a/gtk/gtktextmark.c
+++ b/gtk/gtktextmark.c
@@ -283,8 +283,8 @@ gtk_text_mark_get_deleted (GtkTextMark *mark)
  * 
  * Gets the buffer this mark is located inside,
  * or %NULL if the mark is deleted.
- * 
- * Return value: the mark's #GtkTextBuffer
+ *
+ * Return value: (transfer none): the mark's #GtkTextBuffer
  **/
 GtkTextBuffer*
 gtk_text_mark_get_buffer (GtkTextMark *mark)
diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c
index bbbdf6b806..cf698fff73 100644
--- a/gtk/gtktextview.c
+++ b/gtk/gtktextview.c
@@ -1363,7 +1363,7 @@ gtk_text_view_new_with_buffer (GtkTextBuffer *buffer)
 /**
  * gtk_text_view_set_buffer:
  * @text_view: a #GtkTextView
- * @buffer: a #GtkTextBuffer
+ * @buffer: (allow-none): a #GtkTextBuffer
  *
  * Sets @buffer as the buffer being displayed by @text_view. The previous
  * buffer displayed by the text view is unreferenced, and a reference is
@@ -1504,7 +1504,7 @@ get_buffer (GtkTextView *text_view)
  * The reference count on the buffer is not incremented; the caller
  * of this function won't own a new reference.
  *
- * Return value: a #GtkTextBuffer
+ * Return value: (transfer none): a #GtkTextBuffer
  **/
 GtkTextBuffer*
 gtk_text_view_get_buffer (GtkTextView *text_view)
@@ -8199,7 +8199,7 @@ text_window_get_height (GtkTextWindow *win)
  * height is 0, and are nonexistent before the widget has been
  * realized.
  *
- * Return value: a #GdkWindow, or %NULL
+ * Return value: (transfer none): a #GdkWindow, or %NULL
  **/
 GdkWindow*
 gtk_text_view_get_window (GtkTextView *text_view,
diff --git a/gtk/gtktoolbar.c b/gtk/gtktoolbar.c
index 70126ca2ab..b83790ccac 100644
--- a/gtk/gtktoolbar.c
+++ b/gtk/gtktoolbar.c
@@ -2253,11 +2253,11 @@ logical_to_physical (GtkToolbar *toolbar,
 /**
  * gtk_toolbar_set_drop_highlight_item:
  * @toolbar: a #GtkToolbar
- * @tool_item: a #GtkToolItem, or %NULL to turn of highlighting
+ * @tool_item: (allow-none): a #GtkToolItem, or %NULL to turn of highlighting
  * @index_: a position on @toolbar
- * 
+ *
  * Highlights @toolbar to give an idea of what it would look like
- * if @item was added to @toolbar at the position indicated by @index_. 
+ * if @item was added to @toolbar at the position indicated by @index_.
  * If @item is %NULL, highlighting is turned off. In that case @index_ 
  * is ignored.
  *
@@ -3518,9 +3518,9 @@ gtk_toolbar_remove_space (GtkToolbar *toolbar,
 /**
  * gtk_toolbar_append_widget:
  * @toolbar: a #GtkToolbar.
- * @widget: a #GtkWidget to add to the toolbar. 
- * @tooltip_text: the element's tooltip.
- * @tooltip_private_text: used for context-sensitive help about this toolbar element.
+ * @widget: a #GtkWidget to add to the toolbar.
+ * @tooltip_text: (allow-none): the element's tooltip.
+ * @tooltip_private_text: (allow-none): used for context-sensitive help about this toolbar element.
  *
  * Adds a widget to the end of the given toolbar.
  *
@@ -3542,9 +3542,9 @@ gtk_toolbar_append_widget (GtkToolbar  *toolbar,
 /**
  * gtk_toolbar_prepend_widget:
  * @toolbar: a #GtkToolbar.
- * @widget: a #GtkWidget to add to the toolbar. 
- * @tooltip_text: the element's tooltip.
- * @tooltip_private_text: used for context-sensitive help about this toolbar element.
+ * @widget: a #GtkWidget to add to the toolbar.
+ * @tooltip_text: (allow-none): the element's tooltip.
+ * @tooltip_private_text: (allow-none): used for context-sensitive help about this toolbar element.
  *
  * Adds a widget to the beginning of the given toolbar.
  *
@@ -3566,11 +3566,11 @@ gtk_toolbar_prepend_widget (GtkToolbar  *toolbar,
 /**
  * gtk_toolbar_insert_widget:
  * @toolbar: a #GtkToolbar.
- * @widget: a #GtkWidget to add to the toolbar. 
- * @tooltip_text: the element's tooltip.
- * @tooltip_private_text: used for context-sensitive help about this toolbar element.
+ * @widget: a #GtkWidget to add to the toolbar.
+ * @tooltip_text: (allow-none): the element's tooltip.
+ * @tooltip_private_text: (allow-none): used for context-sensitive help about this toolbar element.
  * @position: the number of widgets to insert this widget after.
- * 
+ *
  * Inserts a widget in the toolbar at the given position.
  *
  * Deprecated: 2.4: Use gtk_toolbar_insert() instead.
diff --git a/gtk/gtktoolbutton.c b/gtk/gtktoolbutton.c
index 38055e06cf..5fdcc548f0 100644
--- a/gtk/gtktoolbutton.c
+++ b/gtk/gtktoolbutton.c
@@ -921,12 +921,12 @@ gtk_tool_button_new_from_stock (const gchar *stock_id)
 
 /**
  * gtk_tool_button_new:
- * @label: a string that will be used as label, or %NULL
- * @icon_widget: a widget that will be used as icon widget, or %NULL
- * 
+ * @label: (allow-none): a string that will be used as label, or %NULL
+ * @icon_widget: (allow-none): a widget that will be used as icon widget, or %NULL
+ *
  * Creates a new %GtkToolButton using @icon_widget as icon and @label as
  * label.
- * 
+ *
  * Return value: A new #GtkToolButton
  * 
  * Since: 2.4
@@ -948,8 +948,8 @@ gtk_tool_button_new (GtkWidget	 *icon_widget,
 /**
  * gtk_tool_button_set_label:
  * @button: a #GtkToolButton
- * @label: a string that will be used as label, or %NULL.
- * 
+ * @label: (allow-none): a string that will be used as label, or %NULL.
+ *
  * Sets @label as the label used for the tool button. The "label" property
  * only has an effect if not overridden by a non-%NULL "label_widget" property.
  * If both the "label_widget" and "label" properties are %NULL, the label
@@ -1062,8 +1062,8 @@ gtk_tool_button_get_use_underline (GtkToolButton *button)
 /**
  * gtk_tool_button_set_stock_id:
  * @button: a #GtkToolButton
- * @stock_id: a name of a stock item, or %NULL
- * 
+ * @stock_id: (allow-none): a name of a stock item, or %NULL
+ *
  * Sets the name of the stock item. See gtk_tool_button_new_from_stock().
  * The stock_id property only has an effect if not
  * overridden by non-%NULL "label" and "icon_widget" properties.
@@ -1110,8 +1110,8 @@ gtk_tool_button_get_stock_id (GtkToolButton *button)
 /**
  * gtk_tool_button_set_icon_name
  * @button: a #GtkToolButton
- * @icon_name: the name of the themed icon
- * 
+ * @icon_name: (allow-none): the name of the themed icon
+ *
  * Sets the icon for the tool button from a named themed icon.
  * See the docs for #GtkIconTheme for more details.
  * The "icon_name" property only has an effect if not
@@ -1161,8 +1161,8 @@ gtk_tool_button_get_icon_name (GtkToolButton *button)
 /**
  * gtk_tool_button_set_icon_widget:
  * @button: a #GtkToolButton
- * @icon_widget: the widget used as icon, or %NULL
- * 
+ * @icon_widget: (allow-none): the widget used as icon, or %NULL
+ *
  * Sets @icon as the widget used as icon on @button. If @icon_widget is
  * %NULL the icon is determined by the "stock_id" property. If the
  * "stock_id" property is also %NULL, @button will not have an icon.
@@ -1200,8 +1200,8 @@ gtk_tool_button_set_icon_widget (GtkToolButton *button,
 /**
  * gtk_tool_button_set_label_widget:
  * @button: a #GtkToolButton
- * @label_widget: the widget used as label, or %NULL
- * 
+ * @label_widget: (allow-none): the widget used as label, or %NULL
+ *
  * Sets @label_widget as the widget that will be used as the label
  * for @button. If @label_widget is %NULL the "label" property is used
  * as label. If "label" is also %NULL, the label in the stock item
diff --git a/gtk/gtktoolitem.c b/gtk/gtktoolitem.c
index 5ad31cce4b..1cae42908f 100644
--- a/gtk/gtktoolitem.c
+++ b/gtk/gtktoolitem.c
@@ -1094,10 +1094,10 @@ gtk_tool_item_real_set_tooltip (GtkToolItem *tool_item,
 
 /**
  * gtk_tool_item_set_tooltip:
- * @tool_item: a #GtkToolItem 
+ * @tool_item: a #GtkToolItem
  * @tooltips: The #GtkTooltips object to be used
- * @tip_text: text to be used as tooltip text for @tool_item
- * @tip_private: text to be used as private tooltip text
+ * @tip_text: (allow-none): text to be used as tooltip text for @tool_item
+ * @tip_private: (allow-none): text to be used as private tooltip text
  *
  * Sets the #GtkTooltips object to be used for @tool_item, the
  * text to be displayed as tooltip on the item and the private text
@@ -1332,10 +1332,10 @@ gtk_tool_item_get_visible_vertical (GtkToolItem *toolitem)
  * Returns the #GtkMenuItem that was last set by
  * gtk_tool_item_set_proxy_menu_item(), ie. the #GtkMenuItem
  * that is going to appear in the overflow menu.
- * 
- * Return value: The #GtkMenuItem that is going to appear in the
+ *
+ * Return value: (transfer none): The #GtkMenuItem that is going to appear in the
  * overflow menu for @tool_item.
- * 
+ *
  * Since: 2.4
  **/
 GtkWidget *
diff --git a/gtk/gtktooltips.c b/gtk/gtktooltips.c
index a414346b9f..6c9131073d 100644
--- a/gtk/gtktooltips.c
+++ b/gtk/gtktooltips.c
@@ -210,6 +210,17 @@ gtk_tooltips_data_get (GtkWidget       *widget)
   return g_object_get_data (G_OBJECT (widget), tooltips_data_key);
 }
 
+
+/**
+ * gtk_tooltips_set_tip:
+ * @tooltips: a #GtkTooltips.
+ * @widget: the #GtkWidget you wish to associate the tip with.
+ * @tip_text: (allow-none): a string containing the tip itself.
+ * @tip_private: (allow-none): a string of any further information that may be useful if the user gets stuck.
+ *
+ * Adds a tooltip containing the message @tip_text to the specified #GtkWidget.
+ * Deprecated: 2.12:
+ */
 void
 gtk_tooltips_set_tip (GtkTooltips *tooltips,
 		      GtkWidget   *widget,
diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index c8cc7b2dad..0d0a4920e4 100644
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -1173,10 +1173,10 @@ gtk_tree_model_iter_next (GtkTreeModel  *tree_model,
  * gtk_tree_model_iter_children:
  * @tree_model: A #GtkTreeModel.
  * @iter: The new #GtkTreeIter to be set to the child.
- * @parent: The #GtkTreeIter, or %NULL
+ * @parent: (allow-none): The #GtkTreeIter, or %NULL
  *
- * Sets @iter to point to the first child of @parent.  If @parent has no 
- * children, %FALSE is returned and @iter is set to be invalid.  @parent 
+ * Sets @iter to point to the first child of @parent.  If @parent has no
+ * children, %FALSE is returned and @iter is set to be invalid.  @parent
  * will remain a valid node after this function has been called.
  *
  * If @parent is %NULL returns the first node, equivalent to
@@ -1229,7 +1229,7 @@ gtk_tree_model_iter_has_child (GtkTreeModel *tree_model,
 /**
  * gtk_tree_model_iter_n_children:
  * @tree_model: A #GtkTreeModel.
- * @iter: The #GtkTreeIter, or %NULL.
+ * @iter: (allow-none): The #GtkTreeIter, or %NULL.
  *
  * Returns the number of children that @iter has.  As a special case, if @iter
  * is %NULL, then the number of toplevel nodes is returned.
@@ -1254,7 +1254,7 @@ gtk_tree_model_iter_n_children (GtkTreeModel *tree_model,
  * gtk_tree_model_iter_nth_child:
  * @tree_model: A #GtkTreeModel.
  * @iter: The #GtkTreeIter to set to the nth child.
- * @parent: The #GtkTreeIter to get the child from, or %NULL.
+ * @parent: (allow-none): The #GtkTreeIter to get the child from, or %NULL.
  * @n: Then index of the desired child.
  *
  * Sets @iter to be the child of @parent, using the given index.  The first
diff --git a/gtk/gtktreemodelfilter.c b/gtk/gtktreemodelfilter.c
index a3398e602d..a161f47943 100644
--- a/gtk/gtktreemodelfilter.c
+++ b/gtk/gtktreemodelfilter.c
@@ -2956,7 +2956,7 @@ gtk_tree_model_filter_set_root (GtkTreeModelFilter *filter,
 /**
  * gtk_tree_model_filter_new:
  * @child_model: A #GtkTreeModel.
- * @root: A #GtkTreePath or %NULL.
+ * @root: (allow-none): A #GtkTreePath or %NULL.
  *
  * Creates a new #GtkTreeModel, with @child_model as the child_model
  * and @root as the virtual root.
diff --git a/gtk/gtktreeselection.c b/gtk/gtktreeselection.c
index 462f2da7a5..9513f2b788 100644
--- a/gtk/gtktreeselection.c
+++ b/gtk/gtktreeselection.c
@@ -327,8 +327,8 @@ gtk_tree_selection_get_tree_view (GtkTreeSelection *selection)
 /**
  * gtk_tree_selection_get_selected:
  * @selection: A #GtkTreeSelection.
- * @model: A pointer to set to the #GtkTreeModel, or NULL.
- * @iter: The #GtkTreeIter, or NULL.
+ * @model: (out) (allow-none): A pointer to set to the #GtkTreeModel, or NULL.
+ * @iter: (allow-none): The #GtkTreeIter, or NULL.
  *
  * Sets @iter to the currently selected node if @selection is set to
  * #GTK_SELECTION_SINGLE or #GTK_SELECTION_BROWSE.  @iter may be NULL if you
@@ -402,7 +402,7 @@ gtk_tree_selection_get_selected (GtkTreeSelection  *selection,
 /**
  * gtk_tree_selection_get_selected_rows:
  * @selection: A #GtkTreeSelection.
- * @model: A pointer to set to the #GtkTreeModel, or NULL.
+ * @model: (allow-none): A pointer to set to the #GtkTreeModel, or NULL.
  *
  * Creates a list of path of all selected rows. Additionally, if you are
  * planning on modifying the model after calling this function, you may
@@ -415,7 +415,7 @@ gtk_tree_selection_get_selected (GtkTreeSelection  *selection,
  * g_list_free (list);
  * ]|
  *
- * Return value: A #GList containing a #GtkTreePath for each selected row.
+ * Return value: (element-type GtkTreePath) (transfer full): A #GList containing a #GtkTreePath for each selected row.
  *
  * Since: 2.2
  **/
diff --git a/gtk/gtktreestore.c b/gtk/gtktreestore.c
index 81c373e9be..b7fcda89f7 100644
--- a/gtk/gtktreestore.c
+++ b/gtk/gtktreestore.c
@@ -2690,7 +2690,7 @@ free_paths_and_out:
  * gtk_tree_store_move_before:
  * @tree_store: A #GtkTreeStore.
  * @iter: A #GtkTreeIter.
- * @position: A #GtkTreeIter or %NULL.
+ * @position: (allow-none): A #GtkTreeIter or %NULL.
  *
  * Moves @iter in @tree_store to the position before @position. @iter and
  * @position should be in the same level. Note that this function only
@@ -2711,7 +2711,7 @@ gtk_tree_store_move_before (GtkTreeStore *tree_store,
  * gtk_tree_store_move_after:
  * @tree_store: A #GtkTreeStore.
  * @iter: A #GtkTreeIter.
- * @position: A #GtkTreeIter.
+ * @position: (allow-none): A #GtkTreeIter.
  *
  * Moves @iter in @tree_store to the position after @position. @iter and
  * @position should be in the same level. Note that this function only
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index 9d9b488cc0..7c2e00a441 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -10585,10 +10585,10 @@ gtk_tree_view_get_model (GtkTreeView *tree_view)
 /**
  * gtk_tree_view_set_model:
  * @tree_view: A #GtkTreeNode.
- * @model: The model.
+ * @model: (allow-none): The model.
  *
  * Sets the model for a #GtkTreeView.  If the @tree_view already has a model
- * set, it will remove it before setting the new model.  If @model is %NULL, 
+ * set, it will remove it before setting the new model.  If @model is %NULL,
  * then it will unset the old model.
  **/
 void
@@ -11322,7 +11322,7 @@ gtk_tree_view_get_column (GtkTreeView *tree_view,
  * Returns a #GList of all the #GtkTreeViewColumn s currently in @tree_view.
  * The returned list must be freed with g_list_free ().
  *
- * Return value: A list of #GtkTreeViewColumn s
+ * Return value: (element-type GtkTreeViewColumn) (transfer container): A list of #GtkTreeViewColumn s
  **/
 GList *
 gtk_tree_view_get_columns (GtkTreeView *tree_view)
@@ -11336,7 +11336,7 @@ gtk_tree_view_get_columns (GtkTreeView *tree_view)
  * gtk_tree_view_move_column_after:
  * @tree_view: A #GtkTreeView
  * @column: The #GtkTreeViewColumn to be moved.
- * @base_column: The #GtkTreeViewColumn to be moved relative to, or %NULL.
+ * @base_column: (allow-none): The #GtkTreeViewColumn to be moved relative to, or %NULL.
  *
  * Moves @column to be after to @base_column.  If @base_column is %NULL, then
  * @column is placed in the first position.
@@ -11519,8 +11519,8 @@ gtk_tree_view_scroll_to_point (GtkTreeView *tree_view,
 /**
  * gtk_tree_view_scroll_to_cell:
  * @tree_view: A #GtkTreeView.
- * @path: The path of the row to move to, or %NULL.
- * @column: The #GtkTreeViewColumn to move horizontally to, or %NULL.
+ * @path: (allow-none): The path of the row to move to, or %NULL.
+ * @column: (allow-none): The #GtkTreeViewColumn to move horizontally to, or %NULL.
  * @use_align: whether to use alignment arguments, or %FALSE.
  * @row_align: The vertical alignment of the row specified by @path.
  * @col_align: The horizontal alignment of the column specified by @column.
@@ -12512,7 +12512,7 @@ gtk_tree_view_get_cursor (GtkTreeView        *tree_view,
  * gtk_tree_view_set_cursor:
  * @tree_view: A #GtkTreeView
  * @path: A #GtkTreePath
- * @focus_column: A #GtkTreeViewColumn, or %NULL
+ * @focus_column: (allow-none): A #GtkTreeViewColumn, or %NULL
  * @start_editing: %TRUE if the specified cell should start being edited.
  *
  * Sets the current keyboard focus to be at @path, and selects it.  This is
@@ -12541,8 +12541,8 @@ gtk_tree_view_set_cursor (GtkTreeView       *tree_view,
  * gtk_tree_view_set_cursor_on_cell:
  * @tree_view: A #GtkTreeView
  * @path: A #GtkTreePath
- * @focus_column: A #GtkTreeViewColumn, or %NULL
- * @focus_cell: A #GtkCellRenderer, or %NULL
+ * @focus_column: (allow-none): A #GtkTreeViewColumn, or %NULL
+ * @focus_cell: (allow-none): A #GtkCellRenderer, or %NULL
  * @start_editing: %TRUE if the specified cell should start being edited.
  *
  * Sets the current keyboard focus to be at @path, and selects it.  This is
@@ -12764,8 +12764,8 @@ gtk_tree_view_get_path_at_pos (GtkTreeView        *tree_view,
 /**
  * gtk_tree_view_get_cell_area:
  * @tree_view: a #GtkTreeView
- * @path: a #GtkTreePath for the row, or %NULL to get only horizontal coordinates
- * @column: a #GtkTreeViewColumn for the column, or %NULL to get only vertical coordinates
+ * @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
  *
  * Fills the bounding rectangle in bin_window coordinates for the cell at the
@@ -13948,7 +13948,7 @@ gtk_tree_view_get_search_entry (GtkTreeView *tree_view)
 /**
  * gtk_tree_view_set_search_entry:
  * @tree_view: A #GtkTreeView
- * @entry: the entry the interactive search code of @tree_view should use or %NULL
+ * @entry: (allow-none): the entry the interactive search code of @tree_view should use or %NULL
  *
  * Sets the entry which the interactive search code will use for this
  * @tree_view.  This is useful when you want to provide a search entry
diff --git a/gtk/gtktreeviewcolumn.c b/gtk/gtktreeviewcolumn.c
index edec5deffe..c132c9d790 100644
--- a/gtk/gtktreeviewcolumn.c
+++ b/gtk/gtktreeviewcolumn.c
@@ -2245,8 +2245,8 @@ gtk_tree_view_column_get_clickable (GtkTreeViewColumn *tree_column)
 /**
  * gtk_tree_view_column_set_widget:
  * @tree_column: A #GtkTreeViewColumn.
- * @widget: A child #GtkWidget, or %NULL.
- * 
+ * @widget: (allow-none): A child #GtkWidget, or %NULL.
+ *
  * Sets the widget in the header to be @widget.  If widget is %NULL, then the
  * header button is set with a #GtkLabel set to the title of @tree_column.
  **/
diff --git a/gtk/gtkuimanager.c b/gtk/gtkuimanager.c
index 9ebaa92f41..6112bf799f 100644
--- a/gtk/gtkuimanager.c
+++ b/gtk/gtkuimanager.c
@@ -786,7 +786,8 @@ gtk_ui_manager_remove_action_group (GtkUIManager   *self,
  * 
  * Returns the list of action groups associated with @self.
  *
- * Return value: a #GList of action groups. The list is owned by GTK+ 
+ * Return value:  (element-type GtkActionGroup) (transfer none): a #GList of
+ *   action groups. The list is owned by GTK+
  *   and should not be modified.
  *
  * Since: 2.4
@@ -805,7 +806,7 @@ gtk_ui_manager_get_action_groups (GtkUIManager *self)
  * 
  * Returns the #GtkAccelGroup associated with @self.
  *
- * Return value: the #GtkAccelGroup.
+ * Return value: (transfer none): the #GtkAccelGroup.
  *
  * Since: 2.4
  **/
@@ -835,8 +836,8 @@ gtk_ui_manager_get_accel_group (GtkUIManager *self)
  * the lifecycle of the ui manager. If you add the widgets returned by this 
  * function to some container or explicitly ref them, they will survive the
  * destruction of the ui manager.
- * 
- * Return value: the widget found by following the path, or %NULL if no widget
+ *
+ * Return value: (transfer none): the widget found by following the path, or %NULL if no widget
  *   was found.
  *
  * Since: 2.4
@@ -891,9 +892,9 @@ collect_toplevels (GNode   *node,
  *   #GTK_UI_MANAGER_POPUP.
  * 
  * Obtains a list of all toplevel widgets of the requested types.
- * 
- * Return value: a newly-allocated #GSList of all toplevel widgets of the
- * requested types.  Free the returned list with g_slist_free().
+ *
+ * Return value: (element-type GtkWidget) (transfer container): a newly-allocated #GSList of
+ * all toplevel widgets of the requested types.  Free the returned list with g_slist_free().
  *
  * Since: 2.4
  **/
@@ -1736,11 +1737,11 @@ gtk_ui_manager_add_ui_from_file (GtkUIManager *self,
  * @merge_id: the merge id for the merged UI, see gtk_ui_manager_new_merge_id()
  * @path: a path
  * @name: the name for the added UI element
- * @action: the name of the action to be proxied, or %NULL to add a separator
+ * @action: (allow-none): the name of the action to be proxied, or %NULL to add a separator
  * @type: the type of UI element to add.
- * @top: if %TRUE, the UI element is added before its siblings, otherwise it 
+ * @top: if %TRUE, the UI element is added before its siblings, otherwise it
  *   is added after its siblings.
- * 
+ *
  * Adds a UI element to the current contents of @self. 
  *
  * If @type is %GTK_UI_MANAGER_AUTO, GTK+ inserts a menuitem, toolitem or 
diff --git a/gtk/gtkviewport.c b/gtk/gtkviewport.c
index 5fd9014ab4..4fd37b5666 100644
--- a/gtk/gtkviewport.c
+++ b/gtk/gtkviewport.c
@@ -466,8 +466,8 @@ viewport_set_adjustment (GtkViewport    *viewport,
 /**
  * gtk_viewport_set_hadjustment:
  * @viewport: a #GtkViewport.
- * @adjustment: a #GtkAdjustment.
- * 
+ * @adjustment: (allow-none): a #GtkAdjustment.
+ *
  * Sets the horizontal adjustment of the viewport.
  **/
 void
@@ -486,8 +486,8 @@ gtk_viewport_set_hadjustment (GtkViewport   *viewport,
 /**
  * gtk_viewport_set_vadjustment:
  * @viewport: a #GtkViewport.
- * @adjustment: a #GtkAdjustment.
- * 
+ * @adjustment: (allow-none): a #GtkAdjustment.
+ *
  * Sets the vertical adjustment of the viewport.
  **/
 void
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 74392eb0b3..cf1d3610d9 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -3132,7 +3132,7 @@ gtk_widget_destroy (GtkWidget *widget)
 /**
  * gtk_widget_destroyed:
  * @widget: a #GtkWidget
- * @widget_pointer: address of a variable that contains @widget
+ * @widget_pointer: (inout) (transfer none): address of a variable that contains @widget
  *
  * This function sets *@widget_pointer to %NULL if @widget_pointer !=
  * %NULL.  It's intended to be used as a callback connected to the
@@ -4159,9 +4159,9 @@ gtk_widget_common_ancestor (GtkWidget *widget_a,
  * @dest_widget: a #GtkWidget
  * @src_x: X position relative to @src_widget
  * @src_y: Y position relative to @src_widget
- * @dest_x: location to store X position relative to @dest_widget
- * @dest_y: location to store Y position relative to @dest_widget
- * 
+ * @dest_x: (out): location to store X position relative to @dest_widget
+ * @dest_y: (out): location to store Y position relative to @dest_widget
+ *
  * Translate coordinates relative to @src_widget's allocation to coordinates
  * relative to @dest_widget's allocations. In order to perform this
  * operation, both widgets must be realized, and must share a common
@@ -4543,9 +4543,9 @@ destroy_accel_path (gpointer data)
 /**
  * gtk_widget_set_accel_path:
  * @widget: a #GtkWidget
- * @accel_path: path used to look up the accelerator
- * @accel_group: a #GtkAccelGroup.
- * 
+ * @accel_path: (allow-none): path used to look up the accelerator
+ * @accel_group: (allow-none): a #GtkAccelGroup.
+ *
  * Given an accelerator group, @accel_group, and an accelerator path,
  * @accel_path, sets up an accelerator in @accel_group so whenever the
  * key binding that is defined for @accel_path is pressed, @widget
@@ -4977,8 +4977,8 @@ gtk_widget_activate (GtkWidget *widget)
 /**
  * gtk_widget_set_scroll_adjustments:
  * @widget: a #GtkWidget
- * @hadjustment: an adjustment for horizontal scrolling, or %NULL
- * @vadjustment: an adjustment for vertical scrolling, or %NULL
+ * @hadjustment: (allow-none): an adjustment for horizontal scrolling, or %NULL
+ * @vadjustment: (allow-none): an adjustment for vertical scrolling, or %NULL
  *
  * For widgets that support scrolling, sets the scroll adjustments and
  * returns %TRUE.  For widgets that don't support scrolling, does
@@ -6275,7 +6275,7 @@ gtk_widget_set_parent (GtkWidget *widget,
  *
  * Returns the parent container of @widget.
  *
- * Return value: the parent container of @widget, or %NULL
+ * Return value: (transfer none): the parent container of @widget, or %NULL
  **/
 GtkWidget *
 gtk_widget_get_parent (GtkWidget *widget)
@@ -6293,7 +6293,7 @@ gtk_widget_get_parent (GtkWidget *widget)
 /**
  * gtk_widget_set_style:
  * @widget: a #GtkWidget
- * @style: a #GtkStyle, or %NULL to remove the effect of a previous
+ * @style: (allow-none): a #GtkStyle, or %NULL to remove the effect of a previous
  *         gtk_widget_set_style() and go back to the default style
  *
  * Sets the #GtkStyle for a widget (@widget->style). You probably don't
@@ -6372,8 +6372,8 @@ gtk_widget_reset_rc_style (GtkWidget *widget)
  * @widget: a #GtkWidget
  * 
  * Simply an accessor function that returns @widget->style.
- * 
- * Return value: the widget's #GtkStyle
+ *
+ * Return value: (transfer none): the widget's #GtkStyle
  **/
 GtkStyle*
 gtk_widget_get_style (GtkWidget *widget)
@@ -6442,8 +6442,8 @@ gtk_widget_modify_style (GtkWidget      *widget,
  * the passed-in style and sets the copy as the new modifier style,
  * thus dropping any reference to the old modifier style. Add a reference
  * to the modifier style if you want to keep it alive.
- * 
- * Return value: the modifier style for the widget. This rc style is
+ *
+ * Return value: (transfer none): the modifier style for the widget. This rc style is
  *   owned by the widget. If you want to keep a pointer to value this
  *   around, you must add a refcount using g_object_ref().
  **/
@@ -6508,11 +6508,11 @@ gtk_widget_modify_color_component (GtkWidget      *widget,
  * gtk_widget_modify_fg:
  * @widget: a #GtkWidget
  * @state: the state for which to set the foreground color
- * @color: the color to assign (does not need to be allocated),
+ * @color: (allow-none): the color to assign (does not need to be allocated),
  *         or %NULL to undo the effect of previous calls to
  *         of gtk_widget_modify_fg().
- * 
- * Sets the foreground color for a widget in a particular state.  
+ *
+ * Sets the foreground color for a widget in a particular state.
  * All other style values are left untouched. See also
  * gtk_widget_modify_style().
  **/
@@ -6531,11 +6531,11 @@ gtk_widget_modify_fg (GtkWidget      *widget,
  * gtk_widget_modify_bg:
  * @widget: a #GtkWidget
  * @state: the state for which to set the background color
- * @color: the color to assign (does not need to be allocated),
+ * @color: (allow-none): the color to assign (does not need to be allocated),
  *         or %NULL to undo the effect of previous calls to
  *         of gtk_widget_modify_bg().
- * 
- * Sets the background color for a widget in a particular state.  
+ *
+ * Sets the background color for a widget in a particular state.
  * All other style values are left untouched. See also
  * gtk_widget_modify_style(). 
  *
@@ -6562,10 +6562,10 @@ gtk_widget_modify_bg (GtkWidget      *widget,
  * gtk_widget_modify_text:
  * @widget: a #GtkWidget
  * @state: the state for which to set the text color
- * @color: the color to assign (does not need to be allocated),
+ * @color: (allow-none): the color to assign (does not need to be allocated),
  *         or %NULL to undo the effect of previous calls to
  *         of gtk_widget_modify_text().
- * 
+ *
  * Sets the text color for a widget in a particular state.  All other
  * style values are left untouched. The text color is the foreground
  * color used along with the base color (see gtk_widget_modify_base())
@@ -6587,10 +6587,10 @@ gtk_widget_modify_text (GtkWidget      *widget,
  * gtk_widget_modify_base:
  * @widget: a #GtkWidget
  * @state: the state for which to set the base color
- * @color: the color to assign (does not need to be allocated),
+ * @color: (allow-none): the color to assign (does not need to be allocated),
  *         or %NULL to undo the effect of previous calls to
  *         of gtk_widget_modify_base().
- * 
+ *
  * Sets the base color for a widget in a particular state.
  * All other style values are left untouched. The base color
  * is the background color used along with the text color
@@ -6683,9 +6683,9 @@ gtk_widget_modify_cursor (GtkWidget      *widget,
 /**
  * gtk_widget_modify_font:
  * @widget: a #GtkWidget
- * @font_desc: the font description to use, or %NULL to undo
+ * @font_desc: (allow-none): the font description to use, or %NULL to undo
  *   the effect of previous calls to gtk_widget_modify_font().
- * 
+ *
  * Sets the font to use for a widget.  All other style values are left
  * untouched. See also gtk_widget_modify_style().
  **/
@@ -6993,10 +6993,10 @@ gtk_widget_reset_rc_styles (GtkWidget *widget)
  * gtk_widget_get_default_style:
  * 
  * Returns the default style used by all widgets initially.
- * 
- * Returns: the default style. This #GtkStyle object is owned 
+ *
+ * Returns: (transfer none): the default style. This #GtkStyle object is owned
  *          by GTK+ and should not be modified or freed.
- */ 
+ */
 GtkStyle*
 gtk_widget_get_default_style (void)
 {
@@ -7031,7 +7031,7 @@ gtk_widget_peek_pango_context (GtkWidget *widget)
  * on the layout in response to the #GtkWidget::style-set and 
  * #GtkWidget::direction-changed signals for the widget.
  *
- * Return value: the #PangoContext for the widget.
+ * Return value: (transfer none): the #PangoContext for the widget.
  **/
 PangoContext *
 gtk_widget_get_pango_context (GtkWidget *widget)
@@ -7160,10 +7160,10 @@ gtk_widget_create_pango_layout (GtkWidget   *widget,
  * @widget: a #GtkWidget
  * @stock_id: a stock ID
  * @size: a stock size. A size of (GtkIconSize)-1 means render at 
- *     the size of the source and don't scale (if there are multiple 
+ *     the size of the source and don't scale (if there are multiple
  *     source sizes, GTK+ picks one of the available sizes).
- * @detail: render detail to pass to theme engine
- * 
+ * @detail: (allow-none): render detail to pass to theme engine
+ *
  * A convenience function that uses the theme engine and RC file
  * settings for @widget to look up @stock_id and render it to
  * a pixbuf. @stock_id should be a stock icon ID such as
@@ -7241,9 +7241,10 @@ gtk_widget_set_parent_window   (GtkWidget           *widget,
 /**
  * gtk_widget_get_parent_window:
  * @widget: a #GtkWidget.
- * @returns: the parent window of @widget.
  *
  * Gets @widget's parent window.
+ *
+ * Returns: (transfer none): the parent window of @widget.
  **/
 GdkWindow *
 gtk_widget_get_parent_window (GtkWidget *widget)
@@ -7368,8 +7369,8 @@ gtk_widget_get_screen_unchecked (GtkWidget *widget)
  * In general, you should only create screen specific
  * resources when a widget has been realized, and you should
  * free those resources when the widget is unrealized.
- * 
- * Return value: the #GdkScreen for the toplevel for this widget.
+ *
+ * Return value: (transfer none): the #GdkScreen for the toplevel for this widget.
  *
  * Since: 2.2
  **/
@@ -7430,8 +7431,8 @@ gtk_widget_has_screen (GtkWidget *widget)
  * In general, you should only create display specific
  * resources when a widget has been realized, and you should
  * free those resources when the widget is unrealized.
- * 
- * Return value: the #GdkDisplay for the toplevel for this widget.
+ *
+ * Return value: (transfer none): the #GdkDisplay for the toplevel for this widget.
  *
  * Since: 2.2
  **/
@@ -7455,8 +7456,8 @@ gtk_widget_get_display (GtkWidget *widget)
  * #GdkWindow associated with the window. In general, you should only
  * create display specific resources when a widget has been realized,
  * and you should free those resources when the widget is unrealized.
- * 
- * Return value: the #GdkWindow root window for the toplevel for this widget.
+ *
+ * Return value: (transfer none): the #GdkWindow root window for the toplevel for this widget.
  *
  * Since: 2.2
  **/
@@ -7813,8 +7814,8 @@ gtk_widget_set_size_request (GtkWidget *widget,
 /**
  * gtk_widget_get_size_request:
  * @widget: a #GtkWidget
- * @width: return location for width, or %NULL
- * @height: return location for height, or %NULL
+ * @width: (out): return location for width, or %NULL
+ * @height: (out): return location for height, or %NULL
  *
  * Gets the size request that was explicitly set for the widget using
  * gtk_widget_set_size_request(). A value of -1 stored in @width or
@@ -7984,7 +7985,7 @@ gtk_widget_set_extension_events (GtkWidget *widget,
  *    }
  * ]|
  *
- * Return value: the topmost ancestor of @widget, or @widget itself 
+ * Return value: (transfer none): the topmost ancestor of @widget, or @widget itself
  *    if there's no ancestor.
  **/
 GtkWidget*
@@ -8013,7 +8014,7 @@ gtk_widget_get_toplevel (GtkWidget *widget)
  * Note that unlike gtk_widget_is_ancestor(), gtk_widget_get_ancestor() 
  * considers @widget to be an ancestor of itself.
  *
- * Return value: the ancestor widget, or %NULL if not found
+ * Return value: (transfer none): the ancestor widget, or %NULL if not found
  **/
 GtkWidget*
 gtk_widget_get_ancestor (GtkWidget *widget,
@@ -8036,8 +8037,8 @@ gtk_widget_get_ancestor (GtkWidget *widget,
  * 
  * Gets the colormap that will be used to render @widget. No reference will
  * be added to the returned colormap; it should not be unreferenced.
- * 
- * Return value: the colormap used by @widget
+ *
+ * Return value: (transfer none): the colormap used by @widget
  **/
 GdkColormap*
 gtk_widget_get_colormap (GtkWidget *widget)
@@ -8073,8 +8074,8 @@ gtk_widget_get_colormap (GtkWidget *widget)
  * @widget: a #GtkWidget
  * 
  * Gets the visual that will be used to render @widget.
- * 
- * Return value: the visual for @widget
+ *
+ * Return value: (transfer none): the visual for @widget
  **/
 GdkVisual*
 gtk_widget_get_visual (GtkWidget *widget)
@@ -8094,8 +8095,8 @@ gtk_widget_get_visual (GtkWidget *widget)
  * Note that this function can only be called when the #GtkWidget
  * is attached to a toplevel, since the settings object is specific
  * to a particular #GdkScreen.
- * 
- * Return value: the relevant #GtkSettings object
+ *
+ * Return value: (transfer none): the relevant #GtkSettings object
  **/
 GtkSettings*
 gtk_widget_get_settings (GtkWidget *widget)
@@ -8169,8 +8170,8 @@ gtk_widget_get_extension_events (GtkWidget *widget)
 /**
  * gtk_widget_get_pointer:
  * @widget: a #GtkWidget
- * @x: return location for the X coordinate, or %NULL
- * @y: return location for the Y coordinate, or %NULL
+ * @x: (out) (allow-none): return location for the X coordinate, or %NULL
+ * @y: (out) (allow-none): return location for the Y coordinate, or %NULL
  *
  * Obtains the location of the mouse pointer in widget coordinates.
  * Widget coordinates are a bit odd; for historical reasons, they are
@@ -8372,8 +8373,8 @@ gtk_widget_set_default_colormap (GdkColormap *colormap)
  * gtk_widget_get_default_colormap:
  * 
  * Obtains the default colormap used to create widgets.
- * 
- * Return value: default widget colormap
+ *
+ * Return value: (transfer none): default widget colormap
  **/
 GdkColormap*
 gtk_widget_get_default_colormap (void)
@@ -8386,8 +8387,8 @@ gtk_widget_get_default_colormap (void)
  * 
  * Obtains the visual of the default colormap. Not really useful;
  * used to be useful before gdk_colormap_get_visual() existed.
- * 
- * Return value: visual of the default colormap
+ *
+ * Return value: (transfer none): visual of the default colormap
  **/
 GdkVisual*
 gtk_widget_get_default_visual (void)
@@ -9205,12 +9206,12 @@ gtk_widget_shape_combine_mask (GtkWidget *widget,
 }
 
 /**
- * gtk_widget_input_shape_combine_mask: 
+ * gtk_widget_input_shape_combine_mask:
  * @widget: a #GtkWidget
- * @shape_mask: shape to be added, or %NULL to remove an existing shape
+ * @shape_mask: (allow-none): shape to be added, or %NULL to remove an existing shape
  * @offset_x: X position of shape mask with respect to @window
  * @offset_y: Y position of shape mask with respect to @window
- * 
+ *
  * Sets an input shape for this widget's GDK window. This allows for
  * windows which react to mouse click in a nonrectangular region, see 
  * gdk_window_input_shape_combine_mask() for more information.
@@ -9796,9 +9797,9 @@ gtk_widget_style_get (GtkWidget   *widget,
 /**
  * gtk_widget_path:
  * @widget: a #GtkWidget
- * @path_length: location to store length of the path, or %NULL
- * @path: location to store allocated path string, or %NULL 
- * @path_reversed: location to store allocated reverse path string, or %NULL
+ * @path_length: (out) (allow-none): location to store length of the path, or %NULL
+ * @path: (out) (allow-none):  location to store allocated path string, or %NULL
+ * @path_reversed: (out) (allow-none):  location to store allocated reverse path string, or %NULL
  *
  * Obtains the full path to @widget. The path is simply the name of a
  * widget and all its parents in the container hierarchy, separated by
@@ -9869,9 +9870,9 @@ gtk_widget_path (GtkWidget *widget,
 /**
  * gtk_widget_class_path:
  * @widget: a #GtkWidget
- * @path_length: location to store the length of the class path, or %NULL
- * @path: location to store the class path as an allocated string, or %NULL
- * @path_reversed: location to store the reverse class path as an allocated 
+ * @path_length: (out) (allow-none): location to store the length of the class path, or %NULL
+ * @path: (out) (allow-none) location to store the class path as an allocated string, or %NULL
+ * @path_reversed: (out) (allow-none) location to store the reverse class path as an allocated
  *    string, or %NULL
  *
  * Same as gtk_widget_path(), but always uses the name of a widget's type,
@@ -9986,10 +9987,10 @@ gtk_requisition_get_type (void)
  *
  * The documentation of the <ulink url="http://developer.gnome.org/doc/API/2.0/atk/index.html">ATK</ulink>
  * library contains more information about accessible objects and their uses.
- * 
- * Returns: the #AtkObject associated with @widget
+ *
+ * Returns: (transfer none): the #AtkObject associated with @widget
  */
-AtkObject* 
+AtkObject*
 gtk_widget_get_accessible (GtkWidget *widget)
 {
   GtkWidgetClass *klass;
@@ -10576,8 +10577,8 @@ gtk_widget_buildable_custom_finished (GtkBuildable *buildable,
  * be used with @widget. @widget must have a #GdkDisplay
  * associated with it, so must be attached to a toplevel
  * window.
- * 
- * Return value: the appropriate clipboard object. If no
+ *
+ * Return value: (transfer none): the appropriate clipboard object. If no
  *             clipboard already exists, a new one will
  *             be created. Once a clipboard object has
  *             been created, it is persistent for all time.
@@ -10609,7 +10610,8 @@ gtk_widget_get_clipboard (GtkWidget *widget, GdkAtom selection)
  * (GFunc)g_object_ref, NULL)</literal> first, and then unref all the
  * widgets afterwards.
 
- * Return value: the list of mnemonic labels; free this list
+ * Return value: (element-type GtkWidget) (transfer container): the list of
+ *  mnemonic labels; free this list
  *  with g_list_free() when you are done with it.
  *
  * Since: 2.4
@@ -10826,7 +10828,7 @@ gtk_widget_set_tooltip_window (GtkWidget *widget,
  * GtkWindow created by default, or the custom tooltip window set
  * using gtk_widget_set_tooltip_window().
  *
- * Return value: The #GtkWindow of the current tooltip.
+ * Return value: (transfer none): The #GtkWindow of the current tooltip.
  *
  * Since: 2.12
  */
@@ -11022,7 +11024,7 @@ gtk_widget_get_has_tooltip (GtkWidget *widget)
 /**
  * gtk_widget_get_allocation:
  * @widget: a #GtkWidget
- * @allocation: a pointer to a #GtkAllocation to copy to
+ * @allocation: (out): a pointer to a #GtkAllocation to copy to
  *
  * Retrieves the widget's allocation.
  *
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 98747b26a8..3a35731b5b 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -1551,7 +1551,7 @@ gtk_window_get_role (GtkWindow *window)
 /**
  * gtk_window_set_focus:
  * @window: a #GtkWindow
- * @focus: widget to be the new focus widget, or %NULL to unset
+ * @focus: (allow-none): widget to be the new focus widget, or %NULL to unset
  *   any focus widget for the toplevel window.
  *
  * If @focus is not the current focus widget, and is focusable, sets
@@ -1606,7 +1606,7 @@ _gtk_window_internal_set_focus (GtkWindow *window,
 /**
  * gtk_window_set_default:
  * @window: a #GtkWindow
- * @default_widget: widget to be the default, or %NULL to unset the
+ * @default_widget: (allow-none): widget to be the default, or %NULL to unset the
  *                  default widget for the toplevel.
  *
  * The default widget is the widget that's activated when the user
@@ -1960,9 +1960,9 @@ gtk_window_activate_focus (GtkWindow *window)
  * Note that this is the widget that would have the focus
  * if the toplevel window focused; if the toplevel window
  * is not focused then  <literal>GTK_WIDGET_HAS_FOCUS (widget)</literal> will
- * not be %TRUE for the widget. 
- * 
- * Return value: the currently focused widget, or %NULL if there is none.
+ * not be %TRUE for the widget.
+ *
+ * Return value: (transfer none): the currently focused widget, or %NULL if there is none.
  **/
 GtkWidget *
 gtk_window_get_focus (GtkWindow *window)
@@ -2071,8 +2071,8 @@ gtk_window_get_modal (GtkWindow *window)
  * callbacks that might destroy the widgets, you <emphasis>must</emphasis> call
  * <literal>g_list_foreach (result, (GFunc)g_object_ref, NULL)</literal> first, and
  * then unref all the widgets afterwards.
- * 
- * Return value: list of toplevel widgets
+ *
+ * Return value: (element-type GtkWidget) (transfer container): list of toplevel widgets
  **/
 GList*
 gtk_window_list_toplevels (void)
@@ -2242,7 +2242,7 @@ gtk_window_unset_transient_for  (GtkWindow *window)
 /**
  * gtk_window_set_transient_for:
  * @window: a #GtkWindow
- * @parent: parent window
+ * @parent: (allow-none): parent window
  *
  * Dialog windows should be set transient for the main application
  * window they were spawned from. This allows <link
@@ -2319,7 +2319,7 @@ gtk_window_set_transient_for  (GtkWindow *window,
  * Fetches the transient parent for this window. See
  * gtk_window_set_transient_for().
  *
- * Return value: the transient parent for this window, or %NULL
+ * Return value: (transfer none): the transient parent for this window, or %NULL
  *    if no transient parent has been set.
  **/
 GtkWindow *
@@ -3414,8 +3414,8 @@ gtk_window_set_icon_list (GtkWindow  *window,
  * Retrieves the list of icons set by gtk_window_set_icon_list().
  * The list is copied, but the reference count on each
  * member won't be incremented.
- * 
- * Return value: copy of window's icon list
+ *
+ * Return value: (element-type GdkPixbuf) (transfer container): copy of window's icon list
  **/
 GList*
 gtk_window_get_icon_list (GtkWindow  *window)
@@ -3435,8 +3435,8 @@ gtk_window_get_icon_list (GtkWindow  *window)
 /**
  * gtk_window_set_icon:
  * @window: a #GtkWindow
- * @icon: icon image, or %NULL
- * 
+ * @icon: (allow-none): icon image, or %NULL
+ *
  * Sets up the icon representing a #GtkWindow. This icon is used when
  * the window is minimized (also known as iconified).  Some window
  * managers or desktop environments may also place it in the window
@@ -3490,11 +3490,11 @@ update_themed_icon (GtkIconTheme *icon_theme,
 /**
  * gtk_window_set_icon_name:
  * @window: a #GtkWindow
- * @name: the name of the themed icon
+ * @name: (allow-none): the name of the themed icon
  *
  * Sets the icon for the window from a named themed icon. See
- * the docs for #GtkIconTheme for more details. 
- * 
+ * the docs for #GtkIconTheme for more details.
+ *
  * Note that this has nothing to do with the WM_ICON_NAME 
  * property which is mentioned in the ICCCM.
  *
@@ -3558,8 +3558,8 @@ gtk_window_get_icon_name (GtkWindow *window)
  * Gets the value set by gtk_window_set_icon() (or if you've
  * called gtk_window_set_icon_list(), gets the first icon in
  * the icon list).
- * 
- * Return value: icon for window
+ *
+ * Return value: (transfer none): icon for window
  **/
 GdkPixbuf*
 gtk_window_get_icon (GtkWindow  *window)
@@ -3994,8 +3994,8 @@ gtk_window_resize (GtkWindow *window,
 /**
  * gtk_window_get_size:
  * @window: a #GtkWindow
- * @width: return location for width, or %NULL
- * @height: return location for height, or %NULL
+ * @width: (out): return location for width, or %NULL
+ * @height: (out): return location for height, or %NULL
  *
  * Obtains the current size of @window. If @window is not onscreen,
  * it returns the size GTK+ will suggest to the <link
@@ -7254,7 +7254,7 @@ gtk_window_set_gravity (GtkWindow *window,
  *
  * Gets the value set by gtk_window_set_gravity().
  *
- * Return value: window gravity
+ * Return value: (transfer none): window gravity
  **/
 GdkGravity
 gtk_window_get_gravity (GtkWindow *window)
@@ -7470,7 +7470,7 @@ gtk_window_check_screen (GtkWindow *window)
  *
  * Returns the #GdkScreen associated with @window.
  *
- * Return value: a #GdkScreen.
+ * Return value: (transfer none): a #GdkScreen.
  *
  * Since: 2.2
  */
@@ -7655,7 +7655,8 @@ gtk_window_group_remove_window (GtkWindowGroup *window_group,
  *
  * Returns a list of the #GtkWindows that belong to @window_group.
  *
- * Returns: A newly-allocated list of windows inside the group.
+ * Returns: (element-type GtkWidget) (transfer container): A newly-allocated list of
+ *   windows inside the group.
  *
  * Since: 2.14
  **/
@@ -7686,9 +7687,9 @@ gtk_window_group_list_windows (GtkWindowGroup *window_group)
  *
  * Returns the group for @window or the default group, if
  * @window is %NULL or if @window does not have an explicit
- * window group. 
+ * window group.
  *
- * Returns: the #GtkWindowGroup for a window or the default group
+ * Returns: (transfer none): the #GtkWindowGroup for a window or the default group
  *
  * Since: 2.10
  */