Improve documentation

Author: linus-mullvad

src/policy/builtin.rs

@@ -1,3 +1,9 @@
+//! Built-in policies for Sigsum.
+//!
+//! This module contains all the included built-in policies. These can be accessed
+//! and used directly as public statics, or looked up at runtime by name via
+//! [`Policy::builtin`].
+
 use std::ops::Deref;
 use std::sync::LazyLock;
 
@@ -18,7 +24,7 @@ pub struct BuiltInPolicy {
 }
 
 impl BuiltInPolicy {
-    /// Returns the policy for this built in policy. Can also be accessed
+    /// Returns the policy for this built-in policy. Can also be accessed
     /// via the `Deref` implementation.
     pub fn policy(&self) -> &Policy {
         &self.policy
@@ -78,7 +84,7 @@ macro_rules! define_builtin_policies {
     };
 }
 
-// All built in policies defined here in one single place.
+// All built-in policies defined here in one single place.
 // Multiple invocations not possible since this invocation emits the `builtin` lookup function.
 define_builtin_policies! {
     SIGSUM_TEST1_2025 = "sigsum-test1-2025",

src/policy/mod.rs

@@ -12,7 +12,7 @@ pub use parsing::ParsePolicyError;
 /// The Sigsum policy dictates if a signed tree head is considered valid (and by extension, if a
 /// Sigsum signature is valid).
 ///
-/// This library contains a bunch of built in policies, ready for use in [`builtin`].
+/// This library contains a bunch of built-in policies, ready for use in [`builtin`].
 #[derive(Debug, Eq, PartialEq)]
 pub struct Policy {
     // logs keeps the list of log keys and URLs indexed by keyhash.
@@ -60,6 +60,8 @@ impl<'a> Iterator for Logs<'a> {
 
 impl Policy {
     /// Returns a built-in policy by name, if one exists.
+    ///
+    /// See [`builtin`] for public static definitions of these policies.
     pub fn builtin(name: &str) -> Option<&'static Self> {
         builtin::builtin(name)
     }