libostree: Enhance the annotation coverage

Increase the coverage of the GObject Introspection annotation and most notably replace the use of "allow-none" with "out" parameters to "nullable" or "optional" as the previous annotation is deprecated and ambiguous.
2025-03-14 04:59:00 +03:00 · 2023-02-09 16:28:53 +01:00 · 2023-02-09 16:28:53 +01:00 · fa750fba80
commit fa750fba80
parent 51f3d03d9b
13 changed files with 96 additions and 66 deletions
--- 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)
--- 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);
--- 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
--- 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
--- 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.
--- 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():
--- a/src/libostree/ostree-repo-commit.c
+++ b/src/libostree/ostree-repo-commit.c
@ -2444,9 +2444,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
 *
@ -2619,7 +2619,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
@ -2739,7 +2739,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
 *
@ -2994,7 +2994,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().
@ -3032,12 +3033,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
 *
@ -3085,13 +3087,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
 *
@ -3190,7 +3193,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
 *
--- 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,
--- 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
--- 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
 *
--- a/src/libostree/ostree-repo.c
+++ b/src/libostree/ostree-repo.c
@ -972,8 +972,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:
@ -2157,7 +2157,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
@ -2200,7 +2200,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
@ -3917,7 +3917,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)
@ -5078,8 +5078,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
 *
@ -5662,9 +5662,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
@ -5675,8 +5675,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
 */
--- 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
 *
--- 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