Docs: Make tone more factual

crypto/hkdf/src/lib.rs

@@ -164,7 +164,7 @@ use bouncycastle_core::traits::XOF;
 
 /*** Constants ***/
 // Slightly hacky, but set this to accomodate the underlying hash primitive with the largest output size.
-// Would be better to somehow pull that at compile time from H, but I'm not sure how to do that.
+// It would be better to pull that at compile time from H, but the implementation does not currently do that.
 const HMAC_BLOCK_LEN: usize = 64;
 
 /*** String constants ***/
@@ -180,7 +180,7 @@ pub type HKDF_SHA256 = HKDF<SHA256>;
 pub type HKDF_SHA512 = HKDF<SHA512>;
 
 pub struct HKDF<H: Hash + HashAlgParams + Default> {
-    hmac: Option<HMAC<H>>,  // Optional because we can't construct an HMAC until they give us a key
+    hmac: Option<HMAC<H>>,  // Optional because an HMAC cannot be constructed until a key is provided
                             // to initialize it with.
                             // None should correspond to a state of Uninitialized.
     entropy: HkdfEntropyTracker<H>,
@@ -241,7 +241,7 @@ impl<H: Hash + HashAlgParams + Default> HkdfEntropyTracker<H> {
     }
 }
 
-// Since I don't want this struct to be public, the tests have to go here.
+// Because this struct is not public, the tests have to go here.
 #[test]
 fn test_entropy_tracker() {
     let mut entropy = HkdfEntropyTracker::<SHA256>::new();
@@ -398,7 +398,7 @@ impl<H: Hash + HashAlgParams + Default> HKDF<H> {
         let out: &mut [u8] = okm.mut_ref_to_bytes()?;
         // Could potentially speed this up by unrolling T(0) and T(1)
 
-        // We're gonna have to kludge the prk key type to MACKey to make HMAC happy, but we'll set it back to the original value afterwards.
+        // The prk key type must be temporarily changed to MACKey to satisfy HMAC, then restored afterwards.
         let prk_as_mac_key = KeyMaterial::<HMAC_BLOCK_LEN>::from_bytes_as_type(prk.ref_to_bytes(), KeyType::MACKey)?;
 
         #[allow(non_snake_case)]
@@ -481,7 +481,7 @@ impl<H: Hash + HashAlgParams + Default> HKDF<H> {
         };
 
         // Often HMAC is initialized with a zero salt,
-        // So we're gonna ignore key strength errors here
+        // Key strength errors are ignored here.
         // This will all be tabulated correctly via entropy.credit_entropy()
         self.hmac = Some(HMAC::<H>::new_allow_weak_key(salt)?);
 

crypto/mlkem/src/lib.rs

@@ -115,13 +115,13 @@
 //! | ML-KEM-1024_expanded | 1568           | 10272              | 3168            | 12418 |
 //!
 //! All values are in bytes. The "in memory" sizes are measured by rust's `std::mem::size_of`.
-//! Values in parentheses are the usual sizes in our un-optimized implementation in the \[bouncycastle_mldsa] crate.
+//! Values in parentheses are the usual sizes in the un-optimized implementation in the \[bouncycastle_mldsa] crate.
 //!
 //! # Security
 //! All functionality exposed by this crate is considered secure to use.
 //! In other words, this crate does not contain any "hazmat" except for the obvious points about
 //! handling your private keys properly: if you post your private key to github, or you generate
-//! production keys from a weak seed, I can't help you, that's on you.
+//! production keys from a weak seed, that use is unsupported.
 //! It is worth mentioning, however, that if using a [MLKEM::keygen_from_seed], then it is your
 //! responsibility to ensure that the seed is cryptographically random and unpredictable.
 //! And also that [MLKEM::encaps_internal] requires you to provide the randomness, so the ciphertext
@@ -133,8 +133,8 @@
 //! constructions. That should give this implementation reasonably good resistance to timing and
 //! power analysis key extraction attacks, however: A) this is a "best-effort" and not formally verified,
 //! and B) the Rust compiler does not guarantee constant-time behaviour no matter how clever your code,
-//! so like all Safe Rust code (ie Rust code that does not include inline assembly), we are at the mercy
-//! of the Rust compiler's optimizer for whether our bitshift-and-xor code actually remains
+//! so like all Safe Rust code (ie Rust code that does not include inline assembly), the Rust compiler's optimizer
+//! determines whether the bitshift-and-xor code actually remains
 //! constant-time after compilation.
 
 #![no_std]
@@ -143,13 +143,13 @@
 #![allow(incomplete_features)] // needed because currently generic_const_exprs is experimental
 #![feature(generic_const_exprs)]
 #![feature(adt_const_params)]
-// These are because I'm matching variable names exactly against FIPS 204, for example both 'K' and 'k',
+// These are because variable names are matched exactly against FIPS 204, for example both 'K' and 'k',
 // or 'A' and 'a' are used and have specific meanings.
 // But need to tell the rust linter to not care.
 #![allow(non_snake_case)]
 #![allow(non_upper_case_globals)]
-// so I can use private traits to hide internal stuff that needs to be generic within the
-// MLKEM implementation, but I don't want accessed from outside, such as FIPS-internal functions.
+// so private traits can hide internal items that need to be generic within the
+// MLKEM implementation, but should not be accessed from outside, such as FIPS-internal functions.
 #![allow(private_bounds)]
 
 // imports needed just for docs