some doc updates

1 files changed, 16 insertions, 14 deletions

diff --git a/src/lib.rs b/src/lib.rs
index e6c0c8d..205f98b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -22,27 +22,27 @@
 //! # AEZ encryption (for laypeople)
 //!
 //! The security property of encryption schemes says that an adversary without key must not learn
-//! the content of a message, but the adversary might still be able to modify the message. For
-//! example, in AES-CTR, flipping a bit in the ciphertext means that the same bit will be flipped
-//! in the plaintext once the message is decrypted.
+//! the content of a message. However, the adversary might still be able to modify the message. For
+//! example, in AES-CTR (or other stream ciphers), flipping a bit in the ciphertext means that the
+//! same bit will be flipped in the plaintext once the message is decrypted. This allows for
+//! "planned" changes.
 //!
 //! Authenticated encryption solves this problem by including a mechanism to detect changes. This
 //! can be done for example by including a MAC, or using a mode like GCM (Galois counter mode). In
-//! many cases, not only the integrity of the ciphertext can be verified, but additional data can
-//! be provided during encryption and decryption which will also be included in the integrity
-//! check. This results in an *authenticated encryption with associated data* scheme, AEAD for
+//! many cases, not only the integrity of the ciphertext can be verified, but the user can provide
+//! additional data during encryption and decryption which will also have its integrity be
+//! verified. This is called an *authenticated encryption with associated data* scheme, AEAD for
 //! short.
 //!
 //! AEZ employs a nifty technique in order to realize an AEAD scheme: The core of AEZ is an
-//! enciphering scheme, which in addition to "hiding" its input is also very "unpredictable",
-//! similar to a hash function. That means that if a ciphertext is changed slightly (by flipping a
-//! bit), the resulting plaintext will be unpredictably and completely different.
+//! enciphering scheme, which in addition to "hiding" its input is also very "unpredictable" when
+//! bits are flipped. Similar to a hash function, if the ciphertext is changed slightly (by
+//! flipping a bit), the resulting plaintext will be unpredictably and completely different.
 //!
 //! With this property, authenticated encryption can be realized implicitly: The message is padded
 //! with a known string before enciphering it. If, after deciphering, this known string is not
-//! present, the message has been tampered with. Since the enciphering scheme is parametrized by
-//! the key, a nonce and arbitrary additional data, we can verify the integrity of associated data
-//! as well.
+//! present, the message has been tampered with. Since the enciphering is parametrized by the key,
+//! a nonce and arbitrary additional data, we can verify the integrity of associated data as well.
 //!
 //! # Other implementations
 //!
@@ -126,6 +126,8 @@ enum Mode {
 }
 
 /// AEZ encryption scheme.
+///
+/// See the [module level documentation](index.html) for more information.
 pub struct Aez {
     key_i: Block,
     key_j: Block,
@@ -172,7 +174,7 @@ impl Aez {
     /// Parameters:
     ///
     /// * `nonce` -- the nonce to use. Each nonce should only be used once, as re-using the nonce
-    ///   (without chaning the key) will lead to the same ciphertext being produced, potentially
+    ///   (without changing the key) will lead to the same ciphertext being produced, potentially
     ///   making it re-identifiable.
     /// * `associated_data` -- additional data to be included in the integrity check. Note that
     ///   this data will *not* be contained in the ciphertext, but it must be provided on
@@ -181,7 +183,7 @@ impl Aez {
     ///   16` gives 128 bits of security. Passing a value of 0 is valid and leads to no integrity
     ///   checking.
     /// * `data` -- actual data to encrypt. Can be empty, in which case the returned ciphertext
-    ///   provides a "hash" that verifies the integrity of the associated data will be
+    ///   provides a "hash" that verifies the integrity of the associated data.
     ///
     /// Returns the ciphertext, which will be of length `data.len() + tau`.
     pub fn encrypt(