Add some basic high level docs

src/aes.rs

@@ -4,6 +4,11 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+/*!
+AES EBC, CBC, and CTR modes
+
+*/
+
 #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
 use aesni;
 

src/aes_gcm.rs

@@ -4,6 +4,11 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+/*!
+The AES cipher using Galois-Counter key mode. This provides authenticated encryption. 
+
+*/
+
 use aes::{ctr, KeySize};
 use aead::{AeadEncryptor,AeadDecryptor};
 use cryptoutil::copy_memory;

src/aesni.rs

@@ -4,6 +4,11 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+/*!
+AES New Instruction functions for hardware accelerated usage.
+
+*/
+
 use aes::KeySize;
 use aes::KeySize::{KeySize128, KeySize192, KeySize256};
 use symmetriccipher::{BlockEncryptor, BlockDecryptor};

src/blowfish.rs

@@ -4,6 +4,11 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+/*!
+The Blowfish block cipher. Key sizes from 32 to 448 bits (4 - 56 bytes) are supported.
+
+*/
+
 use cryptoutil::{read_u32v_be, write_u32_be};
 use symmetriccipher::{BlockEncryptor, BlockDecryptor};
 use step_by::RangeExt;

src/chacha20.rs

@@ -3,6 +3,12 @@
 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
+
+/*!
+An enchanced version of the Salsa20 cipher. Common as an AES replacement for machines lacking AES hardware acceleration.
+
+*/
+
 use std::cmp;
 
 use buffer::{BufferResult, RefReadBuffer, RefWriteBuffer};

src/chacha20poly1305.rs

@@ -4,6 +4,11 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+/*!
+An authenticated version of the ChaCha20 cipher. Used in TLS 1.2 and standardized in RFC7539.
+
+*/
+
 use aead::{AeadEncryptor,AeadDecryptor};
 
 use chacha20::ChaCha20;

src/md5.rs

@@ -8,6 +8,11 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+/*!
+The MD5 hashing function. No longer considered secure, but present for compatability.
+
+*/
+
 use cryptoutil::{write_u32_le, read_u32v_le, FixedBuffer, FixedBuffer64, StandardPadding};
 use digest::Digest;
 use step_by::RangeExt;

src/salsa20.rs

@@ -4,6 +4,11 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+/*!
+A stream cipher built on the add-rotate-xor (ARX) model. The predecessor to ChaCha20.
+
+*/
+
 use buffer::{BufferResult, RefReadBuffer, RefWriteBuffer};
 use symmetriccipher::{Encryptor, Decryptor, SynchronousStreamCipher, SymmetricCipherError};
 use cryptoutil::{read_u32_le, symm_enc_or_dec, write_u32_le, xor_keystream};