docs: Improve the docs
Some checks failed
Rust CI / Rust CI (push) Failing after 50s

Signed-off-by: Awiteb <a@4rs.nl>
This commit is contained in:
Awiteb 2024-08-12 20:43:14 +00:00
parent a294ebfe96
commit dab2db43cf
Signed by: awiteb
GPG key ID: 3F6B55640AA6682F
4 changed files with 20 additions and 7 deletions

View file

@ -76,7 +76,7 @@ impl Display for SimpleGeneratorError {
impl std::error::Error 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 { pub struct SimpleGenerator {
name: CaptchaName, name: CaptchaName,
difficulty: CaptchaDifficulty, difficulty: CaptchaDifficulty,
@ -93,8 +93,6 @@ impl CaptchaGenerator for SimpleGenerator {
type Error = SimpleGeneratorError; type Error = SimpleGeneratorError;
/// The returned captcha image is 220x110 pixels in png format. /// 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> { async fn new_captcha(&self) -> Result<(String, Vec<u8>), Self::Error> {
let Some((captcha_answer, captcha_image)) = let Some((captcha_answer, captcha_image)) =
captcha::by_name(self.difficulty.into(), self.name.into()).as_tuple() captcha::by_name(self.difficulty.into(), self.name.into()).as_tuple()

View file

@ -29,7 +29,21 @@ pub use {captcha_gen::*, finder::*, storage::*};
/// Key used to insert the captcha state into the depot /// Key used to insert the captcha state into the depot
pub const CAPTCHA_STATE_KEY: &str = "::salvo_captcha::captcha_state"; 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] #[non_exhaustive]
pub struct Captcha<S, F> pub struct Captcha<S, F>
where where

View file

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

View file

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