docs(crypto::block): Better block documentation

src/crypto/block/blowfish.rs

@@ -1,6 +1,7 @@
 use std::iter::Iterator;
 
 use byteorder::{ByteOrder, BigEndian};
+use typenum::consts::U8;
 
 use super::{BlockEncrypt, BlockDecrypt};
 
@@ -299,9 +300,7 @@ impl Blowfish {
 }
 
 impl BlockEncrypt<u8> for Blowfish {
-    fn block_size() -> usize {
-        8
-    }
+    type BlockSize = U8;
 
     fn encrypt_block<I, O>(&self, input: I, mut output: O)
         where I: AsRef<[u8]>,
@@ -320,9 +319,7 @@ impl BlockEncrypt<u8> for Blowfish {
 }
 
 impl BlockDecrypt<u8> for Blowfish {
-    fn block_size() -> usize {
-        8
-    }
+    type BlockSize = U8;
 
     fn decrypt_block<I, O>(&self, input: I, mut output: O)
         where I: AsRef<[u8]>,

src/crypto/block/mod.rs

@@ -1,19 +1,38 @@
 //! Block cryptosystems
 
+use generic_array::ArrayLength;
+use typenum::uint::Unsigned;
+
 #[cfg(feature = "blowfish")]
 pub mod blowfish;
 
+/// Block encryptor definition
 pub trait BlockEncrypt<T> {
-    fn block_size() -> usize;
+    /// Single block size
+    type BlockSize: Unsigned + ArrayLength<u8>;
+
+    /// Single block size
+    fn block_size() -> usize {
+        Self::BlockSize::to_usize()
+    }
 
+    /// Encrypt single block of data
     fn encrypt_block<I, O>(&self, input: I, output: O)
         where I: AsRef<[T]>,
               O: AsMut<[T]>;
 }
 
+/// Block decryptor definition
 pub trait BlockDecrypt<T> {
-    fn block_size() -> usize;
+    /// Single block size
+    type BlockSize: Unsigned + ArrayLength<u8>;
+
+    /// Single block size
+    fn block_size() -> usize {
+        Self::BlockSize::to_usize()
+    }
 
+    /// Decrypt single block of data
     fn decrypt_block<I, O>(&self, input: I, output: O)
         where I: AsRef<[T]>,
               O: AsMut<[T]>;

src/digest/mod.rs

@@ -9,8 +9,12 @@
 //! > - it is infeasible to modify a message without changing the hash
 //! > - it is infeasible to find two different messages with the same hash.
 //!
-//! **WARNING**: If you want to use one of this functions as password hash then
-//! you are evil human being and I really hope that I'm not using any of your services.
+//! # WARNING
+//!
+//! Under any circumstances you should not use this functions to hash users passwords. Instead you
+//! should check [`octavo::kdf`][kdf] module.
+//!
+//! [kdf]: /octavo/kdf/ "Key Derivation Functions"
 //!
 //! # Example
 //!
@@ -52,12 +56,15 @@ pub trait Digest: Clone {
     /// Update digest with data.
     fn update<T>(&mut self, input: T) where T: AsRef<[u8]>;
 
+    /// Output size in bits
     fn output_bits() -> usize {
         Self::OutputBits::to_usize()
     }
+    /// Output size in bytes
     fn output_bytes() -> usize {
         Self::OutputBytes::to_usize()
     }
+    /// Block size in bytes
     fn block_size() -> usize {
         Self::BlockSize::to_usize()
     }