[dconf: 1/3] Add some transfer annotations

[Xavier Claessens <xclaesse src gnome org>]

commit 1aeff160cccc902a7f80cd54759429d8ea5c96b8
Author: Xavier Claessens <xavier claessens collabora com>
Date:   Tue Dec 1 10:14:18 2015 -0500

    Add some transfer annotations
    
    (Expanded by Philip Withnall <withnall endlessm com> to add more
    annotations and fix prior review comments.)
    
    https://bugzilla.gnome.org/show_bug.cgi?id=758903

 client/dconf-client.c    | 20 +++++++++++---------
 common/dconf-changeset.c | 32 +++++++++++++++++---------------
 2 files changed, 28 insertions(+), 24 deletions(-)
---
diff --git a/client/dconf-client.c b/client/dconf-client.c
index 36b56aa..8669b4f 100644
--- a/client/dconf-client.c
+++ b/client/dconf-client.c
@@ -232,7 +232,7 @@ dconf_client_free_weak_ref (gpointer data)
  *
  * Creates a new #DConfClient.
  *
- * Returns: a new #DConfClient
+ * Returns: (transfer full): a new #DConfClient
  **/
 DConfClient *
 dconf_client_new (void)
@@ -261,7 +261,7 @@ dconf_client_new (void)
  * If there are outstanding "fast" changes in progress they may affect
  * the result of this call.
  *
- * Returns: a #GVariant, or %NULL
+ * Returns: (transfer full) (nullable): a #GVariant, or %NULL
  **/
 GVariant *
 dconf_client_read (DConfClient *client,
@@ -321,7 +321,7 @@ dconf_client_read (DConfClient *client,
  * If @flags is %DCONF_READ_FLAGS_NONE and @read_through is %NULL then
  * this call is exactly equivalent to dconf_client_read().
  *
- * Returns: a #GVariant, or %NULL
+ * Returns: (transfer full) (nullable): a #GVariant, or %NULL
  *
  * Since: 0.26
  */
@@ -351,7 +351,7 @@ dconf_client_read_full (DConfClient    *client,
  * may return inaccurate results with respect to those outstanding
  * changes.
  *
- * Returns: an array of strings, never %NULL.
+ * Returns: (transfer full) (not nullable): an array of strings, never %NULL.
  **/
 gchar **
 dconf_client_list (DConfClient *client,
@@ -376,7 +376,7 @@ dconf_client_list (DConfClient *client,
  *
  * The returned list will be %NULL-terminated.
  *
- * Returns: an array of strings, never %NULL.
+ * Returns: (transfer full) (not nullable): an array of strings, never %NULL.
  *
  * Since: 0.26
  */
@@ -419,7 +419,8 @@ dconf_client_is_writable (DConfClient *client,
  * dconf_client_write_fast:
  * @client: a #DConfClient
  * @key: the key to write to
- * @value: a #GVariant, the value to write
+ * @value: a #GVariant, the value to write. If it has a floating reference it's
+ *  consumed.
  * @error: a pointer to a %NULL #GError, or %NULL
  *
  * Writes @value to the given @key, or reset @key to its default value.
@@ -466,8 +467,9 @@ dconf_client_write_fast (DConfClient  *client,
  * dconf_client_write_sync:
  * @client: a #DConfClient
  * @key: the key to write to
- * @value: a #GVariant, the value to write
- * @tag: (out) (allow-none): the tag from this write
+ * @value: a #GVariant, the value to write. If it has a floating reference it's
+ *  consumed.
+ * @tag: (out) (optional) (not nullable) (transfer full): the tag from this write
  * @cancellable: a #GCancellable, or %NULL
  * @error: a pointer to a %NULL #GError, or %NULL
  *
@@ -548,7 +550,7 @@ dconf_client_change_fast (DConfClient     *client,
  * dconf_client_change_sync:
  * @client: a #DConfClient
  * @changeset: the changeset describing the requested change
- * @tag: (out) (allow-none): the tag from this write
+ * @tag: (out) (optional) (not nullable) (transfer full): the tag from this write
  * @cancellable: a #GCancellable, or %NULL
  * @error: a pointer to a %NULL #GError, or %NULL
  *
diff --git a/common/dconf-changeset.c b/common/dconf-changeset.c
index 35b02be..c80c88c 100644
--- a/common/dconf-changeset.c
+++ b/common/dconf-changeset.c
@@ -76,7 +76,7 @@ unref_gvariant0 (gpointer data)
  *
  * Creates a new, empty, #DConfChangeset.
  *
- * Returns: the new #DConfChangeset.
+ * Returns: (transfer full): the new #DConfChangeset.
  **/
 DConfChangeset *
 dconf_changeset_new (void)
@@ -92,7 +92,7 @@ dconf_changeset_new (void)
 
 /**
  * dconf_changeset_new_database:
- * @copy_of: (allow-none): a #DConfChangeset to copy
+ * @copy_of: (nullable): a #DConfChangeset to copy
  *
  * Creates a new #DConfChangeset in "database" mode, possibly
  * initialising it with the values of another changeset.
@@ -114,7 +114,7 @@ dconf_changeset_new (void)
  * If @copy_of is non-%NULL then its contents will be copied into the
  * created changeset.  @copy_of must be a database-mode changeset.
  *
- * Returns: a new #DConfChangeset in "database" mode
+ * Returns: (transfer full): a new #DConfChangeset in "database" mode
  *
  * Since: 0.16
  */
@@ -171,7 +171,7 @@ dconf_changeset_unref (DConfChangeset *changeset)
  *
  * Increases the reference count on @changeset
  *
- * Returns: @changeset
+ * Returns: (transfer full): @changeset
  **/
 DConfChangeset *
 dconf_changeset_ref (DConfChangeset *changeset)
@@ -200,7 +200,8 @@ dconf_changeset_record_dir_reset (DConfChangeset *changeset,
  * dconf_changeset_set:
  * @changeset: a #DConfChangeset
  * @path: a path to modify
- * @value: the value for the key, or %NULL to reset
+ * @value: (nullable): the value for the key, or %NULL to reset. If it has a
+ *  floating reference it's consumed.
  *
  * Adds an operation to modify @path to a #DConfChangeset.
  *
@@ -260,7 +261,7 @@ dconf_changeset_set (DConfChangeset *changeset,
  * dconf_changeset_get:
  * @changeset: a #DConfChangeset
  * @key: the key to check
- * @value: a return location for the value, or %NULL
+ * @value: (transfer full) (optional) (nullable): a return location for the value, or %NULL
  *
  * Checks if a #DConfChangeset has an outstanding request to change
  * the value of the given @key.
@@ -351,7 +352,7 @@ dconf_changeset_is_similar_to (DConfChangeset *changeset,
 /**
  * DConfChangesetPredicate:
  * @path: a path, as per dconf_is_path()
- * @value: a #GVariant, or %NULL
+ * @value: (nullable): a #GVariant, or %NULL
  * @user_data: user data pointer
  *
  * Callback function type for predicates over items in a
@@ -557,9 +558,9 @@ dconf_changeset_seal (DConfChangeset *changeset)
 /**
  * dconf_changeset_describe:
  * @changeset: a #DConfChangeset
- * @prefix: the prefix under which changes have been requested
- * @paths: the list of paths changed, relative to @prefix
- * @values: the list of values changed
+ * @prefix: (transfer none) (optional) (out): the prefix under which changes have been requested
+ * @paths: (transfer none) (optional) (out): the list of paths changed, relative to @prefix
+ * @values: (transfer none) (optional) (out): the list of values changed
  *
  * Describes @changeset.
  *
@@ -610,7 +611,7 @@ dconf_changeset_describe (DConfChangeset       *changeset,
  * The returned value has no particular format and should only be passed
  * to dconf_changeset_deserialise().
  *
- * Returns: a floating #GVariant
+ * Returns: (transfer full): a floating #GVariant
  **/
 GVariant *
 dconf_changeset_serialise (DConfChangeset *changeset)
@@ -630,7 +631,7 @@ dconf_changeset_serialise (DConfChangeset *changeset)
 
 /**
  * dconf_changeset_deserialise:
- * @serialised: a #GVariant from dconf_changeset_serialise()
+ * @serialised: (transfer none): a #GVariant from dconf_changeset_serialise()
  *
  * Creates a #DConfChangeset according to a serialised description
  * returned from an earlier call to dconf_changeset_serialise().
@@ -641,7 +642,7 @@ dconf_changeset_serialise (DConfChangeset *changeset)
  * This call never fails, even if @serialised is not in the correct
  * format.  Improperly-formatted parts are simply ignored.
  *
- * Returns: a new #DConfChangeset
+ * Returns: (transfer full): a new #DConfChangeset
  **/
 DConfChangeset *
 dconf_changeset_deserialise (GVariant *serialised)
@@ -675,7 +676,8 @@ dconf_changeset_deserialise (GVariant *serialised)
 /**
  * dconf_changeset_new_write:
  * @path: a dconf path
- * @value: a #GVariant, or %NULL
+ * @value: (nullable): a #GVariant, or %NULL. If it has a floating reference it's
+ *  consumed.
  *
  * Creates a new #DConfChangeset with one change.  This is equivalent to
  * calling dconf_changeset_new() and then dconf_changeset_set() with
@@ -783,7 +785,7 @@ dconf_changeset_change (DConfChangeset *changeset,
  * dconf_changeset_change() will result in the two changesets being
  * equal.
  *
- * Returns: (transfer full): the changes, or %NULL
+ * Returns: (transfer full) (nullable): the changes, or %NULL
  *
  * Since: 0.16
  */