added docs and callout

Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-description = "Simple library to pluralize words"
+description = "Simple library to pluralize English words"
 edition = "2021"
 include = ["src/**/*", "LICENSE", "README.md"]
 license = "Apache-2.0"

README.md

@@ -2,6 +2,11 @@
 
 A simple library to pluralize words.
 
+> [!NOTE]
+> This library is intended for the English language.
+> It may work with other languages that follow the convention of adding an 's' to the end of words,
+> but for most languages a custom implementation will be required.
+
 ## Usage
 
 ```rust

src/form.rs

@@ -1,6 +1,20 @@
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+#[non_exhaustive]
+#[allow(clippy::module_name_repetitions)]
+/// An enum determining the plural form of a word.
+///
+/// This currently supports two forms:
+///
+/// - `AppendS`: Appends an `s` to the end of the word.
+/// - `Custom`: A custom form provided by the user.
+///
+/// This may change in future hence the `#[non_exhaustive]` attribute.
 pub enum PluralForm {
+    /// Append an 's' to the end of the word
     AppendS,
+    /// A custom form provided by the user
+    ///
+    /// This will simply be passed to the formatter.
     Custom(String),
 }
 

src/plural.rs

@@ -3,40 +3,53 @@ use std::fmt::Display;
 use super::PluralForm;
 
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+#[must_use]
+/// Provides a wrapper that implements the [`Pluralize`] trait.
 pub struct Plural<'w> {
     pub(crate) word: &'w str,
     pub(crate) form: PluralForm,
 }
 
 impl<'w> Plural<'w> {
+    /// Construct a new [`Plural`] instance.
     pub const fn new(word: &'w str) -> Self {
         Self {
             word,
             form: PluralForm::const_default(),
         }
     }
 
+    /// Construct a new [`Plural`] instance with a custom form.
     pub const fn new_with_form(word: &'w str, form: PluralForm) -> Self {
         Self { word, form }
     }
 
+    /// Assign a plural form to the [`Plural`] instance.
     pub fn with_form(self, form: PluralForm) -> Self {
         Self {
             word: self.word,
             form,
         }
     }
 
+    #[must_use]
+    /// Get the word that is being pluralized.
     pub const fn word(&self) -> &str {
         self.word
     }
 
+    #[must_use]
+    /// Determine the plural form of the word.
     pub const fn form(&self) -> &PluralForm {
         &self.form
     }
 }
 
+/// Trait providing methods for the pluralization of words.
+///
+/// This does not handle the implementation itself.
 pub trait Pluralize {
+    /// Get the plural form of the word.
     fn plural(&self) -> String;
 }