diff options
author | Colin Walters <walters@verbum.org> | 2020-11-06 19:38:40 +0000 |
---|---|---|
committer | Colin Walters <walters@verbum.org> | 2020-11-11 22:01:11 +0000 |
commit | 43913178a7eb23f615555dc0962844fce1f82570 (patch) | |
tree | 5add2ac773a249065ed6924b19e6a9a148aa0236 | |
parent | c48e7e10605954c784ec63ddcc61c3797fc538f4 (diff) | |
download | ostree-43913178a7eb23f615555dc0962844fce1f82570.tar.gz |
deployment: Add a bunch of docs and fix annotations
We were missing docs for these, also add some nullability annotations.
Motivated by using these from the Rust bindings.
-rw-r--r-- | src/libostree/ostree-deployment.c | 85 |
1 files changed, 81 insertions, 4 deletions
diff --git a/src/libostree/ostree-deployment.c b/src/libostree/ostree-deployment.c index 182bceea..558434de 100644 --- a/src/libostree/ostree-deployment.c +++ b/src/libostree/ostree-deployment.c @@ -27,12 +27,24 @@ typedef GObjectClass OstreeDeploymentClass; G_DEFINE_TYPE (OstreeDeployment, ostree_deployment, G_TYPE_OBJECT) +/* + * ostree_deployment_get_csum: + * @self: Deployment + * + * Returns: (not nullable): The OSTree commit used for this deployment. + */ const char * ostree_deployment_get_csum (OstreeDeployment *self) { return self->csum; } +/* + * ostree_deployment_get_bootcsum: + * @self: Deployment + * + * Returns: (not nullable): The "boot checksum" for content installed in `/boot/ostree`. + */ const char * ostree_deployment_get_bootcsum (OstreeDeployment *self) { @@ -41,9 +53,9 @@ ostree_deployment_get_bootcsum (OstreeDeployment *self) /* * ostree_deployment_get_osname: - * @self: Deployemnt + * @self: Deployment * - * Returns: The "stateroot" name, also known as an "osname" + * Returns: (not nullable): The "stateroot" name, also known as an "osname" */ const char * ostree_deployment_get_osname (OstreeDeployment *self) @@ -51,12 +63,24 @@ ostree_deployment_get_osname (OstreeDeployment *self) return self->osname; } +/* + * ostree_deployment_get_deployserial: + * @self: Deployment + * + * Returns: An integer counter used to ensure multiple deployments of a commit are unique + */ int ostree_deployment_get_deployserial (OstreeDeployment *self) { return self->deployserial; } +/* + * ostree_deployment_get_bootserial: + * @self: Deployment + * + * Returns: An integer counter to index from shared kernels into deployments + */ int ostree_deployment_get_bootserial (OstreeDeployment *self) { @@ -87,24 +111,51 @@ ostree_deployment_get_origin (OstreeDeployment *self) return self->origin; } +/** + * ostree_deployment_get_index: + * @self: Deployment + * + * Returns: The global index into the bootloader ordering + */ int ostree_deployment_get_index (OstreeDeployment *self) { return self->index; } +/** + * ostree_deployment_set_index: + * @self: Deployment + * @index: Index into bootloader ordering + * + * Sets the global index into the bootloader ordering. + */ void ostree_deployment_set_index (OstreeDeployment *self, int index) { self->index = index; } +/** + * ostree_deployment_set_bootserial: + * @self: Deployment + * @index: Don't use this + * + * Should never have been made public API; don't use this. + */ void ostree_deployment_set_bootserial (OstreeDeployment *self, int index) { self->bootserial = index; } +/** + * ostree_deployment_set_bootconfig: + * @self: Deployment + * @bootconfig: (nullable): Bootloader configuration object + * + * Set or clear the bootloader configuration. + */ void ostree_deployment_set_bootconfig (OstreeDeployment *self, OstreeBootconfigParser *bootconfig) { @@ -113,6 +164,14 @@ ostree_deployment_set_bootconfig (OstreeDeployment *self, OstreeBootconfigParser self->bootconfig = g_object_ref (bootconfig); } +/** + * ostree_deployment_set_origin: + * @self: Deployment + * @origin: (nullable): Set the origin for this deployment + * + * Replace the "origin", which is a description of the source + * of the deployment and how to update to the next version. + */ void ostree_deployment_set_origin (OstreeDeployment *self, GKeyFile *origin) { @@ -190,7 +249,7 @@ _ostree_deployment_get_overlay_initrds (OstreeDeployment *self) * ostree_deployment_clone: * @self: Deployment * - * Returns: (transfer full): New deep copy of @self + * Returns: (not nullable) (transfer full): New deep copy of @self */ OstreeDeployment * ostree_deployment_clone (OstreeDeployment *self) @@ -224,6 +283,12 @@ ostree_deployment_clone (OstreeDeployment *self) return ret; } +/** + * ostree_deployment_hash: + * @v: (type OstreeDeployment): Deployment + * + * Returns: An integer suitable for use in a `GHashTable` + */ guint ostree_deployment_hash (gconstpointer v) { @@ -287,6 +352,17 @@ ostree_deployment_class_init (OstreeDeploymentClass *class) object_class->finalize = ostree_deployment_finalize; } +/** + * ostree_deployment_new: + * @index: Global index into the bootloader entries + * @osname: "stateroot" for this deployment + * @csum: OSTree commit that will be deployed + * @deployserial: Unique counter + * @bootcsum: (nullable): Kernel/initrd checksum + * @bootserial: Unique index + * + * Returns: (transfer full) (not nullable): New deployment + */ OstreeDeployment * ostree_deployment_new (int index, const char *osname, @@ -323,7 +399,7 @@ ostree_deployment_new (int index, * access, it, you must either use fd-relative api such as openat(), * or concatenate it with the full ostree_sysroot_get_path(). * - * Returns: (transfer full): Path to deployment root directory, relative to sysroot + * Returns: (not nullable) (transfer full): Path to deployment root directory, relative to sysroot */ char * ostree_deployment_get_origin_relpath (OstreeDeployment *self) @@ -337,6 +413,7 @@ ostree_deployment_get_origin_relpath (OstreeDeployment *self) /** * ostree_deployment_unlocked_state_to_string: * + * Returns: (not nullable): Description of state * Since: 2016.4 */ const char * |