[gtk+] gtk: port many nullability annotation fixes from Vala bindings

From: Evan Nemerson <evann src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk+] gtk: port many nullability annotation fixes from Vala bindings
Date: Fri, 30 May 2014 20:30:14 +0000 (UTC)
commit 54ec42f035d7b3d47968eecce30659a23e7b3e48
Author: Evan Nemerson <evan nemerson com>
Date:   Mon May 26 09:13:02 2014 -0700

    gtk: port many nullability annotation fixes from Vala bindings
    
    https://bugzilla.gnome.org/show_bug.cgi?id=730745

 gtk/deprecated/gtkactiongroup.c |    4 +-
 gtk/deprecated/gtkhscale.c      |    3 +-
 gtk/deprecated/gtkrc.c          |   11 ++++----
 gtk/deprecated/gtkstyle.c       |   12 ++++----
 gtk/gtkbuilder.c                |    2 +-
 gtk/gtkclipboard.c              |   21 +++++++--------
 gtk/gtkclipboard.h              |   11 ++++----
 gtk/gtkcombobox.c               |    2 +-
 gtk/gtkcontainer.c              |    5 ++-
 gtk/gtkcsscustomproperty.c      |    2 +-
 gtk/gtkcsssection.c             |    2 +-
 gtk/gtkentry.c                  |   13 +++++----
 gtk/gtkfilechooser.c            |   12 ++++----
 gtk/gtkframe.c                  |    5 ++-
 gtk/gtkicontheme.c              |   51 +++++++++++++++++++++-----------------
 gtk/gtklistbox.c                |    2 +-
 gtk/gtkmenuitem.c               |    2 +-
 gtk/gtkrecentfilter.h           |   15 ++++++-----
 gtk/gtkselection.c              |    9 ++++---
 gtk/gtktreestore.c              |    2 +-
 gtk/gtktreeview.c               |    3 +-
 gtk/gtkwidget.c                 |    4 +-
 22 files changed, 103 insertions(+), 90 deletions(-)
---
diff --git a/gtk/deprecated/gtkactiongroup.c b/gtk/deprecated/gtkactiongroup.c
index 737dbf1..a08d18c 100644
--- a/gtk/deprecated/gtkactiongroup.c
+++ b/gtk/deprecated/gtkactiongroup.c
@@ -1154,7 +1154,7 @@ shared_data_unref (gpointer data)
  * @entries: (array length=n_entries): an array of action descriptions
  * @n_entries: the number of entries
  * @user_data: data to pass to the action callbacks
- * @destroy: destroy notification callback for @user_data
+ * @destroy: (nullable): destroy notification callback for @user_data
  *
  * This variant of gtk_action_group_add_actions() adds a #GDestroyNotify
  * callback for @user_data. 
@@ -1265,7 +1265,7 @@ gtk_action_group_add_toggle_actions (GtkActionGroup             *action_group,
  * @entries: (array length=n_entries): an array of toggle action descriptions
  * @n_entries: the number of entries
  * @user_data: data to pass to the action callbacks
- * @destroy: destroy notification callback for @user_data
+ * @destroy: (nullable): destroy notification callback for @user_data
  *
  * This variant of gtk_action_group_add_toggle_actions() adds a 
  * #GDestroyNotify callback for @user_data. 
diff --git a/gtk/deprecated/gtkhscale.c b/gtk/deprecated/gtkhscale.c
index 5572874..f5db3c9 100644
--- a/gtk/deprecated/gtkhscale.c
+++ b/gtk/deprecated/gtkhscale.c
@@ -68,7 +68,8 @@ gtk_hscale_init (GtkHScale *hscale)
 
 /**
  * gtk_hscale_new:
- * @adjustment: the #GtkAdjustment which sets the range of the scale.
+ * @adjustment: (nullable): the #GtkAdjustment which sets the range of
+ * the scale.
  *
  * Creates a new #GtkHScale.
  *
diff --git a/gtk/deprecated/gtkrc.c b/gtk/deprecated/gtkrc.c
index 17f47be..1e8efbb 100644
--- a/gtk/deprecated/gtkrc.c
+++ b/gtk/deprecated/gtkrc.c
@@ -1409,11 +1409,12 @@ gtk_rc_get_style (GtkWidget *widget)
  *                             G_OBJECT_TYPE (widget));
  * ]|
  *
- * Returns: (transfer none): A style created by matching with the
- *     supplied paths, or %NULL if nothing matching was specified and the
- *     default style should be used. The returned value is owned by GTK+
- *     as part of an internal cache, so you must call g_object_ref() on
- *     the returned value if you want to keep a reference to it.
+ * Returns: (nullable) (transfer none): A style created by matching
+ *     with the supplied paths, or %NULL if nothing matching was
+ *     specified and the default style should be used. The returned
+ *     value is owned by GTK+ as part of an internal cache, so you
+ *     must call g_object_ref() on the returned value if you want to
+ *     keep a reference to it.
  *
  * Deprecated:3.0: Use #GtkStyleContext instead
  **/
diff --git a/gtk/deprecated/gtkstyle.c b/gtk/deprecated/gtkstyle.c
index 5c1ef7a..55ad766 100644
--- a/gtk/deprecated/gtkstyle.c
+++ b/gtk/deprecated/gtkstyle.c
@@ -4498,12 +4498,12 @@ gtk_widget_modify_base (GtkWidget      *widget,
 /**
  * gtk_widget_modify_cursor:
  * @widget: a #GtkWidget
- * @primary: the color to use for primary cursor (does not need to be
- *     allocated), or %NULL to undo the effect of previous calls to
- *     of gtk_widget_modify_cursor().
- * @secondary: the color to use for secondary cursor (does not need to be
- *     allocated), or %NULL to undo the effect of previous calls to
- *     of gtk_widget_modify_cursor().
+ * @primary: (nullable): the color to use for primary cursor (does not
+ *     need to be allocated), or %NULL to undo the effect of previous
+ *     calls to of gtk_widget_modify_cursor().
+ * @secondary: (nullable): the color to use for secondary cursor (does
+ *     not need to be allocated), or %NULL to undo the effect of
+ *     previous calls to of gtk_widget_modify_cursor().
  *
  * Sets the cursor color to use in a widget, overriding the #GtkWidget
  * cursor-color and secondary-cursor-color
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index 60927df..d7cadc4 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -1643,7 +1643,7 @@ gtk_builder_connect_signals (GtkBuilder *builder,
  * @object: object to connect a signal to
  * @signal_name: name of the signal
  * @handler_name: name of the handler
- * @connect_object: a #GObject, if non-%NULL, use g_signal_connect_object()
+ * @connect_object: (nullable): a #GObject, if non-%NULL, use g_signal_connect_object()
  * @flags: #GConnectFlags to use
  * @user_data: user data
  *
diff --git a/gtk/gtkclipboard.c b/gtk/gtkclipboard.c
index b867a3f..6826346 100644
--- a/gtk/gtkclipboard.c
+++ b/gtk/gtkclipboard.c
@@ -1385,7 +1385,7 @@ clipboard_received_func (GtkClipboard     *clipboard,
  * This function waits for the data to be received using the main 
  * loop, so events, timeouts, etc, may be dispatched during the wait.
  * 
- * Returns: a newly-allocated #GtkSelectionData object or %NULL
+ * Returns: (nullable): a newly-allocated #GtkSelectionData object or %NULL
  *               if retrieving the given target failed. If non-%NULL,
  *               this value must be freed with gtk_selection_data_free() 
  *               when you are finished with it.
@@ -1438,7 +1438,7 @@ clipboard_text_received_func (GtkClipboard *clipboard,
  * the data to be received using the main loop, so events,
  * timeouts, etc, may be dispatched during the wait.
  * 
- * Returns: a newly-allocated UTF-8 string which must
+ * Returns: (nullable): a newly-allocated UTF-8 string which must
  *               be freed with g_free(), or %NULL if retrieving
  *               the selection data failed. (This could happen
  *               for various reasons, in particular if the
@@ -1497,7 +1497,7 @@ clipboard_rich_text_received_func (GtkClipboard *clipboard,
  * waits for the data to be received using the main loop, so events,
  * timeouts, etc, may be dispatched during the wait.
  *
- * Returns: (array length=length) (transfer full): a
+ * Returns: (nullable) (array length=length) (transfer full): a
  *               newly-allocated binary block of data which must be
  *               freed with g_free(), or %NULL if retrieving the
  *               selection data failed. (This could happen for various
@@ -1564,7 +1564,7 @@ clipboard_image_received_func (GtkClipboard *clipboard,
  * the data to be received using the main loop, so events,
  * timeouts, etc, may be dispatched during the wait.
  *
- * Returns: (transfer full): a newly-allocated #GdkPixbuf
+ * Returns: (nullable) (transfer full): a newly-allocated #GdkPixbuf
  *     object which must be disposed with g_object_unref(), or
  *     %NULL if retrieving the selection data failed. (This could
  *     happen for various reasons, in particular if the clipboard
@@ -1618,13 +1618,12 @@ clipboard_uris_received_func (GtkClipboard *clipboard,
  * for the data to be received using the main loop, so events,
  * timeouts, etc, may be dispatched during the wait.
  *
- * Returns: (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
- *               the clipboard could not be converted into URI form.)
+ * Returns: (nullable) (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
+ *     the clipboard could not be converted into URI form.)
  *
  * Since: 2.14
  **/
diff --git a/gtk/gtkclipboard.h b/gtk/gtkclipboard.h
index 13f7f7b..d65b2bd 100644
--- a/gtk/gtkclipboard.h
+++ b/gtk/gtkclipboard.h
@@ -51,9 +51,10 @@ typedef void (* GtkClipboardReceivedFunc)         (GtkClipboard     *clipboard,
 /**
  * GtkClipboardTextReceivedFunc:
  * @clipboard: the #GtkClipboard
- * @text: the text received, as a UTF-8 encoded string, or %NULL
- *   if retrieving the data failed.
- * @data: the @user_data supplied to gtk_clipboard_request_text().
+ * @text: (nullable): the text received, as a UTF-8 encoded string, or
+ *   %NULL if retrieving the data failed.
+ * @data: (closure): the @user_data supplied to
+ *   gtk_clipboard_request_text().
  *
  * A function to be called when the results of gtk_clipboard_request_text()
  * are received, or when the request fails.
@@ -120,8 +121,8 @@ typedef void (* GtkClipboardURIReceivedFunc)      (GtkClipboard     *clipboard,
 /**
  * GtkClipboardTargetsReceivedFunc:
  * @clipboard: the #GtkClipboard
- * @atoms: the supported targets, as array of #GdkAtom, or %NULL
- *   if retrieving the data failed.
+ * @atoms: (nullable) (array length=n_atoms): the supported targets,
+ *   as array of #GdkAtom, or %NULL if retrieving the data failed.
  * @n_atoms: the length of the @atoms array.
  * @data: (closure): the @user_data supplied to
  *   gtk_clipboard_request_targets().
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index e31f521..2404886 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -5807,7 +5807,7 @@ gtk_combo_box_get_id_column (GtkComboBox *combo_box)
  * no row is active, or if the active row has a %NULL ID value, then %NULL
  * is returned.
  *
- * Returns: the ID of the active row, or %NULL
+ * Returns: (nullable): the ID of the active row, or %NULL
  *
  * Since: 3.0
  **/
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 30aa6b2..b67e380 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -1311,8 +1311,9 @@ gtk_container_class_install_child_property (GtkContainerClass *cclass,
  *
  * Finds a child property of a container class by name.
  *
- * Returns: (transfer none): the #GParamSpec of the child property
- *     or %NULL if @class has no child property with that name.
+ * Returns: (nullable) (transfer none): the #GParamSpec of the child
+ *     property or %NULL if @class has no child property with that
+ *     name.
  */
 GParamSpec*
 gtk_container_class_find_child_property (GObjectClass *cclass,
diff --git a/gtk/gtkcsscustomproperty.c b/gtk/gtkcsscustomproperty.c
index 0fecddb..21dd0f1 100644
--- a/gtk/gtkcsscustomproperty.c
+++ b/gtk/gtkcsscustomproperty.c
@@ -177,7 +177,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
 /**
  * gtk_theming_engine_register_property: (skip)
  * @name_space: namespace for the property name
- * @parse_func: parsing function to use, or %NULL
+ * @parse_func: (nullable): parsing function to use, or %NULL
  * @pspec: the #GParamSpec for the new property
  *
  * Registers a property so it can be used in the CSS file format,
diff --git a/gtk/gtkcsssection.c b/gtk/gtkcsssection.c
index 9246d2d..fce7038 100644
--- a/gtk/gtkcsssection.c
+++ b/gtk/gtkcsssection.c
@@ -174,7 +174,7 @@ gtk_css_section_get_section_type (const GtkCssSection *section)
  * #GTK_CSS_SECTION_IMPORT if it was loaded with an import rule from
  * a different file.
  *
- * Returns: the parent section or %NULL if none
+ * Returns: (nullable) (transfer none): the parent section or %NULL if none
  *
  * Since: 3.2
  **/
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index 75ad8ee..0e52a12 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -8131,7 +8131,8 @@ 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.
  *
- * Returns: (transfer none): the entry’s #GtkBorder, or %NULL if none was set.
+ * Returns: (nullable) (transfer none): the entry’s #GtkBorder, or
+ *   %NULL if none was set.
  *
  * Since: 2.10
  *
@@ -9153,8 +9154,8 @@ ensure_has_tooltip (GtkEntry *entry)
  * Gets the contents of the tooltip on the icon at the specified 
  * position in @entry.
  * 
- * Returns: the tooltip text, or %NULL. Free the returned string
- *     with g_free() when done.
+ * Returns: (nullable): the tooltip text, or %NULL. Free the returned
+ *     string with g_free() when done.
  * 
  * Since: 2.16
  */
@@ -9240,8 +9241,8 @@ gtk_entry_set_icon_tooltip_text (GtkEntry             *entry,
  * Gets the contents of the tooltip on the icon at the specified 
  * position in @entry.
  * 
- * Returns: the tooltip text, or %NULL. Free the returned string
- *     with g_free() when done.
+ * Returns: (nullable): the tooltip text, or %NULL. Free the returned
+ *     string with g_free() when done.
  * 
  * Since: 2.16
  */
@@ -10849,7 +10850,7 @@ gtk_entry_set_tabs (GtkEntry      *entry,
  * Gets the tabstops that were set on the entry using gtk_entry_set_tabs(), if
  * any.
  *
- * Returns: (transfer none): the tabstops, or %NULL if none was set.
+ * Returns: (nullable) (transfer none): the tabstops, or %NULL if none was set.
  *
  * Since: 3.10
  */
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index 049712c..2c23ea9 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -2046,9 +2046,9 @@ 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().
  *
- * Returns: (element-type filename) (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
+ * Returns: (nullable) (element-type filename) (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().
  *
  * Since: 2.4
@@ -2144,9 +2144,9 @@ 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().
  *
- * Returns: (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().
+ * Returns: (nullable) (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().
  *
  * Since: 2.4
  **/
diff --git a/gtk/gtkframe.c b/gtk/gtkframe.c
index 4cd31a3..41550a9 100644
--- a/gtk/gtkframe.c
+++ b/gtk/gtkframe.c
@@ -448,7 +448,7 @@ gtk_frame_get_label (GtkFrame *frame)
 /**
  * gtk_frame_set_label_widget:
  * @frame: a #GtkFrame
- * @label_widget: the new label widget
+ * @label_widget: (nullable): the new label widget
  * 
  * Sets the label widget for the frame. This is the widget that
  * will appear embedded in the top edge of the frame as a
@@ -501,7 +501,8 @@ gtk_frame_set_label_widget (GtkFrame  *frame,
  * Retrieves the label widget for the frame. See
  * gtk_frame_set_label_widget().
  *
- * Returns: (transfer none): the label widget, or %NULL if there is none.
+ * Returns: (nullable) (transfer none): the label widget, or %NULL if
+ * there is none.
  **/
 GtkWidget *
 gtk_frame_get_label_widget (GtkFrame *frame)
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index 9965dc0..8f2cc73 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -1957,8 +1957,9 @@ choose_icon (GtkIconTheme       *icon_theme,
  * gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon()
  * combines these two steps if all you need is the pixbuf.)
  * 
- * Returns: (transfer full): a #GtkIconInfo object containing information
- * about the icon, or %NULL if the icon wasn’t found.
+ * Returns: (nullable) (transfer full): a #GtkIconInfo object
+ * containing information about the icon, or %NULL if the icon wasn’t
+ * found.
  *
  * Since: 2.4
  */
@@ -1994,8 +1995,9 @@ gtk_icon_theme_lookup_icon (GtkIconTheme       *icon_theme,
  * gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon() combines
  * these two steps if all you need is the pixbuf.)
  *
- * Returns: (transfer full): a #GtkIconInfo object containing
- * information about the icon, or %NULL if the icon wasn’t found.
+ * Returns: (nullable) (transfer full): a #GtkIconInfo object
+ * containing information about the icon, or %NULL if the icon wasn’t
+ * found.
  *
  * Since: 3.10
  */
@@ -2098,8 +2100,9 @@ gtk_icon_theme_lookup_icon_for_scale (GtkIconTheme       *icon_theme,
  * tries them all in the given order before falling back to 
  * inherited icon themes.
  * 
- * Returns: (transfer full): a #GtkIconInfo object containing information
- * about the icon, or %NULL if the icon wasn’t found.
+ * Returns: (nullable) (transfer full): a #GtkIconInfo object
+ * containing information about the icon, or %NULL if the icon wasn’t
+ * found.
  *
  * Since: 2.12
  */
@@ -2136,8 +2139,9 @@ gtk_icon_theme_choose_icon (GtkIconTheme       *icon_theme,
  * tries them all in the given order before falling back to 
  * inherited icon themes.
  * 
- * Returns: (transfer full): a #GtkIconInfo object containing information
- * about the icon, or %NULL if the icon wasn’t found.
+ * Returns: (nullable) (transfer full): a #GtkIconInfo object
+ * containing information about the icon, or %NULL if the icon wasn’t
+ * found.
  *
  * Since: 3.10
  */
@@ -2188,8 +2192,8 @@ gtk_icon_theme_error_quark (void)
  * returned by this function. Otherwise GTK+ may need to keep the old
  * icon theme loaded, which would be a waste of memory.
  *
- * Returns: (transfer full): the rendered icon; this may be a
- *     newly created icon or a new reference to an internal icon, so
+ * Returns: (nullable) (transfer full): the rendered icon; this may be
+ *     a newly created icon or a new reference to an internal icon, so
  *     you must not modify the icon. Use g_object_unref() to release
  *     your reference to the icon. %NULL if the icon isn’t found.
  *
@@ -2237,8 +2241,8 @@ gtk_icon_theme_load_icon (GtkIconTheme         *icon_theme,
  * returned by this function. Otherwise GTK+ may need to keep the old
  * icon theme loaded, which would be a waste of memory.
  *
- * Returns: (transfer full): the rendered icon; this may be a
- *     newly created icon or a new reference to an internal icon, so
+ * Returns: (nullable) (transfer full): the rendered icon; this may be
+ *     a newly created icon or a new reference to an internal icon, so
  *     you must not modify the icon. Use g_object_unref() to release
  *     your reference to the icon. %NULL if the icon isn’t found.
  *
@@ -2299,10 +2303,11 @@ gtk_icon_theme_load_icon_for_scale (GtkIconTheme        *icon_theme,
  * update the icon. This is usually done by connecting to the
  * GtkWidget::style-set signal.
  *
- * Returns: (transfer full): the rendered icon; this may be a
- *     newly created icon or a new reference to an internal icon, so
- *     you must not modify the icon. Use cairo_surface_destroy() to release
- *     your reference to the icon. %NULL if the icon isn’t found.
+ * Returns: (nullable) (transfer full): the rendered icon; this may be
+ *     a newly created icon or a new reference to an internal icon, so
+ *     you must not modify the icon. Use cairo_surface_destroy() to
+ *     release your reference to the icon. %NULL if the icon isn’t
+ *     found.
  *
  * Since: 3.10
  **/
@@ -2638,7 +2643,7 @@ gtk_icon_theme_list_contexts (GtkIconTheme *icon_theme)
  * current theme (for instance, to use when presenting
  * a list of themes to the user.)
  * 
- * Returns: the name of an example icon or %NULL.
+ * Returns: (nullable): the name of an example icon or %NULL.
  *  Free with g_free().
  *
  * Since: 2.4
@@ -5360,9 +5365,9 @@ find_builtin_icon (const gchar *icon_name,
  * The icon can then be rendered into a pixbuf using
  * gtk_icon_info_load_icon().
  *
- * Returns: (transfer full): a #GtkIconInfo containing 
- *     information about the icon, or %NULL if the icon 
- *     wasn’t found. Unref with g_object_unref()
+ * Returns: (nullable) (transfer full): a #GtkIconInfo containing
+ *     information about the icon, or %NULL if the icon wasn’t
+ *     found. Unref with g_object_unref()
  *
  * Since: 2.14
  */
@@ -5390,9 +5395,9 @@ gtk_icon_theme_lookup_by_gicon (GtkIconTheme       *icon_theme,
  * The icon can then be rendered into a pixbuf using
  * gtk_icon_info_load_icon().
  *
- * Returns: (transfer full): a #GtkIconInfo containing
- *     information about the icon, or %NULL if the icon
- *     wasn’t found. Unref with g_object_unref()
+ * Returns: (nullable) (transfer full): a #GtkIconInfo containing
+ *     information about the icon, or %NULL if the icon wasn’t
+ *     found. Unref with g_object_unref()
  *
  * Since: 3.10
  */
diff --git a/gtk/gtklistbox.c b/gtk/gtklistbox.c
index bfe622f..6bab1b5 100644
--- a/gtk/gtklistbox.c
+++ b/gtk/gtklistbox.c
@@ -390,7 +390,7 @@ gtk_list_box_class_init (GtkListBoxClass *klass)
   /**
    * GtkListBox::row-selected:
    * @box: the #GtkListBox
-   * @row: the selected row
+   * @row: (nullable): the selected row
    *
    * The ::row-selected signal is emitted when a new row is selected, or
    * (with a %NULL @row) when the selection is cleared.
diff --git a/gtk/gtkmenuitem.c b/gtk/gtkmenuitem.c
index f715c6a..e097fec 100644
--- a/gtk/gtkmenuitem.c
+++ b/gtk/gtkmenuitem.c
@@ -1311,7 +1311,7 @@ gtk_menu_item_set_use_action_appearance (GtkMenuItem *menu_item,
 /**
  * gtk_menu_item_set_submenu:
  * @menu_item: a #GtkMenuItem
- * @submenu: (allow-none): the submenu, or %NULL
+ * @submenu: (allow-none) (type Gtk.Menu): the submenu, or %NULL
  *
  * Sets or replaces the menu item’s submenu, or removes it when a %NULL
  * submenu is passed.
diff --git a/gtk/gtkrecentfilter.h b/gtk/gtkrecentfilter.h
index 32d6bf1..2c428df 100644
--- a/gtk/gtkrecentfilter.h
+++ b/gtk/gtkrecentfilter.h
@@ -77,13 +77,14 @@ typedef gboolean (*GtkRecentFilterFunc) (const GtkRecentFilterInfo *filter_info,
 /**
  * GtkRecentFilterInfo:
  * @contains: #GtkRecentFilterFlags to indicate which fields are set.
- * @uri: The URI of the file being tested.
- * @display_name: The string that will be used to display the file in
- *    the recent chooser.
- * @mime_type: MIME type of the file.
- * @applications: The list of applications that have registered the
- *    file.
- * @groups: The groups to which the file belongs to.
+ * @uri: (nullable): The URI of the file being tested.
+ * @display_name: (nullable): The string that will be used to display
+ *    the file in the recent chooser.
+ * @mime_type: (nullable): MIME type of the file.
+ * @applications: (nullable) (array zero-terminated=1): The list of
+ *    applications that have registered the file.
+ * @groups: (nullable) (array zero-terminated=1): The groups to which
+ *    the file belongs to.
  * @age: The number of days elapsed since the file has been
  *    registered.
  *
diff --git a/gtk/gtkselection.c b/gtk/gtkselection.c
index e066521..17f0365 100644
--- a/gtk/gtkselection.c
+++ b/gtk/gtkselection.c
@@ -1714,10 +1714,11 @@ gtk_selection_data_set_pixbuf (GtkSelectionData *selection_data,
  * 
  * Gets the contents of the selection data as a #GdkPixbuf.
  * 
- * Returns: (transfer full): if the selection data contained a recognized
- *   image type and it could be converted to a #GdkPixbuf, a 
- *   newly allocated pixbuf is returned, otherwise %NULL.
- *   If the result is non-%NULL it must be freed with g_object_unref().
+ * Returns: (nullable) (transfer full): if the selection data
+ *   contained a recognized image type and it could be converted to a
+ *   #GdkPixbuf, a newly allocated pixbuf is returned, otherwise
+ *   %NULL.  If the result is non-%NULL it must be freed with
+ *   g_object_unref().
  *
  * Since: 2.6
  **/
diff --git a/gtk/gtktreestore.c b/gtk/gtktreestore.c
index ba9c6b3..db3a3ff 100644
--- a/gtk/gtktreestore.c
+++ b/gtk/gtktreestore.c
@@ -2249,7 +2249,7 @@ gtk_tree_store_reorder_func (gconstpointer a,
 /**
  * gtk_tree_store_reorder: (skip)
  * @tree_store: A #GtkTreeStore
- * @parent: A #GtkTreeIter, or %NULL
+ * @parent: (nullable): A #GtkTreeIter, or %NULL
  * @new_order: (array): an array of integers mapping the new position of each child
  *      to its old position before the re-ordering,
  *      i.e. @new_order`[newpos] = oldpos`.
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index fa90787..4862535 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -11263,7 +11263,8 @@ gtk_tree_view_new_with_model (GtkTreeModel *model)
  * Returns the model the #GtkTreeView is based on.  Returns %NULL if the
  * model is unset.
  *
- * Returns: (transfer none): A #GtkTreeModel, or %NULL if none is currently being used.
+ * Returns: (transfer none) (nullable): A #GtkTreeModel, or %NULL if
+ * none is currently being used.
  **/
 GtkTreeModel *
 gtk_tree_view_get_model (GtkTreeView *tree_view)
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 15f3010..9397ff1 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -7865,7 +7865,7 @@ gtk_widget_reparent (GtkWidget *widget,
  * gtk_widget_intersect:
  * @widget: a #GtkWidget
  * @area: a rectangle
- * @intersection: rectangle to store intersection of @widget and @area
+ * @intersection: (nullable): rectangle to store intersection of @widget and @area
  *
  * Computes the intersection of a @widget’s area and @area, storing
  * the intersection in @intersection, and returns %TRUE if there was
@@ -10254,7 +10254,7 @@ gtk_widget_create_pango_context (GtkWidget *widget)
 /**
  * gtk_widget_create_pango_layout:
  * @widget: a #GtkWidget
- * @text: text to set on the layout (can be %NULL)
+ * @text: (nullable): text to set on the layout (can be %NULL)
  *
  * Creates a new #PangoLayout with the appropriate font map,
  * font description, and base direction for drawing text for
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]