chore: Bump the version to 0.3.1

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

.forgejo/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Build the source code
         run: cargo build
       - name: Build examples
-        run: cargo build -F 'cacache-storage' --example simple_login
+        run: cargo build -F 'simple-generator' --example simple_login
       - name: Run tests
         run: cargo test --tests --all-features
       - name: Check the code format

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "salvo-captcha"
-version = "0.1.0"
+version = "0.3.1"
 rust-version = "1.75.0"
 edition = "2021"
 authors = ["Awiteb <a@4rs.nl>"]
@@ -24,7 +24,11 @@ either = { version = "1.13.0", default-features = false }
 
 [features]
 cacache-storage = ["dep:cacache"]
-simple_generator = ["dep:captcha"]
+simple-generator = ["dep:captcha"]
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
 
 [dev-dependencies]
 tempfile = "3.9"
@@ -35,4 +39,4 @@ rstest = "0.22.0"
 
 [[example]]
 name = "simple_login"
-required-features = ["simple_generator"]
+required-features = ["simple-generator"]

Justfile

@@ -19,7 +19,7 @@ _default:
 # Run the CI (Local use only)
 @ci:
     cargo fmt --all --check
-    cargo build -F 'simple_generator' --example simple_login
+    cargo build -F 'simple-generator' --example simple_login
     cargo clippy --workspace --all-targets --examples --tests --all-features -- -D warnings
     cargo nextest run --workspace --all-targets --all-features
     @{{JUST_EXECUTABLE}} msrv

README.md

@@ -14,7 +14,7 @@ First, add the following to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-salvo-captcha = "0.2"
+salvo-captcha = "0.3"
 ```
 
 Or use [`cargo add`] to add the dependency to your `Cargo.toml`:
@@ -37,7 +37,7 @@ A high-performance, concurrent, content-addressable disk cache. The storage is b
 
 ```toml
 [dependencies]
-salvo-captcha = { version = "0.2", features = ["cacache-storage"] }
+salvo-captcha = { version = "0.3", features = ["cacache-storage"] }
 ```
 
 ## Captcha Finder
@@ -46,7 +46,14 @@ We provide fully customizable query parameters, form fields, and headers to find
 
 ## Captcha Generator
 
-We provide [`SimpleCaptchaGenerator`] which is a simple captcha generator based on the [`captcha`] crate. You can implement your own captcha generator by implementing the [`CaptchaGenerator`] trait.
+We provide [`SimpleCaptchaGenerator`] which is a simple captcha generator based on the [`captcha`] crate, you can enable it by enabling the `simple-generator` feature.
+
+```toml
+[dependencies]
+salvo-captcha = { version = "0.3", features = ["simple-generator"] }
+```
+
+You can implement your own generator by implementing the [`CaptchaGenerator`] trait.
 
 ### Captcha name and difficulty
 

src/captcha_gen/mod.rs

@@ -9,10 +9,11 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 // THE SOFTWARE.
 
-#[cfg(feature = "simple_generator")]
+#[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::*;