From dab2db43cf6634e0166fc0b2f266fbbea4571336 Mon Sep 17 00:00:00 2001 From: Awiteb Date: Mon, 12 Aug 2024 20:43:14 +0000 Subject: [PATCH] docs: Improve the docs Signed-off-by: Awiteb --- src/captcha_gen/simple_generator.rs | 4 +--- src/lib.rs | 16 +++++++++++++++- src/storage/cacache_storage.rs | 4 ++-- src/storage/memory_storage.rs | 3 ++- 4 files changed, 20 insertions(+), 7 deletions(-) diff --git a/src/captcha_gen/simple_generator.rs b/src/captcha_gen/simple_generator.rs index 04845c1..0a02777 100644 --- a/src/captcha_gen/simple_generator.rs +++ b/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), Self::Error> { let Some((captcha_answer, captcha_image)) = captcha::by_name(self.difficulty.into(), self.name.into()).as_tuple() diff --git a/src/lib.rs b/src/lib.rs index 288707a..69d0866 100644 --- a/src/lib.rs +++ b/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 where diff --git a/src/storage/cacache_storage.rs b/src/storage/cacache_storage.rs index 42b440a..7c4c6e0 100644 --- a/src/storage/cacache_storage.rs +++ b/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) -> Self { Self { cache_dir: cache_dir.into(), diff --git a/src/storage/memory_storage.rs b/src/storage/memory_storage.rs index 42e6b12..561ef92 100644 --- a/src/storage/memory_storage.rs +++ b/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>); @@ -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 {