docs: Improve the docs

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

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

@@ -29,7 +29,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> {