Docs.rs comments

Comments for generating the docs with cargo doc

backend/src/cookie/validation.rs

@@ -19,6 +19,25 @@ use crate::{
     models::{LoginScheme, User},
 };
 
+/// Axum middleware to validate a JWT token present in cookies or Authorization header.
+///
+/// This function extracts a JWT from the request (either from the `token` cookie or
+/// the `Authorization: Bearer` header), decodes and validates it. If valid, it fetches
+/// the corresponding user from the database and inserts a `FilteredUser` into the
+/// request extensions for subsequent handlers to use.
+///
+/// If the token is missing, invalid, or the user is not found, it returns an
+/// appropriate error response (401 Unauthorized).
+///
+/// # Arguments
+/// - `cookies`: The `CookieJar` from the request, used to extract the `token` cookie.
+/// - `State(data)`: Application state containing `AppState` for database access and `token_secret`.
+/// - `mut request`: The incoming HTTP request, which will have user data injected into its extensions.
+/// - `next`: The next middleware or handler in the chain.
+///
+/// # Returns
+/// - `Ok(impl IntoResponse)`: If validation succeeds, the request proceeds to the next handler.
+/// - `Err((StatusCode, Json<serde_json::Value>))`: An error response if validation fails.
 pub async fn validate_token(
     cookies: CookieJar,
     State(data): State<Arc<AppState>>,
@@ -94,6 +113,25 @@ pub async fn validate_token(
     Ok(next.run(request).await)
 }
 
+/// Axum middleware to validate JWT token and ensure the authenticated user has admin privileges.
+///
+/// This middleware first performs all checks of `validate_token`: extracting, decoding,
+/// and validating the JWT, and fetching the associated user from the database.
+/// Additionally, it verifies that the fetched user has `is_admin` set to `true`.
+///
+/// If the user is not authenticated or not an administrator, it returns an
+/// appropriate error response (401 Unauthorized or 403 Forbidden).
+///
+/// # Arguments
+/// - `cookies`: The `CookieJar` from the request.
+/// - `State(data)`: Application state containing `AppState`.
+/// - `mut request`: The incoming HTTP request, which will have admin user data injected.
+/// - `next`: The next middleware or handler in the chain.
+///
+/// # Returns
+/// - `Ok(impl IntoResponse)`: If validation and admin check succeed, the request proceeds.
+/// - `Err((StatusCode, Json<serde_json::Value>))`: An error response if validation fails
+///   or the user is not an admin.
 pub async fn validate_admin(
     cookies: CookieJar,
     State(data): State<Arc<AppState>>,