Docs.rs comments

Comments for generating the docs with cargo doc

frontend/src/pages/user.rs

@@ -14,6 +14,17 @@ use yew_router::prelude::*;
 //     pub pwd: String,
 // }
 
+/// Data transfer object (DTO) for creating a new user.
+///
+/// This struct defines the payload sent to the backend when an administrator
+/// registers a new user. It includes all necessary information for user creation.
+///
+/// # Fields
+/// - `first_name`: The first name of the user.
+/// - `last_name`: The last name of the user.
+/// - `username`: The unique username for the user's login.
+/// - `is_admin`: A boolean indicating whether the new user should have administrator privileges.
+/// - `pwd`: The password for the user's account. This will be hashed on the backend.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct UserCreateScheme {
     pub first_name: String,
@@ -23,12 +34,31 @@ pub struct UserCreateScheme {
     pub pwd: String,
 }
 
+/// Data transfer object (DTO) for user login credentials.
+///
+/// This struct defines the payload sent to the backend when a user attempts to log in.
+///
+/// # Fields
+/// - `username`: The username provided by the user.
+/// - `pwd`: The password provided by the user.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct LoginScheme {
     pub username: String,
     pub pwd: String,
 }
 
+/// Data transfer object (DTO) for updating an existing user's information.
+///
+/// This struct is used to send updated user details, including an optional new password,
+/// to the backend for an existing user.
+///
+/// # Fields
+/// - `id`: The unique identifier of the user to be updated.
+/// - `first_name`: The updated first name of the user.
+/// - `last_name`: The updated last name of the user.
+/// - `username`: The updated username for the user.
+/// - `make_admin`: A boolean indicating whether to grant/revoke administrator privileges.
+/// - `new_pwd`: An optional new password for the user. If empty, the password remains unchanged.
 #[derive(Deserialize, Serialize, Debug)]
 pub struct UserUpdateScheme {
     pub id: i16,
@@ -39,6 +69,18 @@ pub struct UserUpdateScheme {
     pub new_pwd: String,
 }
 
+/// Represents a user entity with sensitive information filtered out.
+///
+/// This struct is used for displaying user information in contexts where
+/// the password hash or other sensitive details are not needed or should not be exposed.
+/// It's typically used for listing users or displaying user profiles.
+///
+/// # Fields
+/// - `id`: The unique identifier of the user.
+/// - `first_name`: The first name of the user.
+/// - `last_name`: The last name of the user.
+/// - `username`: The unique username of the user.
+/// - `is_admin`: A boolean indicating if the user has administrator privileges.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct FilteredUser {
     pub id: i16,
@@ -48,6 +90,13 @@ pub struct FilteredUser {
     pub is_admin: bool,
 }
 
+/// Properties for components that display or interact with a single user.
+///
+/// This struct is used to pass the ID of a specific user to components
+/// that need to fetch, display, or modify their details.
+///
+/// # Fields
+/// - `id`: The unique identifier of the user to be displayed or acted upon.
 #[derive(Properties, PartialEq)]
 pub struct UserProps {
     pub id: i16,
@@ -59,6 +108,31 @@ struct ApiError {
     _status: String,
 }
 
+/// A component providing a form for registering new users.
+///
+/// This component allows an administrator to create new user accounts by providing
+/// their first name, last name, username, password, and specifying if they should
+/// be an administrator. The component handles form input, validation (basic),
+/// and interaction with the backend `/api/register` endpoint.
+///
+/// # State
+/// Uses `use_state` hooks to manage:
+/// - `first_name`, `last_name`, `username`, `pwd`: Values of the form input fields.
+/// - `is_admin`: Boolean state for the admin checkbox.
+/// - `status`: To display messages about registration success or errors.
+///
+/// # Form Submission
+/// - Prevents default form submission behavior.
+/// - Constructs a `UserCreateScheme` payload from the form data.
+/// - Sends a POST request to `/api/register`.
+/// - Updates the `status` state based on the API response.
+///
+/// # Example
+/// ```rust
+/// html! {
+///     <Register />
+/// }
+/// ```
 #[component(Register)]
 pub fn register_component() -> Html {
     let first_name = use_state(|| "".to_string());
@@ -169,6 +243,32 @@ pub fn register_component() -> Html {
     }
 }
 
+/// A component providing a form for user login.
+///
+/// This component handles user authentication by collecting a username and password,
+/// then sending these credentials to the backend `/api/login` endpoint. It manages
+/// UI states for loading, errors, and success, and redirects to the home page on successful login.
+///
+/// # State
+/// Uses `use_state` hooks to manage:
+/// - `username`, `pwd`: Values of the login form input fields.
+/// - `loading`: A boolean to indicate if the login process is ongoing.
+/// - `error`: A string to display any login error messages.
+/// - `success`: A boolean to indicate if login was successful.
+///
+/// # Form Submission
+/// - Prevents default form submission behavior.
+/// - Constructs a `LoginScheme` payload from the input fields.
+/// - Sends a POST request to `/api/login`.
+/// - On successful response (HTTP 200), sets `success` to true and redirects to `crate::Route::Home`.
+/// - On error, updates the `error` state with the appropriate message.
+///
+/// # Example
+/// ```rust
+/// html! {
+///     <Login />
+/// }
+/// ```
 #[component(Login)]
 pub fn login_component() -> Html {
     let username = use_state(|| "".to_string());
@@ -252,6 +352,33 @@ pub fn login_component() -> Html {
     }
 }
 
+/// A component for fetching and displaying a list of all registered users.
+///
+/// This component retrieves a list of `FilteredUser` entities from the backend
+/// via the `/api/users` endpoint and displays them. Each user entry includes a
+/// link to view their individual details through `UserByID`.
+///
+/// # State
+/// Uses `use_state` hooks to manage:
+/// - `users`: A vector of `FilteredUser` structs to store the fetched user data.
+/// - `error`: Any error message encountered during API calls.
+/// - `loading`: A boolean indicating if user data is currently being fetched.
+///
+/// # Functionality
+/// - **Data Fetching**: On component mount, fetches all users from `/api/users`.
+/// - **Conditional Display**:
+///   - If `loading` is true, displays "Loading...".
+///   - If an `error` occurs, displays the error message.
+///   - Otherwise, renders an unordered list of users.
+/// - **Navigation**: Each user in the list is a link to [`crate::Route::UserByID`]
+///   for viewing individual user details.
+///
+/// # Example
+/// ```rust
+/// html! {
+///     <AllUsers />
+/// }
+/// ```
 #[component(AllUsers)]
 pub fn all_users_component() -> Html {
     let users = use_state(|| Vec::<FilteredUser>::new());
@@ -306,6 +433,43 @@ pub fn all_users_component() -> Html {
     }
 }
 
+/// A component for displaying, updating, and deleting a single user by their ID.
+///
+/// This component fetches a specific user's details from the backend based on the
+/// `id` provided in its `UserProps`. It allows administrators to view, modify
+/// (first name, last name, username, admin status, and password), and delete user accounts.
+///
+/// # Props
+/// - `id`: The `i16` ID of the user to fetch and display.
+///
+/// # State
+/// Uses `use_state` hooks to manage:
+/// - `user`: The fetched [`FilteredUser`] data, if available.
+/// - `error`: Any error message encountered during initial user data fetching.
+/// - `loading`: A boolean indicating if initial user data is being fetched.
+/// - `first_name`, `last_name`, `username`, `make_admin`, `new_pwd`:
+///   States for the update form fields, pre-filled with current user data.
+/// - `saving`, `save_error`, `save_success`: States for the user update operation.
+/// - `deleting`, `delete_error`: States for the user deletion operation.
+///
+/// # Functionality
+/// - **Initial Data Fetching**: On component mount or `id` change, fetches user data from
+///   `/api/users/:id`.
+/// - **Form Initialization**: Populates the update form fields with the fetched user's
+///   current details once loaded.
+/// - **User Update**: The update form sends a PATCH request to `/api/users/:id` with a
+///   `UserUpdateScheme` payload. On success, updates the displayed user data and shows a
+///   success message.
+/// - **User Deletion**: Includes a "Delete" button that, after user confirmation, sends
+///   a DELETE request to `/api/users/:id`. On success, clears the user from display.
+/// - **Error Handling**: Displays error messages for various API and network issues.
+///
+/// # Example
+/// ```rust
+/// html! {
+///     <UserByID id={42} />
+/// }
+/// ```
 #[component(UserByID)]
 pub fn user_by_id_component(props: &UserProps) -> Html {
     let user = use_state(|| None::<FilteredUser>);