[glib: 1/2] gsettings: Add various missing (nullable) or (not nullable) annotations

From: Philip Withnall <pwithnall src gnome org>
To: commits-list gnome org
Cc:
Subject: [glib: 1/2] gsettings: Add various missing (nullable) or (not nullable) annotations
Date: Tue, 21 Sep 2021 10:39:38 +0000 (UTC)

commit 452afce22162a87e1a5abd4dd14af56de19361bf
Author: Luke Yelavich <themuso themuso com>
Date:   Tue Sep 7 18:47:11 2021 +1000

    gsettings: Add various missing (nullable) or (not nullable) annotations
    
    Also added (transfer full) or (transfer none) annotations while I was at it.
    
    This is the result of checking each `Returns:` line in these files. I’ve
    only considered nullability and transferability, and not other (potentially
    missing or incorrect) annotations.
    
    Helps: #2227

 gio/gsettings.c        | 30 +++++++++++++++---------------
 gio/gsettingsbackend.c |  7 ++++---
 gio/gsettingsschema.c  | 42 +++++++++++++++++++++---------------------
 3 files changed, 40 insertions(+), 39 deletions(-)
---
diff --git a/gio/gsettings.c b/gio/gsettings.c
index f7d39c77e..c189a2e62 100644
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -972,7 +972,7 @@ g_settings_class_init (GSettingsClass *class)
  * call to g_settings_new().  The new #GSettings will hold a reference
  * on the context.  See g_main_context_push_thread_default().
  *
- * Returns: a new #GSettings object
+ * Returns: (not nullable) (transfer full): a new #GSettings object
  *
  * Since: 2.26
  */
@@ -1020,7 +1020,7 @@ path_is_valid (const gchar *path)
  * begins and ends with '/' and does not contain two consecutive '/'
  * characters.
  *
- * Returns: a new #GSettings object
+ * Returns: (not nullable) (transfer full): a new #GSettings object
  *
  * Since: 2.26
  */
@@ -1051,7 +1051,7 @@ g_settings_new_with_path (const gchar *schema_id,
  * the system to get a settings object that modifies the system default
  * settings instead of the settings for this user.
  *
- * Returns: a new #GSettings object
+ * Returns: (not nullable) (transfer full): a new #GSettings object
  *
  * Since: 2.26
  */
@@ -1080,7 +1080,7 @@ g_settings_new_with_backend (const gchar      *schema_id,
  * This is a mix of g_settings_new_with_backend() and
  * g_settings_new_with_path().
  *
- * Returns: a new #GSettings object
+ * Returns: (not nullable) (transfer full): a new #GSettings object
  *
  * Since: 2.26
  */
@@ -1130,7 +1130,7 @@ g_settings_new_with_backend_and_path (const gchar      *schema_id,
  * @path is non-%NULL and not equal to the path that the schema does
  * have.
  *
- * Returns: a new #GSettings object
+ * Returns: (not nullable) (transfer full): a new #GSettings object
  *
  * Since: 2.32
  */
@@ -1207,7 +1207,7 @@ g_settings_read_from_backend (GSettings          *settings,
  * It is a programmer error to give a @key that isn't contained in the
  * schema for @settings.
  *
- * Returns: a new #GVariant
+ * Returns: (not nullable) (transfer full): a new #GVariant
  *
  * Since: 2.26
  */
@@ -1727,7 +1727,7 @@ g_settings_set (GSettings   *settings,
  * what is returned by this function.  %NULL is valid; it is returned
  * just as any other value would be.
  *
- * Returns: (transfer full): the result, which may be %NULL
+ * Returns: (nullable) (transfer full): the result, which may be %NULL
  **/
 gpointer
 g_settings_get_mapped (GSettings           *settings,
@@ -1794,7 +1794,7 @@ g_settings_get_mapped (GSettings           *settings,
  * It is a programmer error to give a @key that isn't specified as
  * having a string type in the schema for @settings.
  *
- * Returns: a newly-allocated string
+ * Returns: (not nullable) (transfer full): a newly-allocated string
  *
  * Since: 2.26
  */
@@ -2188,7 +2188,7 @@ g_settings_set_boolean (GSettings  *settings,
  * It is a programmer error to give a @key that isn't specified as
  * having an array of strings type in the schema for @settings.
  *
- * Returns: (array zero-terminated=1) (transfer full): a
+ * Returns: (array zero-terminated=1) (not nullable) (transfer full): a
  * newly-allocated, %NULL-terminated array of strings, the value that
  * is stored at @key in @settings.
  *
@@ -2426,7 +2426,7 @@ g_settings_is_writable (GSettings   *settings,
  * The schema for the child settings object must have been declared
  * in the schema of @settings using a <child> element.
  *
- * Returns: (transfer full): a 'child' settings object
+ * Returns: (not nullable) (transfer full): a 'child' settings object
  *
  * Since: 2.26
  */
@@ -2469,8 +2469,8 @@ g_settings_get_child (GSettings   *settings,
  * You should free the return value with g_strfreev() when you are done
  * with it.
  *
- * Returns: (transfer full) (element-type utf8): a list of the keys on
- *    @settings, in no defined order
+ * Returns: (not nullable) (transfer full) (element-type utf8): a list
+ *    of the keys on @settings, in no defined order
  * Deprecated: 2.46: Use g_settings_schema_list_keys() instead.
  */
 gchar **
@@ -2495,8 +2495,8 @@ g_settings_list_keys (GSettings *settings)
  * You should free the return value with g_strfreev() when you are done
  * with it.
  *
- * Returns: (transfer full) (element-type utf8): a list of the children on
- *    @settings, in no defined order
+ * Returns: (not nullable) (transfer full) (element-type utf8): a list of the children
+ *    on @settings, in no defined order
  */
 gchar **
 g_settings_list_children (GSettings *settings)
@@ -3380,7 +3380,7 @@ g_settings_action_enabled_changed (GSettings   *settings,
  * activations take the new value for the key (which must have the
  * correct type).
  *
- * Returns: (transfer full): a new #GAction
+ * Returns: (not nullable) (transfer full): a new #GAction
  *
  * Since: 2.32
  **/
diff --git a/gio/gsettingsbackend.c b/gio/gsettingsbackend.c
index b124bc7ec..56409f59e 100644
--- a/gio/gsettingsbackend.c
+++ b/gio/gsettingsbackend.c
@@ -703,7 +703,7 @@ g_settings_backend_changed_tree (GSettingsBackend *backend,
  * backend (ie: the one that the backend would contain if
  * g_settings_reset() were called).
  *
- * Returns: the value that was read, or %NULL
+ * Returns: (nullable) (transfer full): the value that was read, or %NULL
  */
 GVariant *
 g_settings_backend_read (GSettingsBackend   *backend,
@@ -741,7 +741,7 @@ g_settings_backend_read (GSettingsBackend   *backend,
  * value for themselves, then this will return %NULL (even if the
  * sysadmin has provided a default value).
  *
- * Returns: the value that was read, or %NULL
+ * Returns: (nullable) (transfer full): the value that was read, or %NULL
  */
 GVariant *
 g_settings_backend_read_user_value (GSettingsBackend   *backend,
@@ -1041,7 +1041,8 @@ g_settings_backend_get_default (void)
  * If this is not implemented in the backend, then a %TRUE
  * #GSimplePermission is returned.
  *
- * Returns: a non-%NULL #GPermission. Free with g_object_unref()
+ * Returns: (not nullable) (transfer full): a non-%NULL #GPermission.
+ *     Free with g_object_unref()
  */
 GPermission *
 g_settings_backend_get_permission (GSettingsBackend *backend,
diff --git a/gio/gsettingsschema.c b/gio/gsettingsschema.c
index ec0caf655..7b478a387 100644
--- a/gio/gsettingsschema.c
+++ b/gio/gsettingsschema.c
@@ -202,7 +202,7 @@ static GSettingsSchemaSource *schema_sources;
  *
  * Increase the reference count of @source, returning a new reference.
  *
- * Returns: a new reference to @source
+ * Returns: (transfer full) (not nullable): a new reference to @source
  *
  * Since: 2.32
  **/
@@ -869,9 +869,9 @@ ensure_schema_lists (void)
  *
  * Deprecated.
  *
- * Returns: (element-type utf8) (transfer none):  a list of #GSettings
- *   schemas that are available, in no defined order.  The list must not be
- *   modified or freed.
+ * Returns: (element-type utf8) (transfer none) (not nullable): a list of
+ *   #GSettings schemas that are available, in no defined order.  The list
+ *   must not be modified or freed.
  *
  * Since: 2.26
  *
@@ -893,9 +893,9 @@ g_settings_list_schemas (void)
  *
  * Deprecated.
  *
- * Returns: (element-type utf8) (transfer none): a list of relocatable
- *   #GSettings schemas that are available, in no defined order.  The list must
- *   not be modified or freed.
+ * Returns: (element-type utf8) (transfer none) (not nullable): a list of
+ *   relocatable #GSettings schemas that are available, in no defined order.
+ *   The list must not be modified or freed.
  *
  * Since: 2.28
  *
@@ -915,7 +915,7 @@ g_settings_list_relocatable_schemas (void)
  *
  * Increase the reference count of @schema, returning a new reference.
  *
- * Returns: a new reference to @schema
+ * Returns: (transfer full) (not nullable): a new reference to @schema
  *
  * Since: 2.32
  **/
@@ -1066,8 +1066,8 @@ g_settings_schema_has_key (GSettingsSchema *schema,
  * You should free the return value with g_strfreev() when you are done
  * with it.
  *
- * Returns: (transfer full) (element-type utf8): a list of the children on
- *    @settings, in no defined order
+ * Returns: (not nullable) (transfer full) (element-type utf8): a list of
+ *    the children on @settings, in no defined order
  *
  * Since: 2.44
  */
@@ -1111,8 +1111,8 @@ g_settings_schema_list_children (GSettingsSchema *schema)
  * (since you should already know what keys are in your schema).  This
  * function is intended for introspection reasons.
  *
- * Returns: (transfer full) (element-type utf8): a list of the keys on
- *   @schema, in no defined order
+ * Returns: (not nullable) (transfer full) (element-type utf8): a list
+ *   of the keys on @schema, in no defined order
  *
  * Since: 2.46
  */
@@ -1250,7 +1250,7 @@ g_settings_schema_list (GSettingsSchema *schema,
  *
  * Get the ID of @schema.
  *
- * Returns: (transfer none): the ID
+ * Returns: (not nullable) (transfer none): the ID
  **/
 const gchar *
 g_settings_schema_get_id (GSettingsSchema *schema)
@@ -1581,7 +1581,7 @@ G_DEFINE_BOXED_TYPE (GSettingsSchemaKey, g_settings_schema_key, g_settings_schem
  *
  * Increase the reference count of @key, returning a new reference.
  *
- * Returns: a new reference to @key
+ * Returns: (not nullable) (transfer full): a new reference to @key
  *
  * Since: 2.40
  **/
@@ -1626,7 +1626,7 @@ g_settings_schema_key_unref (GSettingsSchemaKey *key)
  * It is a programmer error to request a key that does not exist.  See
  * g_settings_schema_list_keys().
  *
- * Returns: (transfer full): the #GSettingsSchemaKey for @name
+ * Returns: (not nullable) (transfer full): the #GSettingsSchemaKey for @name
  *
  * Since: 2.40
  **/
@@ -1652,7 +1652,7 @@ g_settings_schema_get_key (GSettingsSchema *schema,
  *
  * Gets the name of @key.
  *
- * Returns: the name of @key.
+ * Returns: (not nullable) (transfer none): the name of @key.
  *
  * Since: 2.44
  */
@@ -1682,7 +1682,7 @@ g_settings_schema_key_get_name (GSettingsSchemaKey *key)
  * function has to parse all of the source XML files in the schema
  * directory.
  *
- * Returns: (nullable): the summary for @key, or %NULL
+ * Returns: (nullable) (transfer none): the summary for @key, or %NULL
  *
  * Since: 2.34
  **/
@@ -1717,7 +1717,7 @@ g_settings_schema_key_get_summary (GSettingsSchemaKey *key)
  * function has to parse all of the source XML files in the schema
  * directory.
  *
- * Returns: (nullable): the description for @key, or %NULL
+ * Returns: (nullable) (transfer none): the description for @key, or %NULL
  *
  * Since: 2.34
  **/
@@ -1739,7 +1739,7 @@ g_settings_schema_key_get_description (GSettingsSchemaKey *key)
  *
  * Gets the #GVariantType of @key.
  *
- * Returns: (transfer none): the type of @key
+ * Returns: (not nullable) (transfer none): the type of @key
  *
  * Since: 2.40
  **/
@@ -1760,7 +1760,7 @@ g_settings_schema_key_get_value_type (GSettingsSchemaKey *key)
  * Note that this is the default value according to the schema.  System
  * administrator defaults and lockdown are not visible via this API.
  *
- * Returns: (transfer full): the default value for the key
+ * Returns: (not nullable) (transfer full): the default value for the key
  *
  * Since: 2.40
  **/
@@ -1823,7 +1823,7 @@ g_settings_schema_key_get_default_value (GSettingsSchemaKey *key)
  * You should free the returned value with g_variant_unref() when it is
  * no longer needed.
  *
- * Returns: (transfer full): a #GVariant describing the range
+ * Returns: (not nullable) (transfer full): a #GVariant describing the range
  *
  * Since: 2.40
  **/
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]