From eeb738b649b00b3b48354a51e31e72d10e81e12e Mon Sep 17 00:00:00 2001
From: David Niehues <niehues@utilacy.de>
Date: Thu, 28 Nov 2024 10:39:11 +0100
Subject: [PATCH] add documentation and doc-tests for blake2b.rs

---
 ciphers/src/subtle/blake2b.rs | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/ciphers/src/subtle/blake2b.rs b/ciphers/src/subtle/blake2b.rs
index 2d5b6a45..3b5b34b6 100644
--- a/ciphers/src/subtle/blake2b.rs
+++ b/ciphers/src/subtle/blake2b.rs
@@ -9,19 +9,43 @@ use blake2::Blake2bMac;
 use rosenpass_to::{ops::copy_slice, with_destination, To};
 use rosenpass_util::typenum2const;
 
+/// Specify that the used implementation of BLAKE2b is the MAC version of BLAKE2b 
+/// with output and key length of 32 bytes (see [Blake2bMac<U32>]).
 type Impl = Blake2bMac<U32>;
 
 type KeyLen = <Impl as KeySizeUser>::KeySize;
 type OutLen = <Impl as OutputSizeUser>::OutputSize;
 
+/// The key length for BLAKE2b supported by this API. Currently 32 Bytes.
 const KEY_LEN: usize = typenum2const! { KeyLen };
+/// The output length for BLAKE2b supported by this API. Currently 32 Bytes.
 const OUT_LEN: usize = typenum2const! { OutLen };
 
+/// Minimal key length supported by this API (identical to [KEY_LEN])
 pub const KEY_MIN: usize = KEY_LEN;
+/// maximal key length supported by this API (identical to [KEY_LEN])
 pub const KEY_MAX: usize = KEY_LEN;
+/// minimal output length supported by this API (identical [OUT_LEN])
 pub const OUT_MIN: usize = OUT_LEN;
+/// maximal output length supported by this API (identical [OUT_LEN])
 pub const OUT_MAX: usize = OUT_LEN;
 
+/// Hashes the given `data` with the [Blake2bMac<U32>] hash function under the given `key`.
+/// The [KEY_LEN] and [OUT_LEN] are both set to 32 bytes (or 256 bits).  
+/// 
+/// # Examples
+/// 
+///```rust
+/// # use rosenpass_ciphers::subtle::blake2b::hash;
+/// use rosenpass_to::To;
+/// let zero_key: [u8; 32] = [0; 32]; 
+/// let data: [u8; 32] = [255; 32];
+/// // buffer for the hash output
+/// let mut hash_data: [u8; 32] = [0u8; 32];  
+///
+/// assert!(hash(&zero_key, &data).to(&mut hash_data).is_ok(), "Hashing has to return OK result");
+///```
+/// 
 #[inline]
 pub fn hash<'a>(key: &'a [u8], data: &'a [u8]) -> impl To<[u8], anyhow::Result<()>> + 'a {
     with_destination(|out: &mut [u8]| {
@@ -36,7 +60,6 @@ pub fn hash<'a>(key: &'a [u8], data: &'a [u8]) -> impl To<[u8], anyhow::Result<(
         let tmp = GenericArray::from_mut_slice(tmp.as_mut());
         h.finalize_into(tmp);
         copy_slice(tmp.as_ref()).to(out);
-
         Ok(())
     })
 }