Fully document crypto/

crypto/transcript/README.md

@@ -27,6 +27,7 @@ their type, and their length.
 compatible with existing Rust projects using `merlin`.
 
 This library was
-[audited by Cypher Stack in March 2023](https://github.com/serai-dex/serai/raw/74924095e1a0f266b58181b539d9e74fa35dc37a/audits/Cypher%20Stack%20crypto%20March%202023/Audit.pdf),
-culminating in commit 669d2dbffc1dafb82a09d9419ea182667115df06. Any subsequent
-changes have not undergone auditing.
+[audited by Cypher Stack in March 2023](https://github.com/serai-dex/serai/raw/e1bb2c191b7123fd260d008e31656d090d559d21/audits/Cypher%20Stack%20crypto%20March%202023/Audit.pdf),
+culminating in commit
+[669d2dbffc1dafb82a09d9419ea182667115df06](https://github.com/serai-dex/serai/tree/669d2dbffc1dafb82a09d9419ea182667115df06).
+Any subsequent changes have not undergone auditing.

crypto/transcript/src/lib.rs

@@ -1,11 +1,14 @@
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![no_std]
 
+///! A transcript trait valid over a variety of transcript formats.
+
 #[cfg(feature = "merlin")]
 mod merlin;
 #[cfg(feature = "merlin")]
 pub use crate::merlin::MerlinTranscript;
 
+/// Tests for a transcript.
 #[cfg(any(test, feature = "tests"))]
 pub mod tests;
 
@@ -16,6 +19,7 @@ use digest::{
   Digest, Output, HashMarker,
 };
 
+/// A transcript trait valid over a variety of transcript formats.
 pub trait Transcript: Send + Clone {
   type Challenge: Send + Sync + Clone + AsRef<[u8]>;
 
@@ -130,6 +134,6 @@ impl<D: Send + Clone + SecureDigest> Transcript for DigestTranscript<D> {
   }
 }
 
-/// The recommended transcript, secure against length-extension attacks.
+/// The recommended transcript, guaranteed to be secure against length-extension attacks.
 #[cfg(feature = "recommended")]
 pub type RecommendedTranscript = DigestTranscript<blake2::Blake2b512>;

crypto/transcript/src/tests.rs

@@ -1,5 +1,6 @@
 use crate::Transcript;
 
+/// Test the sanity of a transcript.
 pub fn test_transcript<T: Transcript>()
 where
   T::Challenge: PartialEq,