doc: module doc + readme

Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "tc_tea"
-version = "0.1.0"
+version = "0.1.1"
 authors = ["Jixun Wu <jixun.moe@gmail.com>"]
 edition = "2021"
 

LICENSE

@@ -0,0 +1 @@
+MIT OR Apache-2.0 license

README.md

@@ -16,16 +16,16 @@ Code implemented according to the spec described in
 Add the following to `[dependencies]` section in your `Cargo.toml` file:
 
 ```toml
-tc_tea = "0.1.0"
+tc_tea = "0.1.1"
 ```
 
-## Failures
+## Troubleshooting
 
-* Key size needs to be `>= 16` bytes.
-  * `None` will be returned in this case.
-  * Only first 16 bytes are used.
-* Encrypted size are always multiple of 8.
-  * `None` will be returned in this case.
+* Key need to have `16` bytes or more.
+  * `None` will be returned if less than `16` bytes provided.
+  * If more bytes were provided, only the first 16 bytes will be used.
+* Encrypted data should have a size that is multiple of 8.
+  * `None` will be returned if `encrypted_data.len() % 8 > 0`.
 
 ## Usage
 
@@ -44,7 +44,9 @@ fn hello_tc_tea() {
 
 Dual licensed under MIT OR Apache-2.0 license.
 
-`SPDX-License-Identifier: MIT OR Apache-2.0`
+```license
+SPDX-License-Identifier: MIT OR Apache-2.0
+```
 
 [tc_tea_cpp]: https://github.com/TarsCloud/TarsCpp/blob/a6d5ed8/util/src/tc_tea.cpp
 [tc_tea_spec]: https://github.com/iweizime/StepChanger/wiki/%E8%85%BE%E8%AE%AFTEA%E5%8A%A0%E5%AF%86%E7%AE%97%E6%B3%95

src/lib.rs

@@ -1,4 +1,5 @@
 //! _Tencent modified TEA_ (tc_tea) is a variant of the standard TEA (Tiny Encryption Algorithm).
+//!
 //! Notably, it uses a different round number and uses a "tweaked" CBC mode.
 
 mod stream_ext;

src/tc_tea.rs

@@ -8,6 +8,9 @@ const SALT_LEN: usize = 2;
 const ZERO_LEN: usize = 7;
 const FIXED_PADDING_LEN: usize = 1 + SALT_LEN + ZERO_LEN;
 
+/// Calculate expected size of encrypted data.
+///
+/// `body_size` is the size of data you'd like to encrypt.
 pub fn calc_encrypted_size(body_size: usize) -> usize {
     let len = FIXED_PADDING_LEN + body_size;
     let pad_len = (8 - (len & 0b0111)) & 0b0111;
@@ -15,13 +18,16 @@ pub fn calc_encrypted_size(body_size: usize) -> usize {
 }
 
 /// Encrypts an arbitrary length sized data in the following way:
+///
 /// * PadLen  (1 byte)
 /// * Padding (variable, 0-7byte)
 /// * Salt    (2 bytes)
 /// * Body    (? bytes)
 /// * Zero    (7 bytes)
-/// PadLen/Padding/Salt is random bytes. Minimum of 3 bytes.
-/// PadLen is taken from the last 3 bit of the first byte.
+///
+/// Returned bytes will always have a length multiple of 8.
+///
+/// PadLen/Padding/Salt are randomly bytes, with a minimum of 21 bits (3 * 8 - 3) randomness.
 ///
 /// # Panics
 ///
@@ -78,12 +84,13 @@ pub fn encrypt<T: AsRef<[u8]>, K: AsRef<[u8]>>(plaintext: T, key: K) -> Option<B
 }
 
 /// Decrypts a byte array containing the following:
+///
 /// * PadLen  (1 byte)
 /// * Padding (variable, 0-7byte)
 /// * Salt    (2 bytes)
 /// * Body    (? bytes)
 /// * Zero    (7 bytes)
-/// PadLen/Padding/Salt is random bytes. Minimum of 3 bytes.
+///
 /// PadLen is taken from the last 3 bit of the first byte.
 pub fn decrypt<T: AsRef<[u8]>, K: AsRef<[u8]>>(encrypted: T, key: K) -> Option<Box<[u8]>> {
     let encrypted = encrypted.as_ref();