update the documentation slightly

Author: tmthecoder

src/hotp.rs

@@ -4,7 +4,9 @@ use crate::util::{base32_decode, get_code, hash_generic, MacDigest};
 
 /// A HOTP Generator
 ///
-/// Follows the specification listed in [RFC4226]. Needs a secret and a number of digits on initialization.
+/// Follows the specification listed in [RFC4226]. Needs a secret and
+/// digit count on initialization.
+///
 /// The HOTP can then be generated using [`HOTP::get_otp`].
 ///
 /// # Example
@@ -20,8 +22,8 @@ use crate::util::{base32_decode, get_code, hash_generic, MacDigest};
 pub struct HOTP {
     /// The secret key used in the HMAC process.
     ///
-    /// Often given as a Base32 key, which can be conveniently initialize using
-    /// the [`HOTP::from_base32`] constructors.
+    /// Often given as a Base32 key, which can be conveniently initialized
+    /// using the [`HOTP::default_from_base32`] constructor.
     secret: Vec<u8>,
 
     /// The number of digits of the code generated.
@@ -33,7 +35,7 @@ pub struct HOTP {
 /// All initializer implementations for the [`HOTP`] struct.
 impl HOTP {
     /// Creates a new HOTP instance with a byte-array representation
-    /// of the secret and the number of digits.
+    /// of the secret and specified digit count.
     ///
     /// Since only SHA1 was specified in the reference implementation and
     /// RFC specification, there's no need to initialize with a digest object.
@@ -44,40 +46,47 @@ impl HOTP {
         }
     }
 
-    /// Creates a new HOTP instance from an utf8-encoded string secret and the number of digits.
+    /// Creates a new HOTP instance from a utf8-encoded string secret
+    /// and specified digit count.
     pub fn new_from_utf8(secret: &str, digits: u32) -> Self {
         HOTP::new(secret.as_bytes(), digits)
     }
 
-    /// Creates a new HOTP instance from a base32-encoded string secret and the number of digits.
+    /// Creates a new HOTP instance from a base32-encoded string secret
+    /// and specified digit count.
     ///
     /// # Panics
-    /// This method panics if the provided string is not correctly base32 encoded.
+    /// This method panics if the provided string is not correctly
+    /// base32-encoded.
     pub fn new_from_base32(secret: &str, digits: u32) -> Self {
         let decoded = base32_decode(secret).expect("Failed to decode base32 string");
         HOTP::new(&decoded, digits)
     }
 
-    /// Creates a new HOTP instance from a byte-array representation of the secret and
-    /// a default number of 6 digits.
+    /// Creates a new HOTP instance from a byte-array representation of
+    /// the secret and a default digit count of 6.
     pub fn default_from_secret(secret: &[u8]) -> Self {
         HOTP::new(secret, 6)
     }
 
-    /// Creates a new HOTP instance from an utf8-encoded string secret and a default number of 6 digits.
+    /// Creates a new HOTP instance from an utf8-encoded string secret
+    /// and a default digit count of 6..
     pub fn default_from_utf8(secret: &str) -> Self {
         HOTP::new_from_utf8(secret, 6)
     }
 
-    /// Creates a new HOTP instance from a base32-encoded string secret and a default number of 6 digits.
+    /// Creates a new HOTP instance from a base32-encoded string secret
+    /// and a default digit count of 6..
     ///
     /// # Panics
-    /// This method panics if the provided string is not correctly base32 encoded.
+    /// This method panics if the provided string is not correctly
+    /// base32-encoded.
     pub fn default_from_base32(secret: &str) -> Self {
         HOTP::new_from_base32(secret, 6)
     }
 }
 
+/// All getters for the ['HOTP'] struct
 impl HOTP {
     /// Gets the number of digits of the code.
     pub fn get_digits(&self) -> u32 {

src/totp.rs

@@ -4,6 +4,7 @@ use crate::util::{base32_decode, get_code, hash_generic, MacDigest};
 ///
 /// Follows the specification listed in [RFC6238]. Needs a secret,
 /// a digest algorithm, a number of digits and a period on initialization.
+///
 /// The TOTP can then be generated using [`TOTP::get_otp`] or
 /// [`TOTP::get_otp_with_custom_time_start`].
 ///
@@ -19,13 +20,14 @@ use crate::util::{base32_decode, get_code, hash_generic, MacDigest};
 pub struct TOTP {
     /// The secret key used in the HMAC process.
     ///
-    /// Often given as a Base32 key, which can be conveniently initialized using
-    /// [`TOTP::default_from_base32`] constructors.
+    /// Often given as a Base32 key, which can be conveniently initialized
+    /// using the [`TOTP::default_from_base32`] constructor.
     secret: Vec<u8>,
 
     /// The digest to use in the HMAC process.
     ///
-    /// This value defaults to [`MacDigest::SHA1`] if not specified in a constructor.
+    /// This value defaults to [`MacDigest::SHA1`] if not specified in a
+    /// constructor.
     mac_digest: MacDigest,
 
     /// The number of digits of the code generated.
@@ -39,10 +41,11 @@ pub struct TOTP {
     period: u64,
 }
 
-// All initializer implementations for the [`TOTP`] struct
+/// All initializer implementations for the [`TOTP`] struct
 impl TOTP {
-    /// Generates a new TOTP instance from a byte array representation of the secret,
-    /// a digest algorithm, a number of digits and a period in seconds.
+    /// Generates a new TOTP instance from a byte array representation of the
+    /// secret, a digest algorithm, a number of digits,
+    /// and a period in seconds.
     pub fn new(secret: &[u8], mac_digest: MacDigest, digits: u32, period: u64) -> Self {
         TOTP {
             secret: secret.to_vec(),
@@ -52,14 +55,16 @@ impl TOTP {
         }
     }
 
-    /// Generates a new TOTP instance from an utf8 representation of the secret,
-    /// a digest algorithm, a number of digits and a period in seconds.
+    /// Generates a new TOTP instance from an utf8 representation of the
+    /// secret, a digest algorithm, a number of digits,
+    /// and a period in seconds.
     pub fn new_from_utf8(secret: &str, mac_digest: MacDigest, digits: u32, period: u64) -> Self {
         TOTP::new(secret.as_bytes(), mac_digest, digits, period)
     }
 
-    /// Generates a new TOTP instance from a base32 representation of the secret,
-    /// a digest algorithm, a number of digits and a period in seconds.
+    /// Generates a new TOTP instance from a base32-encoded representation of
+    /// the secret, a digest algorithm, a number of digits,
+    /// and a period in seconds.
     ///
     /// # Panics
     /// This method panics if the provided string is not correctly base32 encoded.
@@ -68,56 +73,59 @@ impl TOTP {
         TOTP::new(&decoded, mac_digest, digits, period)
     }
 
-    /// Creates a new TOTP instance with a byte-array representation of the secret.
+    /// Creates a new TOTP instance with a byte-array representation of the
+    /// secret.
     ///
-    /// Defaults to using [`MacDigest::SHA1`] as the digest for HMAC operations,
-    /// 6 digits and a 30 seconds period.
+    /// Defaults to using [`MacDigest::SHA1`] as the digest for HMAC
+    /// operations, with a 6-digit OTP output and a 30-second period.
     pub fn default_from_secret(secret: &[u8]) -> Self {
         TOTP::default_from_secret_with_digest(secret, MacDigest::SHA1)
     }
 
-    /// Creates a new TOTP instance with a byte-array representation of the secret and
-    /// a digest algorithm.
+    /// Creates a new TOTP instance with a byte-array representation of the
+    /// secret and a digest algorithm.
     ///
-    /// Defaults to using 6 digits and a 30 seconds period.
+    /// Defaults to a 6-digit OTP output and a 30-second period.
     pub fn default_from_secret_with_digest(secret: &[u8], mac_digest: MacDigest) -> Self {
         TOTP::new(secret, mac_digest, 6, 30)
     }
 
     /// Creates a new TOTP instance with an utf8 representation of the secret.
     ///
-    /// Defaults to using [`MacDigest::SHA1`] as the digest for HMAC operations,
-    /// 6 digits and a 30 seconds period.
+    /// Defaults to using [`MacDigest::SHA1`] as the digest for HMAC
+    /// operations, with a 6-digit OTP output and a 30-second period.
     pub fn default_from_utf8(secret: &str) -> Self {
         TOTP::default_from_utf8_with_digest(secret, MacDigest::SHA1)
     }
 
     /// Creates a new TOTP instance with an utf8 representation of the secret and
     /// a digest algorithm.
     ///
-    /// Defaults to using 6 digits and a 30 seconds period.
+    /// Defaults to a 6-digit OTP output and a 30-second period.
     pub fn default_from_utf8_with_digest(secret: &str, mac_digest: MacDigest) -> Self {
         TOTP::new_from_utf8(secret, mac_digest, 6, 30)
     }
 
     /// Creates a new TOTP instance with a base32 representation of the secret.
     ///
-    /// Defaults to using [`MacDigest::SHA1`] as the digest for HMAC operations,
-    /// 6 digits and a 30 seconds period.
+    /// Defaults to using [`MacDigest::SHA1`] as the digest for HMAC
+    /// operations, with a 6-digit OTP output and a 30-second period.
     ///
     /// # Panics
-    /// This method panics if the provided string is not correctly base32 encoded.
+    /// This method panics if the provided string is not correctly
+    /// base32-encoded.
     pub fn default_from_base32(secret: &str) -> Self {
         TOTP::default_from_base32_with_digest(secret, MacDigest::SHA1)
     }
 
-    /// Creates a new TOTP instance with a base32 representation of the secret and
-    /// a digest algorithm.
+    /// Creates a new TOTP instance with a base32 representation of the secret
+    /// and a digest algorithm.
     ///
-    /// Defaults to using 6 digits and a 30 seconds period.
+    /// Defaults to a 6-digit OTP output and a 30-second period.
     ///
     /// # Panics
-    /// This method panics if the provided string is not correctly base32 encoded.
+    /// This method panics if the provided string is not correctly
+    /// base32-encoded.
     pub fn default_from_base32_with_digest(secret: &str, mac_digest: MacDigest) -> Self {
         TOTP::new_from_base32(secret, mac_digest, 6, 30)
     }
@@ -135,7 +143,7 @@ impl TOTP {
         self.digits
     }
 
-    /// Gets the period between different generated code.
+    /// Gets the period between code changes.
     pub fn get_period(&self) -> u64 {
         self.period
     }
@@ -145,18 +153,20 @@ impl TOTP {
 impl TOTP {
     /// Generates and returns the TOTP value for the specified time.
     ///
-    /// The time must be specified in seconds to calculate the correct one-time password.
+    /// The time must be specified in seconds to calculate the correct
+    /// one-time password.
     ///
     /// # Panics
-    /// This method panics if the called [`TOTP::get_otp_with_custom_time_start`] method
-    /// does, which would happen if the hash's secret is incorrectly given.
+    /// This method panics if the [`TOTP::get_otp_with_custom_time_start`]
+    /// method does, which happens if the hash's secret is incorrectly given.
     pub fn get_otp(&self, time: u64) -> u32 {
         self.get_otp_with_custom_time_start(time, 0)
     }
 
     /// Generates and returns the TOTP value for the specified time.
     ///
-    /// The time must be specified in seconds to calculate the correct one-time password.
+    /// The time must be specified in seconds to calculate the correct
+    /// one-time password.
     ///
     /// This method allows a custom start time to be provided.
     ///

src/util.rs

@@ -19,7 +19,6 @@ use crate::totp::TOTP;
 /// may not support other digest algorithms.
 ///
 /// [RFC6238]: https://datatracker.ietf.org/doc/html/rfc6238
-
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 #[cfg_attr(feature = "ffi", repr(C))]
 pub enum MacDigest {
@@ -77,7 +76,11 @@ pub(crate) fn base32_decode(data: &str) -> Option<Vec<u8>> {
 
 /// Result of an otpauth URI parsing.
 ///
-/// It's either a TOTP or a HOTP with its current counter.
+/// As the URI can return either an [HOTP] or [TOTP] instance,
+/// this enum is returned as a wrapper around both types.
+///
+/// If an [HOTP] instance is returned, a second value is returned
+/// signifying the counter's value.
 #[derive(Debug)]
 #[cfg_attr(feature = "ffi", repr(C))]
 pub enum ParseResult {
@@ -86,6 +89,10 @@ pub enum ParseResult {
 }
 
 /// Different error types of the optauth URI parsing.
+///
+/// Represents each error that could occur while parsing the otpauth URI
+/// in an enum. The returned error may have an associated message or
+/// [url::ParseError] with more information
 #[derive(Debug)]
 #[cfg_attr(feature = "ffi", repr(C))]
 pub enum ParseError {
@@ -102,8 +109,13 @@ pub enum ParseError {
     InvalidPeriod(String),
 }
 
-/// Parses an otpauth URI, which is the string format of the QR codes usually given by platforms for TOTP.
-/// This method is safe and shouldn't panic.
+/// Parses an otpauth URI.
+///
+/// This is generally the string format of QR codes provided by
+/// authentication services
+///
+/// This method is safe and shouldn't panic. It will return an error if the
+/// provided uri is invalid.
 pub fn parse_otpauth_uri(uri: &str) -> Result<ParseResult, ParseError> {
     use ParseError::*;