Docs.rs comments

Comments for generating the docs with cargo doc

frontend/src/pages/setup.rs

@@ -4,6 +4,17 @@ use wasm_bindgen_futures::spawn_local;
 use yew::prelude::*;
 use yew_router::prelude::*;
 
+/// Payload for creating the initial administrator account.
+///
+/// This struct is sent to the `/api/setup-admin` endpoint to create the first admin user
+/// when no administrators exist in the system. It carries the necessary information
+/// for the new admin's profile and credentials.
+///
+/// # Fields
+/// - `first_name`: The first name of the administrator.
+/// - `last_name`: The last name of the administrator.
+/// - `username`: The unique username for the administrator's login.
+/// - `pwd`: The password for the administrator's account. This will be hashed on the backend.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct AdminSetupScheme {
     pub first_name: String,
@@ -12,6 +23,43 @@ pub struct AdminSetupScheme {
     pub pwd: String,
 }
 
+/// Component for the initial admin account setup page.
+///
+/// This page is displayed when a fresh system has no administrator accounts. It provides
+/// a form to create the first admin user. Key functionality:
+///
+/// - **Admin Check**: On mount, verifies if an admin already exists by calling `/api/check-admin`.
+///   If an admin is found, the user is redirected to the login page (`crate::Route::Login`).
+/// - **Form Fields**: Collects `first_name`, `last_name`, `username`, `password`, and `confirm_password`.
+/// - **Form Validation**:
+///   - Ensures password fields are not empty.
+///   - Verifies that `password` and `confirm_password` match.
+///   - Ensures the `username` field is not empty.
+/// - **API Interaction**: On form submission, a POST request is sent to `/api/setup-admin`
+///   with the new admin's details.
+/// - **Password Hashing**: The backend is responsible for hashing the password using Argon2
+///   before storage; this component only sends the plain text password.
+/// - **Auto-redirect**: On successful admin account creation, the user is automatically
+///   redirected to the login page (`crate::Route::Login`).
+/// - **State Management**: Uses Yew's `use_state` hooks to manage:
+///   - Input field values (`first_name`, `last_name`, `username`, `pwd`, `pwd_confirm`).
+///   - UI states like `error` messages, `success` status, and `loading` indicators.
+///   - `admin_check_done` to prevent rendering the form before the initial admin check completes.
+///
+/// # Example Flow
+/// 1. User navigates to `/setup`.
+/// 2. The component checks `/api/check-admin`.
+/// 3. If an admin exists, redirects to `/login`.
+/// 4. If no admin exists, the setup form is displayed.
+/// 5. User fills out the form and submits.
+/// 6. Form data is sent via POST to `/api/setup-admin`.
+/// 7. On successful response (HTTP 200), redirects to `/login`.
+/// 8. On error, displays an error message to the user.
+///
+/// # Security Notes
+/// - The initial admin check prevents re-creating an admin if one already exists.
+/// - Password confirmation helps prevent user typos for critical credentials.
+/// - Backend validation further ensures non-empty and secure credentials.
 #[component(InitialAdminSetup)]
 pub fn initial_admin_setup() -> Html {
     let first_name = use_state(|| "".to_string());