Add docs and fix annotations for ostree-repo-file.c

The code here is not great, embarassing we've gone this
long without docs for some of these public API functions too.

I think this is right though.

diff --git a/rust-bindings/src/auto/repo_file.rs b/rust-bindings/src/auto/repo_file.rs
index 31fe363c8daee32b0ecacbe2b31a5c0f72e8644c..d480e76326f4bdce0d37a73725d0757b06965d7d 100644 (file)
--- a/rust-bindings/src/auto/repo_file.rs
+++ b/rust-bindings/src/auto/repo_file.rs
@@ -77,28 +77,28 @@ impl RepoFile {
     }
 
     #[doc(alias = "ostree_repo_file_tree_get_contents")]
-    pub fn tree_get_contents(&self) -> glib::Variant {
+    pub fn tree_get_contents(&self) -> Option<glib::Variant> {
         unsafe {
             from_glib_full(ffi::ostree_repo_file_tree_get_contents(self.to_glib_none().0))
         }
     }
 
     #[doc(alias = "ostree_repo_file_tree_get_contents_checksum")]
-    pub fn tree_get_contents_checksum(&self) -> glib::GString {
+    pub fn tree_get_contents_checksum(&self) -> Option<glib::GString> {
         unsafe {
             from_glib_none(ffi::ostree_repo_file_tree_get_contents_checksum(self.to_glib_none().0))
         }
     }
 
     #[doc(alias = "ostree_repo_file_tree_get_metadata")]
-    pub fn tree_get_metadata(&self) -> glib::Variant {
+    pub fn tree_get_metadata(&self) -> Option<glib::Variant> {
         unsafe {
             from_glib_full(ffi::ostree_repo_file_tree_get_metadata(self.to_glib_none().0))
         }
     }
 
     #[doc(alias = "ostree_repo_file_tree_get_metadata_checksum")]
-    pub fn tree_get_metadata_checksum(&self) -> glib::GString {
+    pub fn tree_get_metadata_checksum(&self) -> Option<glib::GString> {
         unsafe {
             from_glib_none(ffi::ostree_repo_file_tree_get_metadata_checksum(self.to_glib_none().0))
         }

diff --git a/rust-bindings/src/auto/versions.txt b/rust-bindings/src/auto/versions.txt
index c9131191385ba9248cd357c9d6028bb79ca160eb..c5cd56623d5f1a43149e27cb8f9976105b4269f3 100644 (file)
--- a/rust-bindings/src/auto/versions.txt
+++ b/rust-bindings/src/auto/versions.txt
@@ -1,2 +1,2 @@
 Generated by gir (https://github.com/gtk-rs/gir @ 0eeebbdf9d4d)
-from gir-files (@ f4ba299323ae)
+from gir-files (@ ed64a300c33e)

diff --git a/rust-bindings/sys/src/auto/versions.txt b/rust-bindings/sys/src/auto/versions.txt
index c9131191385ba9248cd357c9d6028bb79ca160eb..c5cd56623d5f1a43149e27cb8f9976105b4269f3 100644 (file)
--- a/rust-bindings/sys/src/auto/versions.txt
+++ b/rust-bindings/sys/src/auto/versions.txt
@@ -1,2 +1,2 @@
 Generated by gir (https://github.com/gtk-rs/gir @ 0eeebbdf9d4d)
-from gir-files (@ f4ba299323ae)
+from gir-files (@ ed64a300c33e)

diff --git a/src/libostree/ostree-repo-file.c b/src/libostree/ostree-repo-file.c
index a6be898806a6a07bdfc4e3bd7782bc4d5ffb131f..de606b0a70d6827ec5c719e6158c9ff5e4773328 100644 (file)
--- a/src/libostree/ostree-repo-file.c
+++ b/src/libostree/ostree-repo-file.c
@@ -269,6 +269,15 @@ do_resolve_nonroot (OstreeRepoFile     *self,
   return TRUE;
 }
 
+/**
+ * ostree_repo_file_ensure_resolved:
+ * @self: A repo file
+ * @error: Error
+ *
+ * Ensure that the backing metadata is loaded.
+ *
+ * Returns: %FALSE if the operation failed, %TRUE otherwise
+ */
 gboolean
 ostree_repo_file_ensure_resolved (OstreeRepoFile  *self,
                                    GError         **error)
@@ -321,18 +330,42 @@ ostree_repo_file_get_xattrs (OstreeRepoFile  *self,
   return TRUE;
 }
 
+/**
+ * ostree_repo_file_tree_get_contents:
+ * @self: A repo file
+ *
+ * This API will return %NULL if the file is not "resolved" i.e. in a loaded
+ * state.  It will also return %NULL if this path is not a directory tree.
+ *
+ * Returns: (nullable): The GVariant representing the children of this directory.
+ */
 GVariant *
 ostree_repo_file_tree_get_contents (OstreeRepoFile  *self)
 {
   return self->tree_contents;
 }
 
+/**
+ * ostree_repo_file_tree_get_metadata:
+ * @self: A repo file
+ *
+ * This API will return %NULL if the file is not "resolved" i.e. in a loaded
+ * state.  It will also return %NULL if this path is not a directory tree.
+ *
+ * Returns: (nullable): The GVariant representing the metadata for this directory.
+ */
 GVariant *
 ostree_repo_file_tree_get_metadata (OstreeRepoFile  *self)
 {
   return self->tree_metadata;
 }
 
+/**
+ * ostree_repo_file_tree_set_metadata:
+ * @self: A repo file
+ *
+ * Replace the metadata checksum and metadata object.
+ */
 void
 ostree_repo_file_tree_set_metadata (OstreeRepoFile *self,
                                      const char     *checksum,
@@ -344,12 +377,24 @@ ostree_repo_file_tree_set_metadata (OstreeRepoFile *self,
   self->tree_metadata_checksum = g_strdup (checksum);
 }
 
+/**
+ * ostree_repo_file_tree_get_contents_checksum:
+ * @self: A repo file
+ *
+ * Returns: (nullable): The SHA256 digest of the content object, or %NULL if this is not a directory.
+ */
 const char *
 ostree_repo_file_tree_get_contents_checksum (OstreeRepoFile  *self)
 {
   return self->tree_contents_checksum;
 }
 
+/**
+ * ostree_repo_file_tree_get_metadata_checksum:
+ * @self: A repo file
+ *
+ * Returns: (nullable): The SHA256 digest of the metadata object, or %NULL if this is not a directory.
+ */
 const char *
 ostree_repo_file_tree_get_metadata_checksum (OstreeRepoFile  *self)
 {
@@ -384,6 +429,12 @@ ostree_repo_file_get_root (OstreeRepoFile  *self)
   return parent;
 }
 
+/**
+ * ostree_repo_file_tree_get_checksum:
+ * @self: A repo file
+ *
+ * Returns: For non-directories, the SHA-256 digest of the object.  For directories, the metadata digest will be returned.
+ */
 const char *
 ostree_repo_file_get_checksum (OstreeRepoFile  *self)
 {