Merge pull request #2814 from tintou/tintou/ostree-coverage

libostree: Enhance the annotation coverage

13 files changed, 96 insertions, 66 deletions

diff --git a/src/libostree/ostree-bootconfig-parser.c b/src/libostree/ostree-bootconfig-parser.c
index 365a7bc5..a8ca04d6 100644
--- a/src/libostree/ostree-bootconfig-parser.c
+++ b/src/libostree/ostree-bootconfig-parser.c
@@ -134,6 +134,14 @@ ostree_bootconfig_parser_parse (OstreeBootconfigParser  *self,
                                             cancellable, error);
 }
 
+/**
+ * ostree_bootconfig_parser_set:
+ * @self: Parser
+ * @key: the key
+ * @value: the key
+ *
+ * Set the @key/@value pair to the boot configuration dictionary.
+ */
 void
 ostree_bootconfig_parser_set (OstreeBootconfigParser  *self,
                               const char      *key,
@@ -142,6 +150,16 @@ ostree_bootconfig_parser_set (OstreeBootconfigParser  *self,
   g_hash_table_replace (self->options, g_strdup (key), g_strdup (value));
 }
 
+/**
+ * ostree_bootconfig_parser_get:
+ * @self: Parser
+ * @key: the key name to retrieve
+ *
+ * Get the value corresponding to @key from the boot configuration dictionary.
+ *
+ * Returns: (nullable): The corresponding value, or %NULL if the key hasn't been
+ * found.
+ */
 const char *
 ostree_bootconfig_parser_get (OstreeBootconfigParser  *self,
                               const char      *key)
diff --git a/src/libostree/ostree-deployment.c b/src/libostree/ostree-deployment.c
index 30e82a63..bfd0b2e6 100644
--- a/src/libostree/ostree-deployment.c
+++ b/src/libostree/ostree-deployment.c
@@ -89,7 +89,7 @@ ostree_deployment_get_bootserial (OstreeDeployment *self)
  * ostree_deployment_get_bootconfig:
  * @self: Deployment
  *
- * Returns: (transfer none): Boot configuration
+ * Returns: (transfer none) (nullable): Boot configuration
  */
 OstreeBootconfigParser *
 ostree_deployment_get_bootconfig (OstreeDeployment *self)
@@ -101,7 +101,7 @@ ostree_deployment_get_bootconfig (OstreeDeployment *self)
  * ostree_deployment_get_origin:
  * @self: Deployment
  *
- * Returns: (transfer none): Origin
+ * Returns: (transfer none) (nullable): Origin
  */
 GKeyFile *
 ostree_deployment_get_origin (OstreeDeployment *self)
@@ -157,9 +157,7 @@ ostree_deployment_set_bootserial (OstreeDeployment *self, int index)
 void
 ostree_deployment_set_bootconfig (OstreeDeployment *self, OstreeBootconfigParser *bootconfig)
 {
-  g_clear_object (&self->bootconfig);
-  if (bootconfig)
-    self->bootconfig = g_object_ref (bootconfig);
+  g_set_object (&self->bootconfig, bootconfig);
 }
 
 /**
@@ -173,6 +171,9 @@ ostree_deployment_set_bootconfig (OstreeDeployment *self, OstreeBootconfigParser
 void
 ostree_deployment_set_origin (OstreeDeployment *self, GKeyFile *origin)
 {
+  if (self->origin == origin)
+    return;
+
   g_clear_pointer (&self->origin, g_key_file_unref);
   if (origin)
     self->origin = g_key_file_ref (origin);
diff --git a/src/libostree/ostree-kernel-args.c b/src/libostree/ostree-kernel-args.c
index e0046e0c..582cab0f 100644
--- a/src/libostree/ostree-kernel-args.c
+++ b/src/libostree/ostree-kernel-args.c
@@ -566,8 +566,8 @@ ostree_kernel_args_replace_argv (OstreeKernelArgs  *kargs,
 /**
  * ostree_kernel_args_append_argv_filtered:
  * @kargs: a OstreeKernelArgs instance
- * @argv: an array of key=value argument pairs
- * @prefixes: an array of prefix strings
+ * @argv: (array zero-terminated=1): an array of key=value argument pairs
+ * @prefixes: (array zero-terminated=1): an array of prefix strings
  *
  * Appends each argument that does not have one of the @prefixes as prefix to the @kargs
  *
@@ -592,7 +592,7 @@ ostree_kernel_args_append_argv_filtered (OstreeKernelArgs  *kargs,
 /**
  * ostree_kernel_args_append_argv:
  * @kargs: a OstreeKernelArgs instance
- * @argv: an array of key=value argument pairs
+ * @argv: (array zero-terminated=1): an array of key=value argument pairs
  *
  * Appends each value in @argv to the corresponding value array and
  * appends key to kargs->order if it is not in the hash table already.
@@ -787,7 +787,7 @@ ostree_kernel_args_to_string (OstreeKernelArgs *kargs)
  * corresponding to the @key in @kargs hash table. Note that the application
  * will be terminated if the @key is found but the value array is empty
  *
- * Returns: NULL if @key is not found in the @kargs hash table,
+ * Returns: (nullable): %NULL if @key is not found in the @kargs hash table,
  * otherwise returns last element of value array corresponding to @key
  *
  * Since: 2019.3
diff --git a/src/libostree/ostree-mutable-tree.c b/src/libostree/ostree-mutable-tree.c
index 60e3be2f..d0002c4e 100644
--- a/src/libostree/ostree-mutable-tree.c
+++ b/src/libostree/ostree-mutable-tree.c
@@ -358,7 +358,7 @@ ostree_mutable_tree_remove (OstreeMutableTree *self,
  * ostree_mutable_tree_ensure_dir:
  * @self: Tree
  * @name: Name of subdirectory of self to retrieve/creates
- * @out_subdir: (out) (transfer full): the subdirectory
+ * @out_subdir: (out) (transfer full) (optional): the subdirectory
  * @error: a #GError
  *
  * Returns the subdirectory of self with filename @name, creating an empty one
@@ -400,6 +400,12 @@ ostree_mutable_tree_ensure_dir (OstreeMutableTree *self,
  * @out_file_checksum: (out) (transfer full) (nullable) (optional): checksum
  * @out_subdir: (out) (transfer full) (nullable) (optional): subdirectory
  * @error: a #GError
+ *
+ * Lookup @name and returns @out_file_checksum or @out_subdir depending on its
+ * file type.
+ *
+ * Returns: %TRUE on success and either @out_file_checksum or @out_subdir are
+ * filled, %FALSE otherwise.
  */
 gboolean
 ostree_mutable_tree_lookup (OstreeMutableTree   *self,
@@ -433,7 +439,7 @@ ostree_mutable_tree_lookup (OstreeMutableTree   *self,
  * @self: Tree
  * @split_path: (element-type utf8): File path components
  * @metadata_checksum: SHA256 checksum for metadata
- * @out_parent: (out) (transfer full): The parent tree
+ * @out_parent: (out) (transfer full) (optional): The parent tree
  * @error: a #GError
  *
  * Create all parent trees necessary for the given @split_path to
diff --git a/src/libostree/ostree-ref.c b/src/libostree/ostree-ref.c
index eb77d97c..5a2f44e3 100644
--- a/src/libostree/ostree-ref.c
+++ b/src/libostree/ostree-ref.c
@@ -45,7 +45,7 @@ G_DEFINE_BOXED_TYPE (OstreeCollectionRef, ostree_collection_ref,
  * refspec; no remote name is included), which can be used for non-P2P
  * operations.
  *
- * Returns: (transfer full) (nullable): a new #OstreeCollectionRef
+ * Returns: (transfer full): a new #OstreeCollectionRef
  * Since: 2018.6
  */
 OstreeCollectionRef *
@@ -102,7 +102,7 @@ ostree_collection_ref_free (OstreeCollectionRef *ref)
 
 /**
  * ostree_collection_ref_hash:
- * @ref: (not nullable): an #OstreeCollectionRef
+ * @ref: (not nullable) (type OstreeCollectionRef): an #OstreeCollectionRef
  *
  * Hash the given @ref. This function is suitable for use with #GHashTable.
  * @ref must be non-%NULL.
@@ -123,8 +123,8 @@ ostree_collection_ref_hash (gconstpointer ref)
 
 /**
  * ostree_collection_ref_equal:
- * @ref1: (not nullable): an #OstreeCollectionRef
- * @ref2 : (not nullable): another #OstreeCollectionRef
+ * @ref1: (not nullable) (type OstreeCollectionRef): an #OstreeCollectionRef
+ * @ref2 : (not nullable) (type OstreeCollectionRef): another #OstreeCollectionRef
  *
  * Compare @ref1 and @ref2 and return %TRUE if they have the same collection ID and
  * ref name, and %FALSE otherwise. Both @ref1 and @ref2 must be non-%NULL.
diff --git a/src/libostree/ostree-ref.h b/src/libostree/ostree-ref.h
index 384b8480..5e5c0ed3 100644
--- a/src/libostree/ostree-ref.h
+++ b/src/libostree/ostree-ref.h
@@ -71,7 +71,7 @@ _OSTREE_PUBLIC
 void ostree_collection_ref_freev (OstreeCollectionRef **refs);
 
 /**
- * OstreeCollectionRefv:
+ * OstreeCollectionRefv: (skip)
  *
  * A %NULL-terminated array of #OstreeCollectionRef instances, designed to
  * be used with g_auto():
diff --git a/src/libostree/ostree-repo-commit.c b/src/libostree/ostree-repo-commit.c
index 7f668b7d..9306a1a0 100644
--- a/src/libostree/ostree-repo-commit.c
+++ b/src/libostree/ostree-repo-commit.c
@@ -2445,9 +2445,9 @@ ostree_repo_abort_transaction (OstreeRepo     *self,
  * ostree_repo_write_metadata:
  * @self: Repo
  * @objtype: Object type
- * @expected_checksum: (allow-none): If provided, validate content against this checksum
+ * @expected_checksum: (nullable): If provided, validate content against this checksum
  * @object: Metadata
- * @out_csum: (out) (array fixed-size=32) (allow-none): Binary checksum
+ * @out_csum: (out) (array fixed-size=32) (optional): Binary checksum
  * @cancellable: Cancellable
  * @error: Error
  *
@@ -2620,7 +2620,7 @@ write_metadata_thread (GTask               *task,
  * ostree_repo_write_metadata_async:
  * @self: Repo
  * @objtype: Object type
- * @expected_checksum: (allow-none): If provided, validate content against this checksum
+ * @expected_checksum: (nullable): If provided, validate content against this checksum
  * @object: Metadata
  * @cancellable: Cancellable
  * @callback: Invoked when metadata is writed
@@ -2740,7 +2740,7 @@ ostree_repo_write_content_trusted (OstreeRepo       *self,
  * @expected_checksum: (allow-none): If provided, validate content against this checksum
  * @object_input: Content object stream
  * @length: Length of @object_input
- * @out_csum: (out) (array fixed-size=32) (allow-none): Binary checksum
+ * @out_csum: (out) (array fixed-size=32) (optional) (nullable): Binary checksum
  * @cancellable: Cancellable
  * @error: Error
  *
@@ -2995,7 +2995,8 @@ ostree_repo_write_content_async (OstreeRepo               *self,
  * ostree_repo_write_content_finish:
  * @self: a #OstreeRepo
  * @result: a #GAsyncResult
- * @out_csum: (out) (transfer full): A binary SHA256 checksum of the content object
+ * @out_csum: (out) (transfer full) (optional): A binary SHA256
+ * checksum of the content object
  * @error: a #GError
  *
  * Completes an invocation of ostree_repo_write_content_async().
@@ -3033,12 +3034,13 @@ create_empty_gvariant_dict (void)
 /**
  * ostree_repo_write_commit:
  * @self: Repo
- * @parent: (allow-none): ASCII SHA256 checksum for parent, or %NULL for none
- * @subject: (allow-none): Subject
- * @body: (allow-none): Body
- * @metadata: (allow-none): GVariant of type a{sv}, or %NULL for none
+ * @parent: (nullable): ASCII SHA256 checksum for parent, or %NULL for none
+ * @subject: (nullable): Subject
+ * @body: (nullable): Body
+ * @metadata: (nullable): GVariant of type a{sv}, or %NULL for none
  * @root: The tree to point the commit to
- * @out_commit: (out): Resulting ASCII SHA256 checksum for commit
+ * @out_commit: (out) (optional): Resulting ASCII SHA256 checksum for
+ * commit
  * @cancellable: Cancellable
  * @error: Error
  *
@@ -3086,13 +3088,14 @@ ostree_repo_write_commit (OstreeRepo      *self,
 /**
  * ostree_repo_write_commit_with_time:
  * @self: Repo
- * @parent: (allow-none): ASCII SHA256 checksum for parent, or %NULL for none
- * @subject: (allow-none): Subject
- * @body: (allow-none): Body
- * @metadata: (allow-none): GVariant of type a{sv}, or %NULL for none
+ * @parent: (nullable): ASCII SHA256 checksum for parent, or %NULL for none
+ * @subject: (nullable): Subject
+ * @body: (nullable): Body
+ * @metadata: (nullable): GVariant of type a{sv}, or %NULL for none
  * @root: The tree to point the commit to
  * @time: The time to use to stamp the commit
- * @out_commit: (out): Resulting ASCII SHA256 checksum for commit
+ * @out_commit: (out) (optional): Resulting ASCII SHA256 checksum for
+ * commit
  * @cancellable: Cancellable
  * @error: Error
  *
@@ -3191,7 +3194,7 @@ ostree_repo_read_commit_detached_metadata (OstreeRepo      *self,
  * ostree_repo_write_commit_detached_metadata:
  * @self: Repo
  * @checksum: ASCII SHA256 commit checksum
- * @metadata: (allow-none): Metadata to associate with commit in with format "a{sv}", or %NULL to delete
+ * @metadata: (nullable): Metadata to associate with commit in with format "a{sv}", or %NULL to delete
  * @cancellable: Cancellable
  * @error: Error
  *
diff --git a/src/libostree/ostree-repo-file.c b/src/libostree/ostree-repo-file.c
index 2f086de5..a6be8988 100644
--- a/src/libostree/ostree-repo-file.c
+++ b/src/libostree/ostree-repo-file.c
@@ -785,12 +785,14 @@ ostree_repo_file_tree_find_child  (OstreeRepoFile  *self,
 /**
  * ostree_repo_file_tree_query_child:
  * @self: #OstreeRepoFile
- * @n:
- * @attributes:
- * @flags:
- * @out_info: (out):
- * @cancellable: Cancellable
- * @error: Error
+ * @n: the child number
+ * @attributes: an attribute string to match, see g_file_attribute_matcher_new()
+ * @flags: a #GFileQueryInfoFlags
+ * @out_info: (out) (transfer full) (optional): the #GFileInfo of the child.
+ * @cancellable: a #GCancellable or %NULL
+ * @error: a #GError or %NULL
+ *
+ * Returns: %TRUE on success and the @out_info is set, %FALSE otherwise.
  */
 gboolean
 ostree_repo_file_tree_query_child (OstreeRepoFile  *self,
diff --git a/src/libostree/ostree-repo-pull-verify.c b/src/libostree/ostree-repo-pull-verify.c
index d38bc9f8..658367fa 100644
--- a/src/libostree/ostree-repo-pull-verify.c
+++ b/src/libostree/ostree-repo-pull-verify.c
@@ -361,7 +361,7 @@ validate_metadata_size (const char *prefix, GBytes *buf, GError **error)
  * @commit_data: Commit object data (GVariant)
  * @commit_metadata: Commit metadata (GVariant `a{sv}`), must contain at least one valid signature
  * @flags: Optionally disable GPG or signapi
- * @out_results: (nullable) (out) (transfer full): Textual description of results
+ * @out_results: (optional) (out) (transfer full): Textual description of results
  * @error: Error
  *
  * Validate the commit data using the commit metadata which must
diff --git a/src/libostree/ostree-repo-pull.c b/src/libostree/ostree-repo-pull.c
index dd21e8c8..99e52b1e 100644
--- a/src/libostree/ostree-repo-pull.c
+++ b/src/libostree/ostree-repo-pull.c
@@ -6564,10 +6564,9 @@ ostree_repo_pull_from_remotes_finish (OstreeRepo    *self,
  * @self: Self
  * @name: name of a remote
  * @options: (nullable): A GVariant a{sv} with an extensible set of flags
- * @out_summary: (out) (optional): return location for raw summary data, or
- *               %NULL
- * @out_signatures: (out) (optional): return location for raw summary
- *                  signature data, or %NULL
+ * @out_summary: (out) (optional): return location for raw summary data, or %NULL
+ * @out_signatures: (out) (optional): return location for raw summary signature
+ *                  data, or %NULL
  * @cancellable: a #GCancellable
  * @error: a #GError
  *
diff --git a/src/libostree/ostree-repo.c b/src/libostree/ostree-repo.c
index 4dbec47b..fd9592d7 100644
--- a/src/libostree/ostree-repo.c
+++ b/src/libostree/ostree-repo.c
@@ -973,8 +973,8 @@ _ostree_repo_remote_name_is_file (const char *remote_name)
  * @self: A OstreeRepo
  * @remote_name: Name
  * @option_name: Option
- * @default_value: (allow-none): Value returned if @option_name is not present
- * @out_value: (out): Return location for value
+ * @default_value: (nullable): Value returned if @option_name is not present
+ * @out_value: (out) (nullable): Return location for value
  * @error: Error
  *
  * OSTree remotes are represented by keyfile groups, formatted like:
@@ -2158,7 +2158,7 @@ ostree_repo_remote_list (OstreeRepo *self,
  * ostree_repo_remote_get_url:
  * @self: Repo
  * @name: Name of remote
- * @out_url: (out) (allow-none): Remote's URL
+ * @out_url: (out) (optional): Remote's URL
  * @error: Error
  *
  * Return the URL of the remote named @name through @out_url.  It is an
@@ -2201,7 +2201,7 @@ ostree_repo_remote_get_url (OstreeRepo  *self,
  * ostree_repo_remote_get_gpg_verify:
  * @self: Repo
  * @name: Name of remote
- * @out_gpg_verify: (out) (allow-none): Remote's GPG option
+ * @out_gpg_verify: (out) (optional): Remote's GPG option
  * @error: Error
  *
  * Return whether GPG verification is enabled for the remote named @name
@@ -3918,7 +3918,7 @@ ostree_repo_get_min_free_space_bytes (OstreeRepo  *self, guint64 *out_reserved_b
  * Before this function can be used, ostree_repo_init() must have been
  * called.
  *
- * Returns: (transfer none): Parent repository, or %NULL if none
+ * Returns: (transfer none) (nullable): Parent repository, or %NULL if none
  */
 OstreeRepo *
 ostree_repo_get_parent (OstreeRepo  *self)
@@ -5079,8 +5079,8 @@ ostree_repo_list_commit_objects_starting_with (OstreeRepo                  *self
  * ostree_repo_read_commit:
  * @self: Repo
  * @ref: Ref or ASCII checksum
- * @out_root: (out): An #OstreeRepoFile corresponding to the root
- * @out_commit: (out): The resolved commit checksum
+ * @out_root: (out) (optional): An #OstreeRepoFile corresponding to the root
+ * @out_commit: (out) (optional): The resolved commit checksum
  * @cancellable: Cancellable
  * @error: Error
  *
@@ -5683,9 +5683,9 @@ ostree_repo_add_gpg_signature_summary (OstreeRepo     *self,
  * ostree_repo_gpg_sign_data:
  * @self: Self
  * @data: Data as a #GBytes
- * @old_signatures: Existing signatures to append to (or %NULL)
+ * @old_signatures: (nullable): Existing signatures to append to (or %NULL)
  * @key_id: (array zero-terminated=1) (element-type utf8): NULL-terminated array of GPG keys.
- * @homedir: (allow-none): GPG home directory, or %NULL
+ * @homedir: (nullable): GPG home directory, or %NULL
  * @out_signatures: (out): in case of success will contain signature
  * @cancellable: A #GCancellable
  * @error: a #GError
@@ -5696,8 +5696,8 @@ ostree_repo_add_gpg_signature_summary (OstreeRepo     *self,
  *
  * You can use ostree_repo_gpg_verify_data() to verify the signatures.
  *
- * Returns: @TRUE if @data has been signed successfully,
- * @FALSE in case of error (@error will contain the reason).
+ * Returns: %TRUE if @data has been signed successfully,
+ * %FALSE in case of error (@error will contain the reason).
  *
  * Since: 2020.8
  */
diff --git a/src/libostree/ostree-sepolicy.c b/src/libostree/ostree-sepolicy.c
index 7815744b..7271bec4 100644
--- a/src/libostree/ostree-sepolicy.c
+++ b/src/libostree/ostree-sepolicy.c
@@ -549,7 +549,7 @@ ostree_sepolicy_get_csum (OstreeSePolicy *self)
  * @self: Self
  * @relpath: Path
  * @unix_mode: Unix mode
- * @out_label: (allow-none) (out) (transfer full): Return location for security context
+ * @out_label: (nullable) (out) (transfer full): Return location for security context
  * @cancellable: Cancellable
  * @error: Error
  *
@@ -565,6 +565,7 @@ ostree_sepolicy_get_label (OstreeSePolicy    *self,
                            GCancellable     *cancellable,
                            GError          **error)
 {
+  *out_label = NULL;
 #ifdef HAVE_SELINUX
   /* Early return if no policy */
   if (!self->selinux_hnd)
@@ -600,10 +601,10 @@ ostree_sepolicy_get_label (OstreeSePolicy    *self,
  * ostree_sepolicy_restorecon:
  * @self: Self
  * @path: Path string to use for policy lookup
- * @info: (allow-none): File attributes
+ * @info: (nullable): File attributes
  * @target: Physical path to target file
  * @flags: Flags controlling behavior
- * @out_new_label: (allow-none) (out): New label, or %NULL if unchanged
+ * @out_new_label: (nullable) (optional) (out): New label, or %NULL if unchanged
  * @cancellable: Cancellable
  * @error: Error
  *
diff --git a/src/libostree/ostree-sysroot-deploy.c b/src/libostree/ostree-sysroot-deploy.c
index 9c70bcd5..4d4f9bcb 100644
--- a/src/libostree/ostree-sysroot-deploy.c
+++ b/src/libostree/ostree-sysroot-deploy.c
@@ -3099,12 +3099,12 @@ sysroot_finalize_deployment (OstreeSysroot     *self,
 /**
  * ostree_sysroot_deploy_tree_with_options:
  * @self: Sysroot
- * @osname: (allow-none): osname to use for merge deployment
+ * @osname: (nullable): osname to use for merge deployment
  * @revision: Checksum to add
- * @origin: (allow-none): Origin to use for upgrades
- * @provided_merge_deployment: (allow-none): Use this deployment for merge path
- * @opts: (allow-none): Options
- * @out_new_deployment: (out): The new deployment path
+ * @origin: (nullable): Origin to use for upgrades
+ * @provided_merge_deployment: (nullable): Use this deployment for merge path
+ * @opts: (nullable): Options
+ * @out_new_deployment: (out) (transfer full): The new deployment path
  * @cancellable: Cancellable
  * @error: Error
  *
@@ -3146,11 +3146,11 @@ ostree_sysroot_deploy_tree_with_options (OstreeSysroot     *self,
 /**
  * ostree_sysroot_deploy_tree:
  * @self: Sysroot
- * @osname: (allow-none): osname to use for merge deployment
+ * @osname: (nullable): osname to use for merge deployment
  * @revision: Checksum to add
- * @origin: (allow-none): Origin to use for upgrades
- * @provided_merge_deployment: (allow-none): Use this deployment for merge path
- * @override_kernel_argv: (allow-none) (array zero-terminated=1) (element-type utf8): Use these as kernel arguments; if %NULL, inherit options from provided_merge_deployment
+ * @origin: (nullable): Origin to use for upgrades
+ * @provided_merge_deployment: (nullable): Use this deployment for merge path
+ * @override_kernel_argv: (nullable) (array zero-terminated=1) (element-type utf8): Use these as kernel arguments; if %NULL, inherit options from provided_merge_deployment
  * @out_new_deployment: (out): The new deployment path
  * @cancellable: Cancellable
  * @error: Error