From 48e0d334b86d5c6f9dce123c65c1159cffc0917c Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Mon, 2 Aug 2021 15:51:49 -0400
Subject: [PATCH] Deny unused results, warn on missing docs (except auto/)

And add basic docs for our manually implemented functions.
---
 rust-bindings/rust/src/checksum.rs  | 3 +++
 rust-bindings/rust/src/functions.rs | 4 ++++
 rust-bindings/rust/src/lib.rs       | 6 +++++-
 rust-bindings/rust/src/repo.rs      | 8 ++++++++
 rust-bindings/rust/src/se_policy.rs | 1 +
 5 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/rust-bindings/rust/src/checksum.rs b/rust-bindings/rust/src/checksum.rs
index 83bb44b9..454c9884 100644
--- a/rust-bindings/rust/src/checksum.rs
+++ b/rust-bindings/rust/src/checksum.rs
@@ -19,10 +19,13 @@ fn base64_config() -> &'static radix64::CustomConfig {
     })
 }
 
+/// Error returned from parsing a checksum.
 #[derive(Debug, thiserror::Error)]
 pub enum ChecksumError {
+    /// Invalid hex checksum string.
     #[error("invalid hex checksum string")]
     InvalidHexString,
+    /// Invalid base64 checksum string
     #[error("invalid base64 checksum string")]
     InvalidBase64String,
 }
diff --git a/rust-bindings/rust/src/functions.rs b/rust-bindings/rust/src/functions.rs
index c6eb2c5e..a30ea7bf 100644
--- a/rust-bindings/rust/src/functions.rs
+++ b/rust-bindings/rust/src/functions.rs
@@ -5,6 +5,7 @@ use glib::{prelude::*, translate::*};
 use glib_sys::GFALSE;
 use std::{future::Future, mem::MaybeUninit, pin::Pin, ptr};
 
+/// Compute the SHA-256 checksum of a file.
 pub fn checksum_file<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>(
     f: &P,
     objtype: ObjectType,
@@ -24,6 +25,7 @@ pub fn checksum_file<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>(
     }
 }
 
+/// Asynchronously compute the SHA-256 checksum of a file.
 pub fn checksum_file_async<
     P: IsA<gio::File>,
     Q: IsA<gio::Cancellable>,
@@ -69,6 +71,7 @@ pub fn checksum_file_async<
     }
 }
 
+/// Asynchronously compute the SHA-256 checksum of a file.
 #[allow(clippy::type_complexity)]
 pub fn checksum_file_async_future<P: IsA<gio::File> + Clone + 'static>(
     f: &P,
@@ -83,6 +86,7 @@ pub fn checksum_file_async_future<P: IsA<gio::File> + Clone + 'static>(
     }))
 }
 
+/// Compute the OSTree checksum of a content object.
 pub fn checksum_file_from_input<P: IsA<gio::InputStream>, Q: IsA<gio::Cancellable>>(
     file_info: &gio::FileInfo,
     xattrs: Option<&glib::Variant>,
diff --git a/rust-bindings/rust/src/lib.rs b/rust-bindings/rust/src/lib.rs
index 11b36290..8b065dc7 100644
--- a/rust-bindings/rust/src/lib.rs
+++ b/rust-bindings/rust/src/lib.rs
@@ -5,6 +5,9 @@
 //! along with a layer for deploying them and managing the bootloader configuration.
 
 #![cfg_attr(feature = "dox", feature(doc_cfg))]
+#![deny(unused_must_use)]
+#![warn(missing_docs)]
+#![warn(rustdoc::broken_intra_doc_links)]
 
 // Re-export our dependencies.  See https://gtk-rs.org/blog/2021/06/22/new-release.html
 // "Dependencies are re-exported".  Users will need e.g. `gio::File`, so this avoids
@@ -16,6 +19,7 @@ pub use glib;
 #[rustfmt::skip]
 #[allow(clippy::all)]
 #[allow(unused_imports)]
+#[allow(missing_docs)]
 mod auto;
 pub use crate::auto::functions::*;
 pub use crate::auto::*;
@@ -62,7 +66,7 @@ pub use crate::sysroot_deploy_tree_opts::SysrootDeployTreeOpts;
 #[cfg(test)]
 mod tests;
 
-// prelude
+/// Prelude, intended for glob imports.
 pub mod prelude {
     pub use crate::auto::traits::*;
     // See "Re-export dependencies above".
diff --git a/rust-bindings/rust/src/repo.rs b/rust-bindings/rust/src/repo.rs
index 4b683716..ba5ab14f 100644
--- a/rust-bindings/rust/src/repo.rs
+++ b/rust-bindings/rust/src/repo.rs
@@ -41,6 +41,7 @@ impl Repo {
         Repo::new(&gio::File::for_path(path.as_ref()))
     }
 
+    /// Find all objects reachable from a commit.
     pub fn traverse_commit<P: IsA<gio::Cancellable>>(
         &self,
         commit_checksum: &str,
@@ -66,6 +67,7 @@ impl Repo {
         }
     }
 
+    /// List all branch names (refs).
     pub fn list_refs<P: IsA<gio::Cancellable>>(
         &self,
         refspec_prefix: Option<&str>,
@@ -117,6 +119,7 @@ impl Repo {
         }
     }
 
+    /// Write a content object from provided input.
     pub fn write_content<P: IsA<gio::InputStream>, Q: IsA<gio::Cancellable>>(
         &self,
         expected_checksum: Option<&str>,
@@ -144,6 +147,7 @@ impl Repo {
         }
     }
 
+    /// Write a metadata object.
     pub fn write_metadata<P: IsA<gio::Cancellable>>(
         &self,
         objtype: ObjectType,
@@ -171,6 +175,7 @@ impl Repo {
         }
     }
 
+    /// Asynchronously write a content object.
     pub fn write_content_async<
         P: IsA<gio::InputStream>,
         Q: IsA<gio::Cancellable>,
@@ -222,6 +227,7 @@ impl Repo {
         }
     }
 
+    /// Asynchronously write a content object.
     pub fn write_content_async_future<P: IsA<gio::InputStream> + Clone + 'static>(
         &self,
         expected_checksum: Option<&str>,
@@ -245,6 +251,7 @@ impl Repo {
         }))
     }
 
+    /// Asynchronously write a metadata object.
     pub fn write_metadata_async<
         P: IsA<gio::Cancellable>,
         Q: FnOnce(Result<Checksum, Error>) + Send + 'static,
@@ -295,6 +302,7 @@ impl Repo {
         }
     }
 
+    /// Asynchronously write a metadata object.
     pub fn write_metadata_async_future(
         &self,
         objtype: ObjectType,
diff --git a/rust-bindings/rust/src/se_policy.rs b/rust-bindings/rust/src/se_policy.rs
index 6ec9cfe1..43f8c11f 100644
--- a/rust-bindings/rust/src/se_policy.rs
+++ b/rust-bindings/rust/src/se_policy.rs
@@ -2,6 +2,7 @@ use crate::SePolicy;
 use std::ptr;
 
 impl SePolicy {
+    /// Reset the SELinux filesystem creation context.
     pub fn fscreatecon_cleanup() {
         unsafe {
             ffi::ostree_sepolicy_fscreatecon_cleanup(ptr::null_mut());