Improve KMAC README

Author: hoxxep

kmac/README.md

@@ -2,7 +2,7 @@
 
 A rust implementation of [KMAC](https://en.wikipedia.org/wiki/SHA-3#Additional_instances), following the [NIST SP 800-185](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-185.pdf) specification.
 
-This crate provides KMAC implementations for KMAC128, KMAC256, KMACXOF128, and KMACXOF256.
+This crate provides implementations for KMAC128, KMAC256, KMACXOF128, and KMACXOF256. KMAC is a PRF and keyed hash function based on the Keccak (SHA-3) sponge construction, designed for message authentication (MAC) and key derivation (KDF).
 
 ## Examples
 
@@ -14,46 +14,46 @@ use kmac::{Kmac128, Mac, KeyInit};
 use hex_literal::hex;
 
 // Use KMAC128 to produce a MAC
-let mut mac = Kmac128::new_from_slice(b"key material").unwrap();
-mac.update(b"input message");
+let mut kmac = Kmac128::new_from_slice(b"key material").unwrap();
+kmac.update(b"input message");
 
 // `result` has type `CtOutput` which is a thin wrapper around array of
 // bytes for providing constant time equality check
-let result = mac.finalize();
+let result = kmac.finalize();
 
 // To get underlying array use `into_bytes`, but be careful, since
 // incorrect use of the code value may permit timing attacks which defeats
 // the security provided by the `CtOutput`
-let code_bytes = result.into_bytes();
+let mac_bytes = result.into_bytes();
 let expected = hex!("
     c39a8f614f8821443599440df5402787
     0f67e4c47919061584f14a616f3efcf5
 ");
-assert_eq!(code_bytes[..], expected[..]);
+assert_eq!(mac_bytes[..], expected[..]);
 ```
 
 ### Verifying a MAC
 ```rust
 use kmac::{Kmac128, Mac, KeyInit};
 use hex_literal::hex;
 
-let mut mac = Kmac128::new_from_slice(b"key material").unwrap();
-mac.update(b"input message");
+let mut kmac = Kmac128::new_from_slice(b"key material").unwrap();
+kmac.update(b"input message");
 
-let mac_code = hex!("
+let mac_bytes = hex!("
     c39a8f614f8821443599440df5402787
     0f67e4c47919061584f14a616f3efcf5
 ");
 
 // `verify_slice` will return `Ok(())` if code is correct, `Err(MacError)` otherwise
-mac.verify_slice(&mac_code).unwrap();
+kmac.verify_slice(&mac_bytes).unwrap();
 ```
 
 ### Producing a fixed-length output
 
-KMAC can also be used to produce an output of any length, and can be particularly useful as a [key-stretching function](https://en.wikipedia.org/wiki/Key_stretching).
+KMAC can also be used to produce an output of any length, which is particularly useful when KMAC is being used as a [key-derivation function (KDF)](https://en.wikipedia.org/wiki/Key_derivation_function).
 
-This method finalizes the KMAC and mixes the requested output length into the KMAC domain separation. That means the resulting bytes are dependent on the exact length of `out`. Use this when the output length is part of the MAC/derivation semantics (for example when the length itself must influence the MAC result).
+This method finalizes the KMAC and mixes the requested output length into the KMAC domain separation. The resulting bytes are dependent on the exact length of `out`. Use this when the output length is part of the MAC/derivation semantics (for example when the length itself must influence the MAC result).
 
 A customisation string can also be provided to further domain-separate different uses of KMAC with the same key when initialising the KMAC instance with `new_customization`.
 
@@ -83,9 +83,9 @@ The XOF variant finalizes the sponge state without binding the requested output
 use kmac::{Kmac256, Mac, ExtendableOutput, XofReader};
 use hex_literal::hex;
 
-let mut mac = Kmac256::new_customization(b"key material", b"customization").unwrap();
-mac.update(b"input message");
-let mut reader = mac.finalize_xof();
+let mut kmac = Kmac256::new_customization(b"key material", b"customization").unwrap();
+kmac.update(b"input message");
+let mut reader = kmac.finalize_xof();
 
 let mut output = [0u8; 32];
 reader.read(&mut output);