feat(web): add comprehensive documentation for extraction

crates/web/src/extract/extract_body.rs

@@ -1,3 +1,31 @@
+//! Body data extraction implementations
+//! 
+//! This module provides implementations for extracting typed data from request bodies.
+//! It supports extracting raw bytes, strings, JSON data and form data.
+//! 
+//! # Examples
+//! 
+//! ```no_run
+//! # use micro_web::extract::{Json, Form};
+//! # use serde::Deserialize;
+//! 
+//! #[derive(Deserialize)]
+//! struct User {
+//!     name: String,
+//!     age: u32
+//! }
+//! 
+//! // Extract JSON data
+//! async fn handle_json(Json(user): Json<User>) {
+//!     println!("Got user: {}", user.name);
+//! }
+//! 
+//! // Extract form data
+//! async fn handle_form(Form(user): Form<User>) {
+//!     println!("Got user: {}", user.name); 
+//! }
+//! ```
+
 use crate::body::OptionReqBody;
 use crate::extract::{Form, FromRequest, Json};
 use crate::RequestContext;
@@ -7,6 +35,7 @@ use http_body_util::BodyExt;
 use micro_http::protocol::ParseError;
 use serde::Deserialize;
 
+/// Extracts raw bytes from request body
 #[async_trait]
 impl FromRequest for Bytes {
     type Output<'any> = Bytes;
@@ -17,6 +46,7 @@ impl FromRequest for Bytes {
     }
 }
 
+/// Extracts UTF-8 string from request body
 #[async_trait]
 impl FromRequest for String {
     type Output<'any> = String;
@@ -32,6 +62,10 @@ impl FromRequest for String {
     }
 }
 
+/// Extracts form data from request body
+/// 
+/// This implementation expects the request body to be URL-encoded form data
+/// and deserializes it into the target type using `serde_urlencoded`.
 #[async_trait]
 impl<T> FromRequest for Form<T>
 where
@@ -48,6 +82,10 @@ where
     }
 }
 
+/// Extracts JSON data from request body
+/// 
+/// This implementation expects the request body to be valid JSON
+/// and deserializes it into the target type using `serde_json`.
 #[async_trait]
 impl<T> FromRequest for Json<T>
 where

crates/web/src/extract/extract_header.rs

@@ -1,10 +1,45 @@
+//! HTTP header extraction implementations
+//! 
+//! This module provides extractors for HTTP header-related information from requests,
+//! including HTTP methods, header maps and raw request headers. These extractors allow
+//! handlers to directly access header information in a type-safe way.
+//! 
+//! The extractors support both owned and borrowed access to the header data:
+//! - Owned extractors like `Method` and `HeaderMap` take ownership of the data
+//! - Borrowed extractors like `&Method` and `&HeaderMap` provide reference access
+//! 
+//! # Examples
+//! 
+//! ```no_run
+//! use http::{HeaderMap, Method};
+//! 
+//! // Access HTTP method
+//! async fn handle_method(method: Method) {
+//!     match method {
+//!         Method::GET => println!("Handling GET request"),
+//!         Method::POST => println!("Handling POST request"),
+//!         _ => println!("Handling other request method")
+//!     }
+//! }
+//! 
+//! // Access headers
+//! async fn handle_headers(headers: &HeaderMap) {
+//!     if let Some(content_type) = headers.get("content-type") {
+//!         println!("Content-Type: {:?}", content_type);
+//!     }
+//! }
+//! ```
+
 use crate::body::OptionReqBody;
 use crate::extract::from_request::FromRequest;
 use crate::RequestContext;
 use async_trait::async_trait;
 use http::{HeaderMap, Method};
 use micro_http::protocol::{ParseError, RequestHeader};
 
+/// Extracts the HTTP method by value
+/// 
+/// This extractor takes ownership of the request method.
 #[async_trait]
 impl FromRequest for Method {
     type Output<'any> = Method;
@@ -15,6 +50,9 @@ impl FromRequest for Method {
     }
 }
 
+/// Extracts a reference to the HTTP method
+/// 
+/// This extractor borrows the request method, avoiding cloning.
 #[async_trait]
 impl FromRequest for &Method {
     type Output<'r> = &'r Method;
@@ -25,6 +63,9 @@ impl FromRequest for &Method {
     }
 }
 
+/// Extracts a reference to the raw request header
+/// 
+/// Provides access to the underlying HTTP request header structure.
 #[async_trait]
 impl FromRequest for &RequestHeader {
     type Output<'r> = &'r RequestHeader;
@@ -35,6 +76,9 @@ impl FromRequest for &RequestHeader {
     }
 }
 
+/// Extracts a reference to the header map
+/// 
+/// This extractor provides borrowed access to all HTTP headers.
 #[async_trait]
 impl FromRequest for &HeaderMap {
     type Output<'r> = &'r HeaderMap;
@@ -45,6 +89,9 @@ impl FromRequest for &HeaderMap {
     }
 }
 
+/// Extracts the header map by value
+/// 
+/// This extractor clones and takes ownership of all HTTP headers.
 #[async_trait]
 impl FromRequest for HeaderMap {
     type Output<'any> = HeaderMap;

crates/web/src/extract/extract_url.rs

@@ -1,9 +1,35 @@
+//! URL query string extraction functionality
+//! 
+//! This module provides implementation for extracting typed data from URL query strings.
+//! It allows handlers to receive strongly-typed query parameters by implementing the
+//! `FromRequest` trait for the `Query<T>` type.
+//!
+//! # Example
+//! ```no_run
+//! # use serde::Deserialize;
+//! # use micro_web::extract::Query;
+//! 
+//! #[derive(Deserialize)]
+//! struct Params {
+//!     name: String,
+//!     age: u32,
+//! }
+//! 
+//! async fn handler(Query(params): Query<Params>) {
+//!     println!("Name: {}, Age: {}", params.name, params.age);
+//! }
+//! ```
+
 use crate::extract::{FromRequest, Query};
 use crate::{OptionReqBody, RequestContext};
 use async_trait::async_trait;
 use micro_http::protocol::ParseError;
 use serde::Deserialize;
 
+/// Implements query string extraction for any type that implements Deserialize
+/// 
+/// This implementation allows automatic deserialization of query string parameters
+/// into a strongly-typed struct using serde_qs.
 #[async_trait]
 impl<T> FromRequest for Query<T>
 where