introspection: add many missing Returns: (nullable) annotations

https://bugzilla.gnome.org/show_bug.cgi?id=729752

10 files changed, 43 insertions, 37 deletions

diff --git a/atk/atkaction.c b/atk/atkaction.c
index 50f21a2..bc12cb2 100755
--- a/atk/atkaction.c
+++ b/atk/atkaction.c
@@ -126,8 +126,8 @@ atk_action_get_n_actions  (AtkAction *obj)
  *
  * Returns a description of the specified action of the object.
  *
- * Returns: a description string, or %NULL if @action does not
- * implement this interface.
+ * Returns: (nullable): a description string, or %NULL if @action does
+ * not implement this interface.
  **/
 const gchar*
 atk_action_get_description (AtkAction *obj,
@@ -165,8 +165,8 @@ atk_action_get_description (AtkAction *obj,
  * i.e. the result of some actions via atk_action_do_action() may be
  * NIL.
  *
- * Returns: a name string, or %NULL if @action does not implement this
- * interface.
+ * Returns: (nullable): a name string, or %NULL if @action does not
+ * implement this interface.
  **/
 const gchar*
 atk_action_get_name (AtkAction *obj,
@@ -191,8 +191,8 @@ atk_action_get_name (AtkAction *obj,
  *
  * Returns the localized name of the specified action of the object.
  *
- * Returns: a name string, or %NULL if @action does not implement this
- * interface.
+ * Returns: (nullable): a name string, or %NULL if @action does not
+ * implement this interface.
  **/
 const gchar*
 atk_action_get_localized_name (AtkAction *obj,
@@ -238,8 +238,8 @@ atk_action_get_localized_name (AtkAction *obj,
  * for the German locale. If, hypothetically, this menu item lacked a mnemonic,
  * it would be represented by ";;Ctrl+N" and ";;Strg+N" respectively.
  *
- * Returns: the keybinding which can be used to activate this action,
- * or %NULL if there is no keybinding for this action.
+ * Returns: (nullable): the keybinding which can be used to activate
+ * this action, or %NULL if there is no keybinding for this action.
  *
  **/
 const gchar*
diff --git a/atk/atkcomponent.c b/atk/atkcomponent.c
index 561c22b..fc63c9d 100755
--- a/atk/atkcomponent.c
+++ b/atk/atkcomponent.c
@@ -228,7 +228,8 @@ atk_component_contains (AtkComponent    *component,
  * Gets a reference to the accessible child, if one exists, at the
  * coordinate point specified by @x and @y.
  *
- * Returns: (transfer full): a reference to the accessible child, if one exists
+ * Returns: (nullable) (transfer full): a reference to the accessible
+ * child, if one exists
  **/
 AtkObject*
 atk_component_ref_accessible_at_point (AtkComponent    *component,
diff --git a/atk/atkdocument.c b/atk/atkdocument.c
index 81bad4d..dc56eae 100755
--- a/atk/atkdocument.c
+++ b/atk/atkdocument.c
@@ -301,9 +301,9 @@ atk_document_get_attributes (AtkDocument *document)
  *
  * Since: 1.12
  *
- * Returns: a string value associated with the named attribute for this
- *    document, or NULL if a value for #attribute_name has not been specified
- *    for this document.
+ * Returns: (nullable): a string value associated with the named
+ *    attribute for this document, or NULL if a value for
+ *    #attribute_name has not been specified for this document.
  */
 const gchar *
 atk_document_get_attribute_value (AtkDocument *document, 
diff --git a/atk/atkimage.c b/atk/atkimage.c
index 9dfcfef..9d8a58f 100755
--- a/atk/atkimage.c
+++ b/atk/atkimage.c
@@ -212,9 +212,9 @@ atk_image_get_image_position (AtkImage *image,
  *
  * Since ATK 1.12
  *
- * Returns: a string corresponding to the POSIX LC_MESSAGES locale
- * used by the image description, or NULL if the image does not
- * specify a locale.
+ * Returns: (nullable): a string corresponding to the POSIX
+ * LC_MESSAGES locale used by the image description, or %NULL if the
+ * image does not specify a locale.
  *
  */
 const gchar*
diff --git a/atk/atkselection.c b/atk/atkselection.c
index f086c28..d4bd836 100755
--- a/atk/atkselection.c
+++ b/atk/atkselection.c
@@ -160,8 +160,9 @@ atk_selection_clear_selection (AtkSelection *obj)
  * use type checking/interface checking macros or the
  * atk_get_accessible_value() convenience method.
  *
- * Returns: (transfer full): an #AtkObject representing the selected
- * accessible , or %NULL if @selection does not implement this interface.
+ * Returns: (nullable) (transfer full): an #AtkObject representing the
+ * selected accessible, or %NULL if @selection does not implement this
+ * interface.
  **/
 AtkObject*
 atk_selection_ref_selection (AtkSelection *obj,
diff --git a/atk/atkstateset.c b/atk/atkstateset.c
index 3dc8d5e..1740d05 100755
--- a/atk/atkstateset.c
+++ b/atk/atkstateset.c
@@ -301,8 +301,8 @@ atk_state_set_and_sets (AtkStateSet  *set,
  *
  * Constructs the union of the two sets.
  *
- * Returns: (transfer full): a new #AtkStateSet which is the union of the two
- * sets, returning %NULL is empty.
+ * Returns: (nullable) (transfer full): a new #AtkStateSet which is
+ * the union of the two sets, returning %NULL is empty.
  **/
 AtkStateSet*
 atk_state_set_or_sets (AtkStateSet  *set,
diff --git a/atk/atkstreamablecontent.c b/atk/atkstreamablecontent.c
index 92643d3..571ca2b 100755
--- a/atk/atkstreamablecontent.c
+++ b/atk/atkstreamablecontent.c
@@ -158,8 +158,8 @@ atk_streamable_content_get_stream (AtkStreamableContent *streamable,
  * Note that it is possible for get_uri to return NULL but for
  * get_stream to work nonetheless, since not all GIOChannels connect to URIs.
  *
- * Returns:  Returns a string representing a URI, or NULL if no corresponding URI
- * can be constructed.
+ * Returns: (nullable): Returns a string representing a URI, or %NULL
+ * if no corresponding URI can be constructed.
  *
  * Since: 1.12
  **/
diff --git a/atk/atktable.c b/atk/atktable.c
index d28591d..ba5d7c1 100755
--- a/atk/atktable.c
+++ b/atk/atktable.c
@@ -357,8 +357,8 @@ atk_table_get_column_at_index (AtkTable *table,
  *
  * Gets the caption for the @table.
  *
- * Returns: (transfer none): a AtkObject* representing the table caption, or
- * %NULL if value does not implement this interface.
+ * Returns: (nullable) (transfer none): a AtkObject* representing the
+ * table caption, or %NULL if value does not implement this interface.
  **/
 AtkObject*
 atk_table_get_caption (AtkTable *table)
@@ -461,8 +461,9 @@ atk_table_get_column_extent_at (AtkTable *table,
  *
  * Gets the column header of a specified column in an accessible table.
  *
- * Returns: (transfer none): a AtkObject* representing the specified column
- * header, or %NULL if value does not implement this interface.
+ * Returns: (nullable) (transfer none): a AtkObject* representing the
+ * specified column header, or %NULL if value does not implement this
+ * interface.
  **/
 AtkObject*
 atk_table_get_column_header (AtkTable *table, gint column)
@@ -510,8 +511,8 @@ atk_table_get_n_rows (AtkTable *table)
  *
  * Gets the description text of the specified row in the table
  *
- * Returns: a gchar* representing the row description, or %NULL
- * if value does not implement this interface.
+ * Returns: (nullable) a gchar* representing the row description, or
+ * %NULL if value does not implement this interface.
  **/
 const gchar*
 atk_table_get_row_description (AtkTable *table,
@@ -565,8 +566,9 @@ atk_table_get_row_extent_at (AtkTable *table,
  *
  * Gets the row header of a specified row in an accessible table.
  *
- * Returns: (transfer none): a AtkObject* representing the specified row
- * header, or %NULL if value does not implement this interface.
+ * Returns: (nullable) (transfer none): a AtkObject* representing the
+ * specified row header, or %NULL if value does not implement this
+ * interface.
  **/
 AtkObject*
 atk_table_get_row_header (AtkTable *table, gint row)
diff --git a/atk/atktext.c b/atk/atktext.c
index 590d2fc..e4d421d 100755
--- a/atk/atktext.c
+++ b/atk/atktext.c
@@ -584,9 +584,10 @@ atk_text_get_text_before_offset (AtkText          *text,
  *
  * Since: 2.10
  *
- * Returns: a newly allocated string containing the text at the @offset bounded
- *   by the specified @granularity. Use g_free() to free the returned string.
- *   Returns %NULL if the offset is invalid or no implementation is available.
+ * Returns: (nullable): a newly allocated string containing the text
+ *   at the @offset bounded by the specified @granularity. Use
+ *   g_free() to free the returned string.  Returns %NULL if the
+ *   offset is invalid or no implementation is available.
  **/
 gchar* atk_text_get_string_at_offset (AtkText *text,
                                       gint offset,
@@ -1263,8 +1264,9 @@ atk_text_attribute_for_name (const gchar *name)
  *
  * Gets the value for the index of the #AtkTextAttribute
  *
- * Returns: a string containing the value; this string should not be freed;
- * NULL is returned if there are no values maintained for the attr value. 
+ * Returns: (nullable): a string containing the value; this string
+ * should not be freed; %NULL is returned if there are no values
+ * maintained for the attr value.
  **/
 const gchar*
 atk_text_attribute_get_value (AtkTextAttribute attr,
diff --git a/atk/atkvalue.c b/atk/atkvalue.c
index 03fc02d..839601b 100755
--- a/atk/atkvalue.c
+++ b/atk/atkvalue.c
@@ -555,9 +555,9 @@ atk_value_get_value_and_text (AtkValue *obj,
  *
  * Gets the range of this object.
  *
- * Returns: (transfer full): a newly allocated #AtkRange that
- * represents the minimum, maximum and descriptor (if available) of
- * @obj. NULL if that range is not defined.
+ * Returns: (nullable) (transfer full): a newly allocated #AtkRange
+ * that represents the minimum, maximum and descriptor (if available)
+ * of @obj. NULL if that range is not defined.
  *
  * Since: 2.12
  **/