From 5cded4d5e29e4c841885894a6fc63f631e2c8c5c Mon Sep 17 00:00:00 2001
From: Pavel Holejsovsky <pholejs@src.gnome.org>
Date: Wed, 26 Jan 2011 12:49:08 +0100
Subject: [PATCH] [GI] Add missing (transfer) annotations

Backported from master commit 2f0d40335b.
---
 gdk/gdkcursor.c              |  2 +-
 gdk/gdkwindow.c              | 14 ++++++++------
 gdk/x11/gdkdisplay-x11.c     |  3 ++-
 gdk/x11/gdkvisual-x11.c      |  4 ++--
 gtk/gtkaboutdialog.c         |  6 +++---
 gtk/gtkaccelgroup.c          |  7 ++++---
 gtk/gtkaction.c              |  5 +++--
 gtk/gtkbindings.c            |  2 +-
 gtk/gtkcontainer.c           | 11 ++++++-----
 gtk/gtkdnd.c                 | 10 +++++-----
 gtk/gtkiconfactory.c         |  4 ++--
 gtk/gtklabel.c               |  3 ++-
 gtk/gtkmain.c                |  3 ++-
 gtk/gtkmenu.c                | 28 ++++++++++++++++++++++++++++
 gtk/gtknotebook.c            |  3 ++-
 gtk/gtkpagesetupunixdialog.c |  4 ++--
 gtk/gtkprintcontext.c        |  2 +-
 gtk/gtkprinter.c             |  2 +-
 gtk/gtkprintjob.c            |  6 +++---
 gtk/gtkprintoperation-unix.c |  2 +-
 gtk/gtkprintoperation.c      |  4 ++--
 gtk/gtkprintunixdialog.c     |  4 ++--
 gtk/gtkradiobutton.c         |  4 ++--
 gtk/gtkrc.c                  |  2 +-
 gtk/gtkselection.c           |  8 ++++----
 gtk/gtkstyle.c               |  2 +-
 gtk/gtktestutils.c           |  8 ++++----
 gtk/gtktextbuffer.c          |  4 ++--
 gtk/gtktextbufferrichtext.c  | 16 ++++++++--------
 gtk/gtkwidget.c              |  4 ++--
 gtk/gtkwindow.c              |  2 +-
 31 files changed, 108 insertions(+), 71 deletions(-)

diff --git a/gdk/gdkcursor.c b/gdk/gdkcursor.c
index 5a6acea3eb..906af1344c 100644
--- a/gdk/gdkcursor.c
+++ b/gdk/gdkcursor.c
@@ -48,7 +48,7 @@ gdk_cursor_get_type (void)
  * 
  * Adds a reference to @cursor.
  * 
- * Return value: Same @cursor that was passed in
+ * Return value: (transfer full): Same @cursor that was passed in
  **/
 GdkCursor*
 gdk_cursor_ref (GdkCursor *cursor)
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index c4e8744488..6d7f00677e 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -507,7 +507,8 @@ gdk_window_class_init (GdkWindowObjectClass *klass)
    * The ::pick-embedded-child signal is emitted to find an embedded
    * child at the given position.
    *
-   * Returns: the #GdkWindow of the embedded child at @x, @y, or %NULL
+   * Returns: (transfer none): the #GdkWindow of the embedded child at
+   *     @x, @y, or %NULL
    *
    * Since: 2.18
    */
@@ -8086,8 +8087,8 @@ gdk_window_set_back_pixmap (GdkWindow *window,
  * does not have its own background and reuses the parent's, %NULL is
  * returned and you'll have to query it yourself.
  *
- * Returns: The pattern to use for the background or %NULL to use the
- * parent's background.
+ * Returns: (transfer none): The pattern to use for the background or
+ *     %NULL to use the parent's background.
  *
  * Since: 2.22
  **/
@@ -8137,9 +8138,10 @@ gdk_window_get_background_pattern (GdkWindow *window)
  * there is no custom cursor set on the specified window, and it is
  * using the cursor for its parent window.
  *
- * Return value: a #GdkCursor, or %NULL. The returned object is owned
- *   by the #GdkWindow and should not be unreferenced directly. Use
- *   gdk_window_set_cursor() to unset the cursor of the window
+ * Return value: (transfer none): a #GdkCursor, or %NULL. The returned
+ *   object is owned by the #GdkWindow and should not be unreferenced
+ *   directly. Use gdk_window_set_cursor() to unset the cursor of the
+ *   window
  *
  * Since: 2.18
  */
diff --git a/gdk/x11/gdkdisplay-x11.c b/gdk/x11/gdkdisplay-x11.c
index 6cded79e4b..47284f233d 100644
--- a/gdk/x11/gdkdisplay-x11.c
+++ b/gdk/x11/gdkdisplay-x11.c
@@ -924,7 +924,8 @@ gdk_x11_lookup_xdisplay (Display *xdisplay)
  * Given the root window ID of one of the screen's of a #GdkDisplay,
  * finds the screen.
  * 
- * Return value: the #GdkScreen corresponding to @xrootwin, or %NULL.
+ * Return value: (transfer none): the #GdkScreen corresponding to
+ *     @xrootwin, or %NULL.
  **/
 GdkScreen *
 _gdk_x11_display_screen_for_xrootwin (GdkDisplay *display,
diff --git a/gdk/x11/gdkvisual-x11.c b/gdk/x11/gdkvisual-x11.c
index a20efba970..6a3f5a576c 100644
--- a/gdk/x11/gdkvisual-x11.c
+++ b/gdk/x11/gdkvisual-x11.c
@@ -551,8 +551,8 @@ gdk_screen_list_visuals (GdkScreen *screen)
  *
  * Looks up the #GdkVisual for a particular screen and X Visual ID.
  *
- * Returns: the #GdkVisual (owned by the screen object), or %NULL
- *   if the visual ID wasn't found.
+ * Returns: (transfer none): the #GdkVisual (owned by the screen
+ *   object), or %NULL if the visual ID wasn't found.
  *
  * Since: 2.2
  */
diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index f63fc3240f..882cee3c67 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -1681,9 +1681,9 @@ gtk_about_dialog_set_translator_credits (GtkAboutDialog *about,
  *
  * Returns the pixbuf displayed as logo in the about dialog.
  *
- * Return value: the pixbuf displayed as logo. The pixbuf is
- *   owned by the about dialog. If you want to keep a reference
- *   to it, you have to call g_object_ref() on it.
+ * Return value: (transfer none): the pixbuf displayed as logo. The
+ *   pixbuf is owned by the about dialog. If you want to keep a
+ *   reference to it, you have to call g_object_ref() on it.
  *
  * Since: 2.6
  */
diff --git a/gtk/gtkaccelgroup.c b/gtk/gtkaccelgroup.c
index 9dbab6f586..32edf4d571 100644
--- a/gtk/gtkaccelgroup.c
+++ b/gtk/gtkaccelgroup.c
@@ -370,8 +370,8 @@ gtk_accel_groups_from_object (GObject *object)
  * @accel_group: a #GtkAccelGroup
  * @find_func: a function to filter the entries of @accel_group with
  * @data: data to pass to @find_func
- * @returns: the key of the first entry passing @find_func. The key is 
- * owned by GTK+ and must not be freed.
+ * @returns: (transfer none): the key of the first entry passing
+ *    @find_func. The key is owned by GTK+ and must not be freed.
  *
  * Finds the first entry in an accelerator group for which 
  * @find_func returns %TRUE and returns its #GtkAccelKey.
@@ -832,7 +832,8 @@ gtk_accel_group_query (GtkAccelGroup  *accel_group,
 /**
  * gtk_accel_group_from_accel_closure:
  * @closure: a #GClosure
- * @returns: (allow-none): the #GtkAccelGroup to which @closure is connected, or %NULL.
+ * @returns: (transfer none): the #GtkAccelGroup to which @closure
+ *     is connected, or %NULL.
  *
  * Finds the #GtkAccelGroup to which @closure is connected; 
  * see gtk_accel_group_connect().
diff --git a/gtk/gtkaction.c b/gtk/gtkaction.c
index 7de87180b1..68934bbb14 100644
--- a/gtk/gtkaction.c
+++ b/gtk/gtkaction.c
@@ -1835,8 +1835,9 @@ gtk_action_get_accel_path (GtkAction *action)
  *
  * Since: 2.8
  *
- * Returns: the accel closure for this action. The returned closure is
- *          owned by GTK+ and must not be unreffed or modified.
+ * Returns: (transfer none): the accel closure for this action. The
+ *          returned closure is owned by GTK+ and must not be unreffed
+ *          or modified.
  */
 GClosure *
 gtk_action_get_accel_closure (GtkAction *action)
diff --git a/gtk/gtkbindings.c b/gtk/gtkbindings.c
index aea76813e9..0519e58321 100644
--- a/gtk/gtkbindings.c
+++ b/gtk/gtkbindings.c
@@ -636,7 +636,7 @@ gtk_binding_set_by_class (gpointer object_class)
  * either be a name used for gtk_binding_set_new() or the type name of
  * a class used in gtk_binding_set_by_class().
  *
- * Return value: %NULL or the specified binding set
+ * Return value: (transfer none): %NULL or the specified binding set
  */
 GtkBindingSet*
 gtk_binding_set_find (const gchar *set_name)
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 16402d95fd..2e091e515a 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -978,10 +978,10 @@ gtk_container_class_install_child_property (GtkContainerClass *cclass,
 
 /**
  * gtk_container_class_find_child_property:
- * @cclass: a #GtkContainerClass
+ * @cclass: (type GtkContainerClass): a #GtkContainerClass
  * @property_name: the name of the child property to find
- * @returns: (allow-none): the #GParamSpec of the child property or %NULL if @class has no
- *   child property with that name.
+ * @returns: (transfer none): the #GParamSpec of the child property or
+ *           %NULL if @class has no child property with that name.
  *
  * Finds a child property of a container class by name.
  */
@@ -1623,8 +1623,9 @@ gtk_container_set_focus_child (GtkContainer *container,
  * currently focused widget. That can be obtained by calling
  * gtk_window_get_focus().
  *
- * Returns: The child widget which will recieve the focus inside @container when
- *          the @conatiner is focussed, or %NULL if none is set.
+ * Returns: (transfer none): The child widget which will receive the
+ *          focus inside @container when the @conatiner is focussed,
+ *          or %NULL if none is set.
  *
  * Since: 2.14
  **/
diff --git a/gtk/gtkdnd.c b/gtk/gtkdnd.c
index 8571042a66..50266f9420 100644
--- a/gtk/gtkdnd.c
+++ b/gtk/gtkdnd.c
@@ -1363,7 +1363,7 @@ gtk_drag_dest_unset (GtkWidget *widget)
  * Returns the list of targets this widget can accept from
  * drag-and-drop.
  * 
- * Return value: the #GtkTargetList, or %NULL if none
+ * Return value: (transfer none): the #GtkTargetList, or %NULL if none
  **/
 GtkTargetList*
 gtk_drag_dest_get_target_list (GtkWidget *widget)
@@ -1670,8 +1670,8 @@ _gtk_drag_dest_handle_event (GtkWidget *toplevel,
  * that case, they will have to implement a drag_motion handler that
  * passes the correct target list to this function.
  *
- * Return value: first target that the source offers and the dest can
- *     accept, or %GDK_NONE
+ * Return value: (transfer none): first target that the source offers
+ *     and the dest can accept, or %GDK_NONE
  **/
 GdkAtom
 gtk_drag_dest_find_target (GtkWidget      *widget,
@@ -2532,7 +2532,7 @@ gtk_drag_begin_internal (GtkWidget         *widget,
  * (remember to free the event with gdk_event_free() when you are done).  If you
  * can really not pass a real event, pass #NULL instead.
  * 
- * Return value: the context for this drag.
+ * Return value: (transfer none): the context for this drag.
  **/
 GdkDragContext *
 gtk_drag_begin (GtkWidget         *widget,
@@ -2645,7 +2645,7 @@ gtk_drag_source_unset (GtkWidget        *widget)
  * Gets the list of targets this widget can provide for
  * drag-and-drop.
  *
- * Return value: the #GtkTargetList, or %NULL if none
+ * Return value: (transfer none): the #GtkTargetList, or %NULL if none
  *
  * Since: 2.4
  **/
diff --git a/gtk/gtkiconfactory.c b/gtk/gtkiconfactory.c
index acfee7a1a1..3dfc8270ee 100644
--- a/gtk/gtkiconfactory.c
+++ b/gtk/gtkiconfactory.c
@@ -241,7 +241,7 @@ gtk_icon_factory_add (GtkIconFactory *factory,
  * widget that will display the icon, instead of using this
  * function directly, so that themes are taken into account.
  *
- * Return value: icon set of @stock_id.
+ * Return value: (transfer none): icon set of @stock_id.
  */
 GtkIconSet *
 gtk_icon_factory_lookup (GtkIconFactory *factory,
@@ -316,7 +316,7 @@ _gtk_icon_factory_ensure_default_icons (void)
  * using this function directly, so that themes are taken into
  * account.
  *
- * Return value: a #GtkIconSet, or %NULL
+ * Return value: (transfer none): a #GtkIconSet, or %NULL
  */
 GtkIconSet *
 gtk_icon_factory_lookup_default (const gchar *stock_id)
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 11e59124ef..9d555bc4af 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -1963,7 +1963,8 @@ gtk_label_set_attributes (GtkLabel         *label,
  * effective attributes for the label, use
  * pango_layout_get_attribute (gtk_label_get_layout (label)).
  *
- * Return value: the attribute list, or %NULL if none was set.
+ * Return value: (transfer none): the attribute list, or %NULL
+ *     if none was set.
  **/
 PangoAttrList *
 gtk_label_get_attributes (GtkLabel *label)
diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index 2f917b8290..a49c84949e 100644
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -2286,7 +2286,8 @@ gtk_invoke_input (gpointer	    data,
  * signal. The returned event must be freed with gdk_event_free().
  * If there is no current event, the function returns %NULL.
  * 
- * Return value: a copy of the current event, or %NULL if no current event.
+ * Return value: (transfer full): a copy of the current event, or %NULL if no
+ *     current event.
  **/
 GdkEvent*
 gtk_get_current_event (void)
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index c44cf8687d..baecd2560e 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -1229,6 +1229,14 @@ gtk_menu_attach_to_widget (GtkMenu	       *menu,
   g_object_notify (G_OBJECT (menu), "attach-widget");
 }
 
+/**
+ * gtk_menu_get_attach_widget:
+ * @menu: a #GtkMenu
+ *
+ * Returns the #GtkWidget that the menu is attached to.
+ *
+ * Returns: (transfer none): the #GtkWidget that the menu is attached to
+ */
 GtkWidget*
 gtk_menu_get_attach_widget (GtkMenu *menu)
 {
@@ -1712,6 +1720,17 @@ gtk_menu_popdown (GtkMenu *menu)
   menu_grab_transfer_window_destroy (menu);
 }
 
+/**
+ * gtk_menu_get_active:
+ * @menu: a #GtkMenu
+ *
+ * Returns the selected menu item from the menu.  This is used by the
+ * #GtkOptionMenu.
+ *
+ * Returns: (transfer none): the #GtkMenuItem that was last selected
+ *          in the menu.  If a selection has not yet been made, the
+ *          first menu item is selected.
+ */
 GtkWidget*
 gtk_menu_get_active (GtkMenu *menu)
 {
@@ -1788,6 +1807,15 @@ gtk_menu_set_accel_group (GtkMenu	*menu,
     }
 }
 
+/**
+ * gtk_menu_get_accel_group:
+ * @menu a #GtkMenu
+ *
+ * Gets the #GtkAccelGroup which holds global accelerators for the
+ * menu.  See gtk_menu_set_accel_group().
+ *
+ * Returns: (transfer none): the #GtkAccelGroup associated with the menu.
+ */
 GtkAccelGroup*
 gtk_menu_get_accel_group (GtkMenu *menu)
 {
diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c
index 7d89c1c151..b34230da3d 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -1005,7 +1005,8 @@ gtk_notebook_class_init (GtkNotebookClass *class)
    * The default handler uses the global window creation hook,
    * if one has been set with gtk_notebook_set_window_creation_hook().
    *
-   * Returns: a #GtkNotebook that @page should be added to, or %NULL.
+   * Returns: (transfer none): a #GtkNotebook that @page should be
+   *     added to, or %NULL.
    *
    * Since: 2.12
    */
diff --git a/gtk/gtkpagesetupunixdialog.c b/gtk/gtkpagesetupunixdialog.c
index c5f63bf708..7f86d246ab 100644
--- a/gtk/gtkpagesetupunixdialog.c
+++ b/gtk/gtkpagesetupunixdialog.c
@@ -1084,7 +1084,7 @@ gtk_page_setup_unix_dialog_set_page_setup (GtkPageSetupUnixDialog *dialog,
  * 
  * Gets the currently selected page setup from the dialog. 
  * 
- * Returns: the current page setup 
+ * Returns: (transfer none): the current page setup 
  *
  * Since: 2.10
  **/
@@ -1181,7 +1181,7 @@ gtk_page_setup_unix_dialog_set_print_settings (GtkPageSetupUnixDialog *dialog,
  * 
  * Gets the current print settings from the dialog.
  * 
- * Returns: the current print settings
+ * Returns: (transfer none): the current print settings
  *
  * Since: 2.10
  **/
diff --git a/gtk/gtkprintcontext.c b/gtk/gtkprintcontext.c
index d775bd7991..b07290227d 100644
--- a/gtk/gtkprintcontext.c
+++ b/gtk/gtkprintcontext.c
@@ -254,7 +254,7 @@ _gtk_print_context_set_page_setup (GtkPrintContext *context,
  * Obtains the cairo context that is associated with the
  * #GtkPrintContext.
  *
- * Return value: the cairo context of @context
+ * Return value: (transfer none): the cairo context of @context
  *
  * Since: 2.10
  */
diff --git a/gtk/gtkprinter.c b/gtk/gtkprinter.c
index ccc2b186ca..bb70c2b613 100644
--- a/gtk/gtkprinter.c
+++ b/gtk/gtkprinter.c
@@ -398,7 +398,7 @@ gtk_printer_new (const gchar     *name,
  * 
  * Returns the backend of the printer.
  * 
- * Return value: the backend of @printer
+ * Return value: (transfer none): the backend of @printer
  * 
  * Since: 2.10
  */
diff --git a/gtk/gtkprintjob.c b/gtk/gtkprintjob.c
index af76152718..647e8aadfa 100644
--- a/gtk/gtkprintjob.c
+++ b/gtk/gtkprintjob.c
@@ -311,7 +311,7 @@ gtk_print_job_new (const gchar      *title,
  * 
  * Gets the #GtkPrintSettings of the print job.
  * 
- * Return value: the settings of @job
+ * Return value: (transfer none): the settings of @job
  *
  * Since: 2.10
  */
@@ -329,7 +329,7 @@ gtk_print_job_get_settings (GtkPrintJob *job)
  * 
  * Gets the #GtkPrinter of the print job.
  * 
- * Return value: the printer of @job
+ * Return value: (transfer none): the printer of @job
  *
  * Since: 2.10
  */
@@ -446,7 +446,7 @@ gtk_print_job_set_source_file (GtkPrintJob *job,
  * Gets a cairo surface onto which the pages of
  * the print job should be rendered.
  * 
- * Return value: the cairo surface of @job
+ * Return value: (transfer none): the cairo surface of @job
  *
  * Since: 2.10
  **/
diff --git a/gtk/gtkprintoperation-unix.c b/gtk/gtkprintoperation-unix.c
index 45280361a3..e4f153797e 100644
--- a/gtk/gtkprintoperation-unix.c
+++ b/gtk/gtkprintoperation-unix.c
@@ -983,7 +983,7 @@ get_page_setup_dialog (GtkWindow        *parent,
  * setup dialog. See gtk_print_run_page_setup_dialog_async() if this is 
  * a problem.
  * 
- * Return value: a new #GtkPageSetup
+ * Return value: (transfer full): a new #GtkPageSetup
  *
  * Since: 2.10
  */
diff --git a/gtk/gtkprintoperation.c b/gtk/gtkprintoperation.c
index 7247b94f1b..aebf947f69 100644
--- a/gtk/gtkprintoperation.c
+++ b/gtk/gtkprintoperation.c
@@ -881,8 +881,8 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class)
    * signal is emitted on the operation. Then you can read out any 
    * information you need from the widgets.
    *
-   * Returns: A custom widget that gets embedded in the print dialog,
-   *          or %NULL
+   * Returns: (transfer none): A custom widget that gets embedded in
+   *          the print dialog, or %NULL
    *
    * Since: 2.10
    */
diff --git a/gtk/gtkprintunixdialog.c b/gtk/gtkprintunixdialog.c
index 6b8ea46ee4..51021b0baf 100644
--- a/gtk/gtkprintunixdialog.c
+++ b/gtk/gtkprintunixdialog.c
@@ -3860,7 +3860,7 @@ gtk_print_unix_dialog_new (const gchar *title,
  *
  * Gets the currently selected printer.
  *
- * Returns: the currently selected printer
+ * Returns: (transfer none): the currently selected printer
  *
  * Since: 2.10
  */
@@ -3909,7 +3909,7 @@ gtk_print_unix_dialog_set_page_setup (GtkPrintUnixDialog *dialog,
  *
  * Gets the page setup that is used by the #GtkPrintUnixDialog.
  *
- * Returns: the page setup of @dialog.
+ * Returns: (transfer none): the page setup of @dialog.
  *
  * Since: 2.10
  */
diff --git a/gtk/gtkradiobutton.c b/gtk/gtkradiobutton.c
index e29886b126..f81e39001a 100644
--- a/gtk/gtkradiobutton.c
+++ b/gtk/gtkradiobutton.c
@@ -285,7 +285,7 @@ gtk_radio_button_new (GSList *group)
  *
  * Creates a new #GtkRadioButton with a text label.
  *
- * Returns: (transfer full): a new radio button.
+ * Returns: a new radio button.
  */
 GtkWidget*
 gtk_radio_button_new_with_label (GSList      *group,
@@ -312,7 +312,7 @@ gtk_radio_button_new_with_label (GSList      *group,
  * gtk_label_new_with_mnemonic(), so underscores in @label indicate the 
  * mnemonic for the button.
  *
- * Returns: (transfer full): a new #GtkRadioButton
+ * Returns: a new #GtkRadioButton
  **/
 GtkWidget*
 gtk_radio_button_new_with_mnemonic (GSList      *group,
diff --git a/gtk/gtkrc.c b/gtk/gtkrc.c
index e60437c63e..4cea61d346 100644
--- a/gtk/gtkrc.c
+++ b/gtk/gtkrc.c
@@ -1935,7 +1935,7 @@ sort_and_dereference_sets (GSList *styles)
  * created styles, so a new style may not be
  * created.)
  * 
- * Returns: the resulting style. No refcount is added
+ * Returns: (transfer none): the resulting style. No refcount is added
  *   to the returned style, so if you want to save this
  *   style around, you should add a reference yourself.
  **/
diff --git a/gtk/gtkselection.c b/gtk/gtkselection.c
index 16be894b12..26f88885d9 100644
--- a/gtk/gtkselection.c
+++ b/gtk/gtkselection.c
@@ -193,7 +193,7 @@ static const char gtk_selection_handler_key[] = "gtk-selection-handlers";
  * 
  * Creates a new #GtkTargetList from an array of #GtkTargetEntry.
  * 
- * Return value: the new #GtkTargetList.
+ * Return value: (transfer full): the new #GtkTargetList.
  **/
 GtkTargetList *
 gtk_target_list_new (const GtkTargetEntry *targets,
@@ -1118,7 +1118,7 @@ gtk_selection_convert (GtkWidget *widget,
  *
  * Retrieves the selection #GdkAtom of the selection data.
  *
- * Returns: the selection #GdkAtom of the selection data.
+ * Returns: (transfer none): the selection #GdkAtom of the selection data.
  *
  * Since: 2.16
  **/
@@ -1136,7 +1136,7 @@ gtk_selection_data_get_selection (GtkSelectionData *selection_data)
  *
  * Retrieves the target of the selection.
  *
- * Returns:  the target of the selection.
+ * Returns: (transfer none): the target of the selection.
  *
  * Since: 2.14
  **/
@@ -1154,7 +1154,7 @@ gtk_selection_data_get_target (GtkSelectionData *selection_data)
  *
  * Retrieves the data type of the selection.
  *
- * Returns:  the data type of the selection.
+ * Returns: (transfer none): the data type of the selection.
  *
  * Since: 2.14
  **/
diff --git a/gtk/gtkstyle.c b/gtk/gtkstyle.c
index 8654d1ffec..0914d61165 100644
--- a/gtk/gtkstyle.c
+++ b/gtk/gtkstyle.c
@@ -877,7 +877,7 @@ gtk_style_realize (GtkStyle    *style,
  * and the default icon factory, returning an icon set if found,
  * otherwise %NULL.
  *
- * Return value: icon set of @stock_id
+ * Return value: (transfer none): icon set of @stock_id
  */
 GtkIconSet*
 gtk_style_lookup_icon_set (GtkStyle   *style,
diff --git a/gtk/gtktestutils.c b/gtk/gtktestutils.c
index 8c0bb55544..b49b2620cf 100644
--- a/gtk/gtktestutils.c
+++ b/gtk/gtktestutils.c
@@ -220,7 +220,7 @@ gtk_test_spin_button_click (GtkSpinButton  *spinner,
  * so this function is genrally only useful in test programs with
  * predetermined locales, see gtk_test_init() for more details.
  *
- * Returns: a GtkLabel widget if any is found.
+ * Returns: (transfer none): a GtkLabel widget if any is found.
  *
  * Since: 2.14
  **/
@@ -316,7 +316,7 @@ widget_geo_cmp (gconstpointer a,
  * widget, relative to another labeling widget. Such as finding a
  * button or text entry widget, given it's corresponding label widget.
  *
- * Returns: a widget of type @widget_type if any is found.
+ * Returns: (transfer none): a widget of type @widget_type if any is found.
  *
  * Since: 2.14
  **/
@@ -358,7 +358,7 @@ gtk_test_find_sibling (GtkWidget *base_widget,
  * gtk_test_widget_click() for possible caveats involving the search of
  * such widgets and synthesizing widget events.
  *
- * Returns: a valid widget if any is found or %NULL.
+ * Returns: (transfer none): a valid widget if any is found or %NULL.
  *
  * Since: 2.14
  **/
@@ -598,7 +598,7 @@ gtk_test_display_button_window (const gchar *window_title,
  * The window will quit any running gtk_main()-loop when destroyed, and it
  * will automatically be destroyed upon test function teardown.
  *
- * Returns: a widget pointer to the newly created GtkWindow.
+ * Returns: (transfer none): a widget pointer to the newly created GtkWindow.
  *
  * Since: 2.14
  **/
diff --git a/gtk/gtktextbuffer.c b/gtk/gtktextbuffer.c
index 99a574f458..fa3e3ec05e 100644
--- a/gtk/gtktextbuffer.c
+++ b/gtk/gtktextbuffer.c
@@ -4167,7 +4167,7 @@ gtk_text_buffer_get_target_list (GtkTextBuffer   *buffer,
  * using gtk_target_list_add_rich_text_targets() and
  * gtk_target_list_add_text_targets().
  *
- * Return value: the #GtkTargetList
+ * Return value: (transfer none): the #GtkTargetList
  *
  * Since: 2.10
  **/
@@ -4199,7 +4199,7 @@ gtk_text_buffer_get_copy_target_list (GtkTextBuffer *buffer)
  * using gtk_target_list_add_rich_text_targets() and
  * gtk_target_list_add_text_targets().
  *
- * Return value: the #GtkTargetList
+ * Return value: (transfer none): the #GtkTargetList
  *
  * Since: 2.10
  **/
diff --git a/gtk/gtktextbufferrichtext.c b/gtk/gtktextbufferrichtext.c
index 16501f7681..057cacc1e5 100644
--- a/gtk/gtktextbufferrichtext.c
+++ b/gtk/gtktextbufferrichtext.c
@@ -67,8 +67,8 @@ static GQuark    deserialize_quark (void);
  * This function registers a rich text serialization @function along with
  * its @mime_type with the passed @buffer.
  *
- * Return value: the #GdkAtom that corresponds to the newly registered
- *               format's mime-type.
+ * Return value: (transfer none): the #GdkAtom that corresponds to the
+ *               newly registered format's mime-type.
  *
  * Since: 2.10
  **/
@@ -124,8 +124,8 @@ gtk_text_buffer_register_serialize_format (GtkTextBuffer              *buffer,
  * identifier != %NULL here, since the %NULL tagset requires the
  * receiving buffer to deal with with pasting of arbitrary tags.
  *
- * Return value: the #GdkAtom that corresponds to the newly registered
- *               format's mime-type.
+ * Return value: (transfer none): the #GdkAtom that corresponds to the
+ *               newly registered format's mime-type.
  *
  * Since: 2.10
  **/
@@ -165,8 +165,8 @@ gtk_text_buffer_register_serialize_tagset (GtkTextBuffer *buffer,
  * This function registers a rich text deserialization @function along with
  * its @mime_type with the passed @buffer.
  *
- * Return value: the #GdkAtom that corresponds to the newly registered
- *               format's mime-type.
+ * Return value: (transfer none): the #GdkAtom that corresponds to the
+ *               newly registered format's mime-type.
  *
  * Since: 2.10
  **/
@@ -208,8 +208,8 @@ gtk_text_buffer_register_deserialize_format (GtkTextBuffer                *buffe
  * format with the passed @buffer. See
  * gtk_text_buffer_register_serialize_tagset() for details.
  *
- * Return value: the #GdkAtom that corresponds to the newly registered
- *               format's mime-type.
+ * Return value: (transfer none): the #GdkAtom that corresponds to the
+ *               newly registered format's mime-type.
  *
  * Since: 2.10
  **/
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 2425392e97..e3b330062d 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -9822,8 +9822,8 @@ gtk_widget_class_install_style_property (GtkWidgetClass *klass,
  * gtk_widget_class_find_style_property:
  * @klass: a #GtkWidgetClass
  * @property_name: the name of the style property to find
- * @returns: (allow-none): the #GParamSpec of the style property or %NULL if @class has no
- *   style property with that name.
+ * @returns: (transfer none): the #GParamSpec of the style property or
+ *   %NULL if @class has no style property with that name.
  *
  * Finds a style property of a widget class by name.
  *
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index b94d089380..2966fe8367 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -7790,7 +7790,7 @@ gtk_window_has_group (GtkWindow *window)
  * Gets the current grab widget of the given group,
  * see gtk_grab_add().
  *
- * Returns: the current grab widget of the group
+ * Returns: (transfer none): the current grab widget of the group
  *
  * Since: 2.22
  */