Add docs to built-in policies

Document the builtin policy statics using the original policy name and a
short description copied from the policy file as summary, and the
raw content of the policy as detailed documentation. (Because of the
macro indirection, the 'source' link generated by rustdoc is kinda
useless, so this provides a replacement.)

Author: gregoire-mullvad

src/policy/builtin.rs

@@ -41,10 +41,23 @@ impl Deref for BuiltInPolicy {
 
 macro_rules! define_builtin_policies {
     ($(
-        $const_name:ident = $policy_name:literal
+        $const_name:ident = $policy_name:literal -- $description:literal
     ),* $(,)?) => {
         // Define the static constants
         $(
+            #[doc = concat!("`", $policy_name, "`: ", $description)]
+            #[doc = ""]
+
+            // We include the policy source in the documentation: it's an easy way to provide the
+            // user with full information about the policy and it's hard to document a policy
+            // without just paraphrasing its content anyway.
+            #[doc = "```text"]
+            #[doc = include_str!(concat!(
+                        "../../builtin-policies/",
+                        $policy_name,
+                        ".builtin-policy"
+                    ))]
+            #[doc = "```"]
             pub static $const_name: BuiltInPolicy = BuiltInPolicy {
                 name: $policy_name,
                 policy: LazyLock::new(|| {
@@ -86,9 +99,16 @@ macro_rules! define_builtin_policies {
 
 // All built-in policies defined here in one single place.
 // Multiple invocations not possible since this invocation emits the `builtin` lookup function.
+//
+// The syntax is
+//      <static name> = "<policy name>" -- "<one-line description>"
+//  Where
+//      <policy name> is the policy name defined by the Sigsum project
+//      <static name> is <policy name> converted to uppercase and with '-' replaced by '_'
+//      <one-line description> is the comment line at the top of the policy file
 define_builtin_policies! {
-    SIGSUM_TEST1_2025 = "sigsum-test1-2025",
-    SIGSUM_TEST2_2025 = "sigsum-test2-2025",
-    SIGSUM_TEST_2025_3 = "sigsum-test-2025-3",
-    SIGSUM_GENERIC_2025_1 = "sigsum-generic-2025-1",
+    SIGSUM_TEST1_2025 = "sigsum-test1-2025" -- "Policy using the sigsum test log at test.sigsum.org/barreleye",
+    SIGSUM_TEST2_2025 = "sigsum-test2-2025" -- "Policy using the sigsum test log at test.sigsum.org/barreleye",
+    SIGSUM_TEST_2025_3 = "sigsum-test-2025-3" -- "Policy using two sigsum test logs at test.sigsum.org/barreleye and serviceberry.tlog.stagemole.eu",
+    SIGSUM_GENERIC_2025_1 = "sigsum-generic-2025-1" -- "This is a Sigsum trust policy that has been vetted by the Sigsum project",
 }