add to and fix docs for hash io-traits impls

src/hazardous/hash/blake2/blake2b.rs

@@ -171,6 +171,16 @@ impl Hasher {
 /// ```
 #[cfg(feature = "safe_api")]
 impl io::Write for Blake2b {
+    /// Update the hasher's internal state with *all* of the bytes given.
+    /// If this function returns the `Ok` variant, it's guaranteed that it
+    /// will contain the length of the buffer passed to [`Write`](std::io::Write).
+    /// Note that this function is just a small wrapper over
+    /// [`Blake2b::update`](crate::hazardous::hash::blake2::blake2b::Blake2b::update).
+    ///
+    /// ## Errors:
+    /// This function will only ever return the [`std::io::ErrorKind::Other`]()
+    /// variant when it returns an error. Additionally, this will always contain Orion's
+    /// [`UnknownCryptoError`](crate::errors::UnknownCryptoError) type.
     fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
         self.update(bytes)
             .map_err(|e| io::Error::new(io::ErrorKind::Other, e))?;

src/hazardous/hash/sha2/sha256.rs

@@ -233,7 +233,7 @@ impl crate::hazardous::mac::hmac::HmacHashFunction for Sha256 {
 }
 
 #[cfg_attr(docsrs, doc(cfg(feature = "safe_api")))]
-/// Example: hashing from a `Read`er with SHA256.
+/// Example: hashing from a [`Read`](std::io::Read)er with SHA256.
 /// ```rust
 /// use orion::{
 ///     hazardous::hash::sha2::sha256::{Sha256, Digest},
@@ -252,6 +252,16 @@ impl crate::hazardous::mac::hmac::HmacHashFunction for Sha256 {
 /// ```
 #[cfg(feature = "safe_api")]
 impl io::Write for Sha256 {
+    /// Update the hasher's internal state with *all* of the bytes given.
+    /// If this function returns the `Ok` variant, it's guaranteed that it
+    /// will contain the length of the buffer passed to [`Write`](std::io::Write).
+    /// Note that this function is just a small wrapper over
+    /// [`Sha256::update`](crate::hazardous::hash::sha2::sha256::Sha256::update).
+    ///
+    /// ## Errors:
+    /// This function will only ever return the [`std::io::ErrorKind::Other`]()
+    /// variant when it returns an error. Additionally, this will always contain Orion's
+    /// [`UnknownCryptoError`](crate::errors::UnknownCryptoError) type.
     fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
         self.update(bytes)
             .map_err(|e| io::Error::new(io::ErrorKind::Other, e))?;

src/hazardous/hash/sha2/sha384.rs

@@ -213,7 +213,7 @@ impl crate::hazardous::mac::hmac::HmacHashFunction for Sha384 {
 }
 
 #[cfg_attr(docsrs, doc(cfg(feature = "safe_api")))]
-/// Example: hashing from a `Read`er with SHA384.
+/// Example: hashing from a [`Read`](std::io::Read)er with SHA384.
 /// ```rust
 /// use orion::{
 ///     hazardous::hash::sha2::sha384::{Sha384, Digest},
@@ -232,6 +232,16 @@ impl crate::hazardous::mac::hmac::HmacHashFunction for Sha384 {
 /// ```
 #[cfg(feature = "safe_api")]
 impl io::Write for Sha384 {
+    /// Update the hasher's internal state with *all* of the bytes given.
+    /// If this function returns the `Ok` variant, it's guaranteed that it
+    /// will contain the length of the buffer passed to [`Write`](std::io::Write).
+    /// Note that this function is just a small wrapper over
+    /// [`Sha384::update`](crate::hazardous::hash::sha2::sha384::Sha384::update).
+    ///
+    /// ## Errors:
+    /// This function will only ever return the [`std::io::ErrorKind::Other`]()
+    /// variant when it returns an error. Additionally, this will always contain Orion's
+    /// [`UnknownCryptoError`](crate::errors::UnknownCryptoError) type.
     fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
         self.update(bytes)
             .map_err(|e| io::Error::new(io::ErrorKind::Other, e))?;

src/hazardous/hash/sha2/sha512.rs

@@ -236,7 +236,7 @@ impl crate::hazardous::mac::hmac::HmacHashFunction for Sha512 {
 }
 
 #[cfg_attr(docsrs, doc(cfg(feature = "safe_api")))]
-/// Example: hashing from a `Read`er with SHA512.
+/// Example: hashing from a [`Read`](std::io::Read)er with SHA512.
 /// ```rust
 /// use orion::{
 ///     hazardous::hash::sha2::sha512::{Sha512, Digest},
@@ -255,6 +255,16 @@ impl crate::hazardous::mac::hmac::HmacHashFunction for Sha512 {
 /// ```
 #[cfg(feature = "safe_api")]
 impl io::Write for Sha512 {
+    /// Update the hasher's internal state with *all* of the bytes given.
+    /// If this function returns the `Ok` variant, it's guaranteed that it
+    /// will contain the length of the buffer passed to [`Write`](std::io::Write).
+    /// Note that this function is just a small wrapper over
+    /// [`Sha512::update`](crate::hazardous::hash::sha2::sha512::Sha512::update).
+    ///
+    /// ## Errors:
+    /// This function will only ever return the [`std::io::ErrorKind::Other`]()
+    /// variant when it returns an error. Additionally, this will always contain Orion's
+    /// [`UnknownCryptoError`](crate::errors::UnknownCryptoError) type.
     fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
         self.update(bytes)
             .map_err(|e| io::Error::new(io::ErrorKind::Other, e))?;

src/high_level/hash.rs

@@ -79,19 +79,24 @@ pub fn digest(data: &[u8]) -> Result<Digest, UnknownCryptoError> {
     blake2b::Hasher::Blake2b256.digest(data)
 }
 
-/// Hash data from `impl Read` using BLAKE2b-256.
+/// Hash data from a [`Read`](std::io::Read)` type using BLAKE2b-256.
 ///
 /// See the [module-level docs](crate::hash) for an example of how to use this function.
-/// Internally calls `std::io::copy()` to move data from the reader into the Blake2b writer.
-/// The `std::io::copy` function buffers reads, so passing in a `BufReader` may be unnecessary.
+/// Internally calls [`std::io::copy`]() to move data from the reader into the Blake2b writer.
+/// Note that the [`std::io::copy`]() function buffers reads, so passing in a
+/// [`BufReader`](std::io::BufReader) may be unnecessary.
 ///
 /// For lower-level control over reads, writes, buffer sizes, *etc.*, consider using the
 /// [`Blake2b`](crate::hazardous::hash::blake2::blake2b::Blake2b) type and its
-/// [`Write`](std::io::Write) implementation directly. See the Blake2b type's source code
-/// for an example.
+/// [`Write`](std::io::Write) implementation directly. See `Blake2b`'s `Write` implementation
+/// and/or its `Write` documentation for an example.
 ///
-/// Note that if an error is returned, data may still have been consumed
-/// from the given reader.
+/// ## Errors:
+/// This function will only ever return the [`std::io::ErrorKind::Other`]()
+/// variant when it returns an error. Additionally, this will always contain Orion's
+/// [`UnknownCryptoError`](crate::errors::UnknownCryptoError) type.
+///
+/// Note that if an error is returned, data may still have been consumed from the given reader.
 #[cfg(feature = "safe_api")]
 #[must_use = "SECURITY WARNING: Ignoring a Result can have real security implications."]
 pub fn digest_from_reader(mut reader: impl std::io::Read) -> Result<Digest, UnknownCryptoError> {