From 0f83f29c851351a3449aa31a24aef8dd4ab7f37b 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 --- Cargo.toml | 4 ++++ src/captcha_gen/mod.rs | 3 ++- src/captcha_gen/simple_generator.rs | 4 +--- src/lib.rs | 17 ++++++++++++++++- src/storage/cacache_storage.rs | 4 ++-- src/storage/memory_storage.rs | 3 ++- src/storage/mod.rs | 1 + 7 files changed, 28 insertions(+), 8 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 193b421..84fbb39 100644 --- a/Cargo.toml +++ b/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"] } diff --git a/src/captcha_gen/mod.rs b/src/captcha_gen/mod.rs index 7241ace..dc9c6e7 100644 --- a/src/captcha_gen/mod.rs +++ b/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. 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..8a5fff3 100644 --- a/src/lib.rs +++ b/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 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 { diff --git a/src/storage/mod.rs b/src/storage/mod.rs index 52ec968..ce49880 100644 --- a/src/storage/mod.rs +++ b/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::*;