docs: Improve the docs

Signed-off-by: Awiteb <a@4rs.nl>

Cargo.toml

@@ -26,6 +26,10 @@ either = { version = "1.13.0", default-features = false }
 cacache-storage = ["dep:cacache"]
 simple_generator = ["dep:captcha"]
 
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
 [dev-dependencies]
 tempfile = "3.9"
 tokio = { version = "1.35", features = ["macros", "rt-multi-thread"] }

src/captcha_gen/mod.rs

@@ -12,7 +12,8 @@
 #[cfg(feature = "simple_generator")]
 mod simple_generator;
 
-#[cfg(feature = "simple_generator")]
+#[cfg_attr(docsrs, doc(cfg(feature = "simple-generator")))]
+#[cfg(feature = "simple-generator")]
 pub use simple_generator::*;
 
 /// Captcha generator, used to generate a new captcha image and answer.

src/captcha_gen/simple_generator.rs

@@ -76,7 +76,7 @@ impl Display for SimpleGeneratorError {
 
 impl std::error::Error for SimpleGeneratorError {}
 
-/// The simple captcha generator
+/// A simple captcha generator, using the [`captcha`](https://crates.io/crates/captcha) crate.
 pub struct SimpleGenerator {
     name: CaptchaName,
     difficulty: CaptchaDifficulty,
@@ -93,8 +93,6 @@ impl CaptchaGenerator for SimpleGenerator {
     type Error = SimpleGeneratorError;
 
     /// The returned captcha image is 220x110 pixels in png format.
-    ///
-    /// For more information about the captcha name and difficulty, see the [`README.md`](https://git.4rs.nl/awiteb/salvo-captcha/#captcha-name-and-difficulty).
     async fn new_captcha(&self) -> Result<(String, Vec<u8>), Self::Error> {
         let Some((captcha_answer, captcha_image)) =
             captcha::by_name(self.difficulty.into(), self.name.into()).as_tuple()

src/lib.rs

@@ -13,6 +13,7 @@
 #![deny(warnings)]
 #![deny(missing_docs)]
 #![deny(clippy::print_stdout)]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 mod captcha_gen;
 mod finder;
@@ -29,7 +30,21 @@ pub use {captcha_gen::*, finder::*, storage::*};
 /// Key used to insert the captcha state into the depot
 pub const CAPTCHA_STATE_KEY: &str = "::salvo_captcha::captcha_state";
 
-/// Captcha struct, contains the token and answer.
+/// The captcha middleware
+///
+/// The captcha middleware is used to check the captcha token and answer from
+/// the request. You can use the [`CaptchaBuilder`] to create a new captcha
+/// middleware.
+///
+/// ## Note
+/// You need to generate the captcha token and answer before, then the captcha
+/// middleware will check the token and answer from the request using the finder
+/// and storage you provided. The captcha middleware will insert the
+/// [`CaptchaState`] into the depot, you can get the captcha state from the
+/// depot using the [`CaptchaDepotExt::get_captcha_state`] trait, which is
+/// implemented for the [`Depot`].
+///
+/// Check the [`examples`](https://git.4rs.nl/awiteb/salvo-captcha/src/branch/master/examples) for more information.
 #[non_exhaustive]
 pub struct Captcha<S, F>
 where

src/storage/cacache_storage.rs

@@ -16,7 +16,7 @@ use std::{
 
 use crate::CaptchaStorage;
 
-/// The [`cacache`] storage.
+/// The [`cacache`] storage. Store the token and answer in the disk.
 ///
 /// [`cacache`]: https://github.com/zkat/cacache-rs
 #[derive(Debug, Clone)]
@@ -26,7 +26,7 @@ pub struct CacacheStorage {
 }
 
 impl CacacheStorage {
-    /// Create a new CacacheStorage
+    /// Create a new [`CacacheStorage`] instance with the cache directory.
     pub fn new(cache_dir: impl Into<PathBuf>) -> Self {
         Self {
             cache_dir: cache_dir.into(),

src/storage/memory_storage.rs

@@ -20,7 +20,7 @@ use tokio::sync::RwLock;
 
 use crate::CaptchaStorage;
 
-/// Captcha storage implementation using an in-memory HashMap.
+/// Captcha storage implementation using an in-memory [HashMap].
 #[derive(Debug)]
 pub struct MemoryStorage(RwLock<HashMap<String, (u64, String)>>);
 
@@ -32,6 +32,7 @@ impl MemoryStorage {
 }
 
 impl CaptchaStorage for MemoryStorage {
+    /// This storage does not return any error.
     type Error = Infallible;
 
     async fn store_answer(&self, answer: String) -> Result<String, Self::Error> {

src/storage/mod.rs

@@ -15,6 +15,7 @@ use std::{sync::Arc, time::Duration};
 mod cacache_storage;
 mod memory_storage;
 
+#[cfg_attr(docsrs, doc(cfg(feature = "cacache-storage")))]
 #[cfg(feature = "cacache-storage")]
 pub use cacache_storage::*;
 pub use memory_storage::*;