From a3f1596069ae966ffa785e85327a868e041560c4 Mon Sep 17 00:00:00 2001
From: Rico Tzschichholz <ricotz@ubuntu.com>
Date: Thu, 22 Sep 2016 13:56:47 +0200
Subject: [PATCH] Add some missing (nullable) annotations

https://bugzilla.gnome.org/show_bug.cgi?id=771826
---
 gdk/gdkdisplay.c                  |  6 +++---
 gdk/gdkdnd.c                      |  2 +-
 gdk/gdkglcontext.c                |  8 ++++----
 gdk/gdkkeys.c                     |  4 ++--
 gtk/deprecated/gtknumerableicon.c |  8 ++++----
 gtk/deprecated/gtkstatusicon.c    | 12 ++++++------
 gtk/deprecated/gtkstyle.c         |  2 +-
 gtk/deprecated/gtkthemingengine.c |  4 ++--
 gtk/gtkactionable.c               |  2 +-
 gtk/gtkcellrenderer.c             |  6 +++---
 gtk/gtkcsscustomproperty.c        |  2 +-
 gtk/gtkdragdest.c                 |  2 +-
 gtk/gtkicontheme.c                |  2 +-
 gtk/gtkrecentmanager.c            |  8 ++++----
 gtk/gtkstylecontext.c             |  4 ++--
 gtk/gtkstyleproperty.c            |  2 +-
 gtk/gtkstyleprovider.c            |  4 ++--
 gtk/gtkwidgetpath.c               |  4 ++--
 gtk/gtkwindow.c                   |  2 +-
 19 files changed, 42 insertions(+), 42 deletions(-)

diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index f771564e5b..ed0e65f956 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -1792,7 +1792,7 @@ gdk_display_supports_clipboard_persistence (GdkDisplay *display)
  * @display:          a #GdkDisplay
  * @clipboard_window: a #GdkWindow belonging to the clipboard owner
  * @time_:            a timestamp
- * @targets:          (array length=n_targets): an array of targets
+ * @targets:          (array length=n_targets) (nullable): an array of targets
  *                    that should be saved, or %NULL
  *                    if all available targets should be saved.
  * @n_targets:        length of the @targets array
@@ -2570,7 +2570,7 @@ get_fallback_monitor (GdkDisplay *display)
  *
  * Gets a monitor associated with this display.
  *
- * Returns: (transfer none): the #GdkMonitor, or %NULL if
+ * Returns: (nullable) (transfer none): the #GdkMonitor, or %NULL if
  *    @monitor_num is not a valid monitor number
  * Since: 3.22
  */
@@ -2597,7 +2597,7 @@ gdk_display_get_monitor (GdkDisplay *display,
  * manager to place the windows, specialized desktop applications
  * such as panels should place themselves on the primary monitor.
  *
- * Returns: (transfer none): the primary monitor, or %NULL if no primary
+ * Returns: (nullable) (transfer none): the primary monitor, or %NULL if no primary
  *     monitor is configured by the user
  * Since: 3.22
  */
diff --git a/gdk/gdkdnd.c b/gdk/gdkdnd.c
index 163a705ee0..d0629cfb7e 100644
--- a/gdk/gdkdnd.c
+++ b/gdk/gdkdnd.c
@@ -592,7 +592,7 @@ gdk_drag_get_selection (GdkDragContext *context)
  * The window is owned by @context and will be destroyed when
  * the drag operation is over.
  *
- * Returns: (transfer none): the drag window, or %NULL
+ * Returns: (nullable) (transfer none): the drag window, or %NULL
  *
  * Since: 3.20
  */
diff --git a/gdk/gdkglcontext.c b/gdk/gdkglcontext.c
index 40addbccae..bf6e45f5a2 100644
--- a/gdk/gdkglcontext.c
+++ b/gdk/gdkglcontext.c
@@ -873,7 +873,7 @@ gdk_gl_context_make_current (GdkGLContext *context)
  *
  * Retrieves the #GdkDisplay the @context is created for
  *
- * Returns: (transfer none): a #GdkDisplay or %NULL
+ * Returns: (nullable) (transfer none): a #GdkDisplay or %NULL
  *
  * Since: 3.16
  */
@@ -893,7 +893,7 @@ gdk_gl_context_get_display (GdkGLContext *context)
  *
  * Retrieves the #GdkWindow used by the @context.
  *
- * Returns: (transfer none): a #GdkWindow or %NULL
+ * Returns: (nullable) (transfer none): a #GdkWindow or %NULL
  *
  * Since: 3.16
  */
@@ -913,7 +913,7 @@ gdk_gl_context_get_window (GdkGLContext *context)
  *
  * Retrieves the #GdkGLContext that this @context share data with.
  *
- * Returns: (transfer none): a #GdkGLContext or %NULL
+ * Returns: (nullable) (transfer none): a #GdkGLContext or %NULL
  *
  * Since: 3.16
  */
@@ -985,7 +985,7 @@ gdk_gl_context_clear_current (void)
  *
  * Retrieves the current #GdkGLContext.
  *
- * Returns: (transfer none): the current #GdkGLContext, or %NULL
+ * Returns: (nullable) (transfer none): the current #GdkGLContext, or %NULL
  *
  * Since: 3.16
  */
diff --git a/gdk/gdkkeys.c b/gdk/gdkkeys.c
index d7f76a9513..467e063ad5 100644
--- a/gdk/gdkkeys.c
+++ b/gdk/gdkkeys.c
@@ -437,9 +437,9 @@ gdk_keymap_get_entries_for_keyval (GdkKeymap     *keymap,
  * gdk_keymap_get_entries_for_keycode:
  * @keymap: a #GdkKeymap
  * @hardware_keycode: a keycode
- * @keys: (out) (array length=n_entries) (transfer full): return
+ * @keys: (out) (array length=n_entries) (transfer full) (optional): return
  *     location for array of #GdkKeymapKey, or %NULL
- * @keyvals: (out) (array length=n_entries) (transfer full): return
+ * @keyvals: (out) (array length=n_entries) (transfer full) (optional): return
  *     location for array of keyvals, or %NULL
  * @n_entries: length of @keys and @keyvals
  *
diff --git a/gtk/deprecated/gtknumerableicon.c b/gtk/deprecated/gtknumerableicon.c
index 7f63f4da31..7527c5e977 100644
--- a/gtk/deprecated/gtknumerableicon.c
+++ b/gtk/deprecated/gtknumerableicon.c
@@ -713,7 +713,7 @@ _gtk_numerable_icon_set_background_icon_size (GtkNumerableIcon *self,
  *
  * Returns the currently displayed label of the icon, or %NULL.
  *
- * Returns: the currently displayed label
+ * Returns: (nullable): the currently displayed label
  *
  * Since: 3.0
  *
@@ -825,7 +825,7 @@ gtk_numerable_icon_set_count (GtkNumerableIcon *self,
  * Returns the #GtkStyleContext used by the icon for theming,
  * or %NULL if there’s none.
  *
- * Returns: (transfer none): a #GtkStyleContext, or %NULL.
+ * Returns: (nullable) (transfer none): a #GtkStyleContext, or %NULL.
  *     This object is internal to GTK+ and should not be unreffed.
  *     Use g_object_ref() if you want to keep it around
  *
@@ -919,7 +919,7 @@ gtk_numerable_icon_set_background_gicon (GtkNumerableIcon *self,
  * %NULL if there’s none. The caller of this function does not own
  * a reference to the returned #GIcon.
  *
- * Returns: (transfer none): a #GIcon, or %NULL
+ * Returns: (nullable) (transfer none): a #GIcon, or %NULL
  *
  * Since: 3.0
  *
@@ -992,7 +992,7 @@ gtk_numerable_icon_set_background_icon_name (GtkNumerableIcon *self,
  * Returns the icon name used as the base background image,
  * or %NULL if there’s none.
  *
- * Returns: an icon name, or %NULL
+ * Returns: (nullable): an icon name, or %NULL
  *
  * Since: 3.0
  *
diff --git a/gtk/deprecated/gtkstatusicon.c b/gtk/deprecated/gtkstatusicon.c
index 7df11cdec1..b33a296751 100644
--- a/gtk/deprecated/gtkstatusicon.c
+++ b/gtk/deprecated/gtkstatusicon.c
@@ -1919,7 +1919,7 @@ gtk_status_icon_get_storage_type (GtkStatusIcon *status_icon)
  * The caller of this function does not own a reference to the
  * returned pixbuf.
  * 
- * Returns: (transfer none): the displayed pixbuf,
+ * Returns: (nullable) (transfer none): the displayed pixbuf,
  *     or %NULL if the image is empty.
  *
  * Since: 2.10
@@ -1948,7 +1948,7 @@ gtk_status_icon_get_pixbuf (GtkStatusIcon *status_icon)
  * The returned string is owned by the #GtkStatusIcon and should not
  * be freed or modified.
  * 
- * Returns: stock id of the displayed stock icon,
+ * Returns: (nullable): stock id of the displayed stock icon,
  *   or %NULL if the image is empty.
  *
  * Since: 2.10
@@ -1977,7 +1977,7 @@ gtk_status_icon_get_stock (GtkStatusIcon *status_icon)
  * The returned string is owned by the #GtkStatusIcon and should not
  * be freed or modified.
  * 
- * Returns: name of the displayed icon, or %NULL if the image is empty.
+ * Returns: (nullable): name of the displayed icon, or %NULL if the image is empty.
  *
  * Since: 2.10
  *
@@ -2007,7 +2007,7 @@ gtk_status_icon_get_icon_name (GtkStatusIcon *status_icon)
  *
  * If this function fails, @icon is left unchanged;
  *
- * Returns: (transfer none): the displayed icon, or %NULL if the image is empty
+ * Returns: (nullable) (transfer none): the displayed icon, or %NULL if the image is empty
  *
  * Since: 2.14
  *
@@ -2582,7 +2582,7 @@ gtk_status_icon_set_tooltip_text (GtkStatusIcon *status_icon,
  *
  * Gets the contents of the tooltip for @status_icon.
  *
- * Returns: the tooltip text, or %NULL. You should free the
+ * Returns: (nullable): the tooltip text, or %NULL. You should free the
  *   returned string with g_free() when done.
  *
  * Since: 2.16
@@ -2672,7 +2672,7 @@ gtk_status_icon_set_tooltip_markup (GtkStatusIcon *status_icon,
  *
  * Gets the contents of the tooltip for @status_icon.
  *
- * Returns: the tooltip text, or %NULL. You should free the
+ * Returns: (nullable): the tooltip text, or %NULL. You should free the
  *   returned string with g_free() when done.
  *
  * Since: 2.16
diff --git a/gtk/deprecated/gtkstyle.c b/gtk/deprecated/gtkstyle.c
index 291e5c2306..9477578fef 100644
--- a/gtk/deprecated/gtkstyle.c
+++ b/gtk/deprecated/gtkstyle.c
@@ -4752,7 +4752,7 @@ gtk_widget_class_path (GtkWidget *widget,
  * the application and should not be modified. The pixbuf should be
  * freed after use with g_object_unref().
  *
- * Returns: (transfer full): a new pixbuf, or %NULL if the
+ * Returns: (nullable) (transfer full): a new pixbuf, or %NULL if the
  *     stock ID wasn’t known
  *
  * Deprecated: 3.0: Use gtk_widget_render_icon_pixbuf() instead.
diff --git a/gtk/deprecated/gtkthemingengine.c b/gtk/deprecated/gtkthemingengine.c
index e26e8078e6..24dbc79ad3 100644
--- a/gtk/deprecated/gtkthemingengine.c
+++ b/gtk/deprecated/gtkthemingengine.c
@@ -951,7 +951,7 @@ gtk_theming_module_init (GtkThemingModule *module)
  * Loads and initializes a theming engine module from the
  * standard directories.
  *
- * Returns: (transfer none): A theming engine, or %NULL if
+ * Returns: (nullable) (transfer none): A theming engine, or %NULL if
  * the engine @name doesn’t exist.
  *
  * Deprecated: 3.14
@@ -1004,7 +1004,7 @@ gtk_theming_engine_load (const gchar *name)
  *
  * Returns the #GdkScreen to which @engine currently rendering to.
  *
- * Returns: (transfer none): a #GdkScreen, or %NULL.
+ * Returns: (nullable) (transfer none): a #GdkScreen, or %NULL.
  *
  * Deprecated: 3.14
  **/
diff --git a/gtk/gtkactionable.c b/gtk/gtkactionable.c
index c28fae2556..e12936a834 100644
--- a/gtk/gtkactionable.c
+++ b/gtk/gtkactionable.c
@@ -102,7 +102,7 @@ gtk_actionable_get_action_name (GtkActionable *actionable)
 /**
  * gtk_actionable_set_action_name:
  * @actionable: a #GtkActionable widget
- * @action_name: an action name, or %NULL
+ * @action_name: (nullable): an action name, or %NULL
  *
  * Specifies the name of the action with which this widget should be
  * associated.  If @action_name is %NULL then the widget will be
diff --git a/gtk/gtkcellrenderer.c b/gtk/gtkcellrenderer.c
index 58969d4b10..163b8962dd 100644
--- a/gtk/gtkcellrenderer.c
+++ b/gtk/gtkcellrenderer.c
@@ -883,7 +883,7 @@ gtk_cell_renderer_activate (GtkCellRenderer      *cell,
 /**
  * gtk_cell_renderer_start_editing:
  * @cell: a #GtkCellRenderer
- * @event: a #GdkEvent
+ * @event: (nullable): a #GdkEvent
  * @widget: widget that received the event
  * @path: widget-dependent string representation of the event location;
  *    e.g. for #GtkTreeView, a string representation of #GtkTreePath
@@ -1792,8 +1792,8 @@ gtk_cell_renderer_get_aligned_area (GtkCellRenderer      *cell,
 
 /**
  * gtk_cell_renderer_get_state:
- * @cell: a #GtkCellRenderer, or %NULL
- * @widget: a #GtkWidget, or %NULL
+ * @cell: (nullable): a #GtkCellRenderer, or %NULL
+ * @widget: (nullable): a #GtkWidget, or %NULL
  * @cell_state: cell renderer state
  *
  * Translates the cell renderer state to #GtkStateFlags,
diff --git a/gtk/gtkcsscustomproperty.c b/gtk/gtkcsscustomproperty.c
index f210ad397b..59205dd2dd 100644
--- a/gtk/gtkcsscustomproperty.c
+++ b/gtk/gtkcsscustomproperty.c
@@ -209,7 +209,7 @@ gtk_theming_engine_register_property (const gchar            *name_space,
 
 /**
  * gtk_style_properties_register_property: (skip)
- * @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/gtkdragdest.c b/gtk/gtkdragdest.c
index 9a679e7801..8f4261b4c8 100644
--- a/gtk/gtkdragdest.c
+++ b/gtk/gtkdragdest.c
@@ -250,7 +250,7 @@ gtk_drag_dest_unset (GtkWidget *widget)
  * Returns the list of targets this widget can accept from
  * drag-and-drop.
  *
- * Returns: (transfer none): the #GtkTargetList, or %NULL if none
+ * Returns: (nullable) (transfer none): the #GtkTargetList, or %NULL if none
  */
 GtkTargetList *
 gtk_drag_dest_get_target_list (GtkWidget *widget)
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index 8ebf652d4f..63b6f238a7 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -3662,7 +3662,7 @@ gtk_icon_info_get_filename (GtkIconInfo *icon_info)
  * built in icon images, you must pass the %GTK_ICON_LOOKUP_USE_BUILTIN
  * to gtk_icon_theme_lookup_icon().
  *
- * Returns: (transfer none): the built-in image pixbuf, or %NULL.
+ * Returns: (nullable) (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/gtkrecentmanager.c b/gtk/gtkrecentmanager.c
index 2f01e3de8d..1157eec3ea 100644
--- a/gtk/gtkrecentmanager.c
+++ b/gtk/gtkrecentmanager.c
@@ -1968,7 +1968,7 @@ get_icon_fallback (const gchar *icon_name,
  *
  * Retrieves the icon of size @size associated to the resource MIME type.
  *
- * Returns: (transfer full): a #GdkPixbuf containing the icon,
+ * Returns: (nullable) (transfer full): a #GdkPixbuf containing the icon,
  *     or %NULL. Use g_object_unref() when finished using the icon.
  *
  * Since: 2.10
@@ -2003,7 +2003,7 @@ gtk_recent_info_get_icon (GtkRecentInfo *info,
  *
  * Retrieves the icon associated to the resource MIME type.
  *
- * Returns: (transfer full): a #GIcon containing the icon, or %NULL.
+ * Returns: (nullable) (transfer full): a #GIcon containing the icon, or %NULL.
  *   Use g_object_unref() when finished using the icon
  *
  * Since: 2.22
@@ -2266,7 +2266,7 @@ gtk_recent_info_get_short_name (GtkRecentInfo *info)
  * is local, it returns a local path; if the resource is not local,
  * it returns the UTF-8 encoded content of gtk_recent_info_get_uri().
  *
- * Returns: a newly allocated UTF-8 string containing the
+ * Returns: (nullable): a newly allocated UTF-8 string containing the
  *   resource’s URI or %NULL. Use g_free() when done using it.
  *
  * Since: 2.10
@@ -2427,7 +2427,7 @@ gtk_recent_info_has_group (GtkRecentInfo *info,
  *
  * Creates a #GAppInfo for the specified #GtkRecentInfo
  *
- * Returns: (transfer full): the newly created #GAppInfo, or %NULL.
+ * Returns: (nullable) (transfer full): the newly created #GAppInfo, or %NULL.
  *   In case of error, @error will be set either with a
  *   %GTK_RECENT_MANAGER_ERROR or a %G_IO_ERROR
  */
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 03a16aac49..aa80b7312c 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -939,7 +939,7 @@ gtk_style_context_set_id (GtkStyleContext *context,
  *
  * Returns the CSS ID used when obtaining style information.
  *
- * Returns: the ID or %NULL if no ID is set.
+ * Returns: (nullable): the ID or %NULL if no ID is set.
  **/
 const char *
 gtk_style_context_get_id (GtkStyleContext *context)
@@ -1930,7 +1930,7 @@ gtk_style_context_get_style (GtkStyleContext *context,
  * the default icon factory, returning an icon set if found, otherwise
  * %NULL.
  *
- * Returns: (transfer none): The looked  up %GtkIconSet, or %NULL
+ * Returns: (nullable) (transfer none): The looked up %GtkIconSet, or %NULL
  *
  * Deprecated: 3.10: Use gtk_icon_theme_lookup_icon() instead.
  **/
diff --git a/gtk/gtkstyleproperty.c b/gtk/gtkstyleproperty.c
index 9639ae44c0..e79849bd28 100644
--- a/gtk/gtkstyleproperty.c
+++ b/gtk/gtkstyleproperty.c
@@ -260,7 +260,7 @@ _gtk_style_property_add_alias (const gchar *name,
  * Looks up the CSS property with the given @name. If no such
  * property exists, %NULL is returned.
  *
- * Returns: (transfer none): The property or %NULL if no
+ * Returns: (nullable) (transfer none): The property or %NULL if no
  *     property with the given name exists.
  **/
 GtkStyleProperty *
diff --git a/gtk/gtkstyleprovider.c b/gtk/gtkstyleprovider.c
index fab975a173..d522b58439 100644
--- a/gtk/gtkstyleprovider.c
+++ b/gtk/gtkstyleprovider.c
@@ -62,7 +62,7 @@ gtk_style_provider_iface_init (gpointer g_iface)
  * Returns the style settings affecting a widget defined by @path, or %NULL if
  * @provider doesn’t contemplate styling @path.
  *
- * Returns: (transfer full): a #GtkStyleProperties containing the
+ * Returns: (nullable) (transfer full): a #GtkStyleProperties containing the
  * style settings affecting @path
  *
  * Since: 3.0
@@ -132,7 +132,7 @@ gtk_style_provider_get_style_property (GtkStyleProvider *provider,
  * Returns the #GtkIconFactory defined to be in use for @path, or %NULL if none
  * is defined.
  *
- * Returns: (transfer none): The icon factory to use for @path, or %NULL
+ * Returns: (nullable) (transfer none): The icon factory to use for @path, or %NULL
  *
  * Since: 3.0
  *
diff --git a/gtk/gtkwidgetpath.c b/gtk/gtkwidgetpath.c
index 2a5ad19871..ae4d0576df 100644
--- a/gtk/gtkwidgetpath.c
+++ b/gtk/gtkwidgetpath.c
@@ -523,7 +523,7 @@ gtk_widget_path_iter_get_sibling_index (const GtkWidgetPath *path,
  * Returns the object name that is at position @pos in the widget
  * hierarchy defined in @path.
  *
- * Returns: the name or %NULL
+ * Returns: (nullable): the name or %NULL
  *
  * Since: 3.20
  **/
@@ -713,7 +713,7 @@ gtk_widget_path_iter_set_state (GtkWidgetPath *path,
  * the position @pos in the widget hierarchy defined by
  * @path
  *
- * Returns: The widget name, or %NULL if none was set.
+ * Returns: (nullable): The widget name, or %NULL if none was set.
  **/
 const gchar *
 gtk_widget_path_iter_get_name (const GtkWidgetPath *path,
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 9808475f73..14a11c376e 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -12368,7 +12368,7 @@ _gtk_window_get_popover_position (GtkWindow             *window,
  * Returns the conceptual parent of this popover, the real
  * parent will always be @window.
  *
- * Returns: The conceptual parent widget, or %NULL.
+ * Returns: (nullable): The conceptual parent widget, or %NULL.
  **/
 GtkWidget *
 _gtk_window_get_popover_parent (GtkWindow *window,