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.

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))
         }

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)

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)

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)
 {