Minor doc improvements

Author: michaelklishin

.cargo/config.toml

@@ -0,0 +1,2 @@
+[doc]
+all-features = true

src/password_hashing.rs

@@ -11,6 +11,16 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
+
+//! Functions that calculate salted password hash values the same way RabbitMQ
+//! nodes do it.
+//!
+//! Use this module if you need to calculate a password hash for a `crate::requests::UserParams`
+//! object that you pass to [`crate::api::Client::create_user`] or [`crate::blocking_api::Client::create_user`].
+//!
+//! See the [Credentials and Passwords guide](https://rabbitmq.com/docs/passwords/).
+//!
+
 use rand::RngCore;
 use ring::digest::{Context, SHA256, SHA512};
 use std::fmt;
@@ -78,10 +88,19 @@ pub fn base64_encoded_salted_password_hash_sha512(salt: &[u8], password: &str) -
     base64_encoded_salted_password_hash(salt, password, &HashingAlgorithm::SHA512)
 }
 
+/// Supported hashing algorithms for password salting and hashing.
+///
+/// This enum represents the cryptographic hash algorithms that can be used
+/// for password hashing in RabbitMQ user management. SHA-256 is the default
+/// algorithm and is recommended for most use cases.
+///
+/// See the [Credentials and Passwords guide](https://rabbitmq.com/docs/passwords/).
 #[derive(Clone, Default, PartialEq, Eq, Hash, Debug)]
 pub enum HashingAlgorithm {
+    /// SHA-256 hashing algorithm (default)
     #[default]
     SHA256,
+    /// SHA-512 hashing algorithm
     SHA512,
     // Unlike RabbitMQ that accepts module implementations via configuration,
     // we cannot support salting and hashing for arbitrary algorithm names,
@@ -98,6 +117,13 @@ impl fmt::Display for HashingAlgorithm {
 }
 
 impl From<&str> for HashingAlgorithm {
+    /// Converts a string slice to a `HashingAlgorithm`.
+    ///
+    /// Supported string values (case-insensitive):
+    /// - "SHA256" or "SHA-256" → `HashingAlgorithm::SHA256`
+    /// - "SHA512" or "SHA-512" → `HashingAlgorithm::SHA512`
+    ///
+    /// Any other value defaults to `HashingAlgorithm::SHA256`.
     fn from(s: &str) -> Self {
         match s.to_uppercase().as_str() {
             "SHA256" => HashingAlgorithm::SHA256,
@@ -115,13 +141,43 @@ impl From<String> for HashingAlgorithm {
     }
 }
 
+/// Errors that can occur during password hashing operations.
 #[derive(Error, Debug)]
 pub enum HashingError {
+    /// The specified hashing algorithm is not supported.
     #[error("Provided algorithm is not supported")]
     UnsupportedAlgorithm,
 }
 
 impl HashingAlgorithm {
+    /// Generates a Base64-encoded, salted password hash from a clear text password value.
+    /// Use this function to produce a password hash to be passed to ``
+    ///
+    /// This method combines the salt with the password and applies the hash algorithm
+    /// specified by this enum variant, then returns the result as a Base64-encoded string.
+    ///
+    /// # Arguments
+    ///
+    /// * `salt`: a byte slice containing the salt to use for hashing
+    /// * `password`: the plaintext password to hash
+    ///
+    /// # Returns
+    ///
+    /// A `Result` containing either:
+    /// - `Ok(String)`: the Base64-encoded salted password hash
+    /// - `Err(HashingError)`: tn error if the algorithm is not supported
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use rabbitmq_http_client::password_hashing::{HashingAlgorithm, salt};
+    ///
+    /// let salt = salt();
+    /// let algorithm = HashingAlgorithm::SHA256;
+    /// let hash = algorithm.salt_and_hash(&salt, "a_cleartext_password").unwrap();
+    /// ```
+    ///
+    /// See the [Credentials and Passwords guide](https://rabbitmq.com/docs/passwords/).
     pub fn salt_and_hash(&self, salt: &[u8], password: &str) -> Result<String, HashingError> {
         Ok(base64_encoded_salted_password_hash(salt, password, self))
     }