Fix/issue 9

.gitignore

@@ -1,2 +1,4 @@
 /target
 /.vscode
+
+.DS_Store

src/lib.rs

@@ -2,10 +2,16 @@
 /// Elliptic curve backend
 use tiny_ed448_goldilocks::curve::{extended_edwards::ExtendedPoint, field::scalar::Scalar};
 
-/// Module for sha3 primitives.
+/// Module for SHA-3 primitives
 pub mod sha3 {
+
+    // Submodule that implements NIST 800-185 compliant functions
     pub mod aux_functions;
+
+    // Submodule that implements the Keccak-f[1600] permutation
     pub mod keccakf;
+
+    // Submodule that implements the sponge construction
     pub mod sponge;
 }
 
@@ -61,18 +67,26 @@ pub struct KeyPair {
 }
 
 #[derive(Debug)]
-/// Message type for which cryptographic traits are defined.
+/// Message struct for which cryptographic traits are defined.
 pub struct Message {
+    // Input message
     pub msg: Box<Vec<u8>>,
+    // The digest lengths in FIPS-approved hash functions
     pub d: Option<SecParam>,
+    // Nonce used in symmetric encryption
     pub sym_nonce: Option<Vec<u8>>,
+    // Nonce used in asymmetric encryption
     pub asym_nonce: Option<ExtendedPoint>,
+    // Hash value (also known as message digest)
     pub digest: Result<Vec<u8>, OperationError>,
+    // Result of the cryptographic trait
     pub op_result: Result<(), OperationError>,
+    // Schnorr signatures on the input message
     pub sig: Option<Signature>,
 }
 
 impl Message {
+    // Returns a new Message instance
     pub fn new(data: Vec<u8>) -> Message {
         Message {
             msg: Box::new(data),
@@ -92,10 +106,15 @@ impl Message {
 //     }
 // }
 #[derive(Debug, Clone, Copy)]
+/// An enum representing standard digest lengths based on FIPS PUB 202
 pub enum SecParam {
+    /// Digest length of 224 bits, also known as SHA3-224
     D224 = 224,
+    /// Digest length of 256 bits, also known as SHA3-256
     D256 = 256,
+    /// Digest length of 384 bits, also known as SHA3-384
     D384 = 384,
+    /// Digest length of 512 bits, also known as SHA3-512
     D512 = 512,
 }
 
@@ -117,14 +136,21 @@ impl SecParam {
 }
 
 #[derive(Debug, Clone, Copy)]
+/// An enum representing standard capacity valuess based on FIPS PUB 202.
+/// (The capacity of a sponge function) = 2 * (digest length)
 pub(crate) enum Capacity {
+    // 2 * SecParam.D224
     C448 = 448,
+    // 2 * SecParam.D256
     C512 = 512,
+    // 2 * SecParam.D384
     C768 = 768,
+    // 2 * SecParam.D512
     C1024 = 1024,
 }
 
 impl Capacity {
+    /// This function effectively maps a given bit length to the appropriate capacity value enum variant,
     fn from_bit_length(bit_length: u64) -> Self {
         match bit_length * 2 {
             x if x <= 448 => Capacity::C448,
@@ -135,6 +161,7 @@ impl Capacity {
     }
 }
 
+/// OutputLength struct for storing the output length.
 pub struct OutputLength {
     value: u64,
 }
@@ -155,11 +182,14 @@ impl OutputLength {
     }
 }
 
+/// Rate struct for storing the rate value.
+/// Rate is the number of input bits processed per invocation of the underlying function in sponge construction.
 pub struct Rate {
     value: u64,
 }
 
 impl Rate {
+    // Rate = (Permutation width) - (Capacity)
     pub fn from<R: BitLength + ?Sized>(sec_param: &R) -> Self {
         Rate {
             value: (1600 - sec_param.bit_length()),
@@ -207,6 +237,11 @@ pub trait BitLength {
 }
 
 pub trait Hashable {
+    /// # Message Digest
+    /// Computes SHA3-d hash of input.
+    /// ## Arguments:
+    /// * `d: u64`: requested security strength in bits. Supported
+    /// bitstrengths are 224, 256, 384, or 512.
     fn compute_hash_sha3(&mut self, d: &SecParam) -> Result<(), OperationError>;
     fn compute_tagged_hash(&mut self, pw: &[u8], s: &str, d: &SecParam);
 }