Docs.rs comments

Comments for generating the docs with cargo doc

frontend/src/auth.rs

@@ -3,18 +3,59 @@ use wasm_bindgen_futures::spawn_local;
 use yew::prelude::*;
 use yew_router::prelude::*;
 
+/// Represents the authentication state of the current user.
+///
+/// This struct holds information about whether a user is authenticated and if they
+/// possess administrator privileges.
+///
+/// # Fields
+/// - `is_authenticated`: An `Option<bool>` indicating if the user is logged in.
+///   `None` means the status is still being checked.
+/// - `is_admin`: An `Option<bool>` indicating if the authenticated user is an administrator.
+///   `None` means the admin status is still being checked or is not applicable.
 #[derive(Clone, Debug, PartialEq)]
 pub struct AuthState {
     pub is_authenticated: Option<bool>,
     pub is_admin: Option<bool>,
 }
 
+/// Properties for the [`ProtectedRoute`] component.
+///
+/// # Fields
+/// - `children`: The child components that this protected route will render if access is granted.
+/// - `admin_page`: A boolean flag indicating whether this route requires administrator privileges.
+///   If `true`, the user must be authenticated AND be an administrator to access the `children`.
 #[derive(Properties, PartialEq)]
 pub struct ProtectedRouteProps {
     pub children: Children,
     pub admin_page: bool,
 }
 
+/// A component that protects routes by enforcing authentication and optional administrator privileges.
+///
+/// This component fetches the current user's authentication and admin status from the
+/// `/api/users/current` endpoint upon mounting. Based on the `AuthState` and the
+/// `admin_page` property, it either renders its children or redirects the user.
+///
+/// # Behavior
+/// - **Initial Load**: Displays "Loading..." while checking authentication status.
+/// - **Not Authenticated**: Redirects to the login page (`crate::Route::Login`).
+/// - **Authenticated**:
+///   - If `admin_page` is `true`:
+///     - If the user is an administrator (`is_admin: Some(true)`), it renders `children`.
+///     - If the user is not an administrator (`is_admin: Some(false)`), it redirects to
+///       the permission denied page (`crate::Route::PermissionDenied`).
+///     - If admin status is still being checked (`is_admin: None`), it displays "Checking permissions...".
+///   - If `admin_page` is `false`: It renders `children` directly, as only authentication is required.
+///
+/// # Example Usage
+/// ```ignore
+/// html! {
+///     <ProtectedRoute admin_page={true}>
+///         <AdminDashboard />
+///     </ProtectedRoute>
+/// }
+/// ```
 #[component(ProtectedRoute)]
 pub fn protected_route(props: &ProtectedRouteProps) -> Html {
     let auth_state = use_state(|| AuthState {