Docs.rs comments

Comments for generating the docs with cargo doc

frontend/src/pages/ticket.rs

@@ -9,6 +9,13 @@ use web_sys::HtmlSelectElement;
 use yew::prelude::*;
 use yew_router::prelude::*;
 
+/// A hardcoded list of valid room numbers for ticket submissions.
+///
+/// This array contains `i16` values representing valid rooms. Negative numbers typically
+/// denote rooms prefixed with 'K' (e.g., -1 for K1), and numbers greater than or equal to 1000
+/// denote rooms prefixed with 'D' (e.g., 1001 for D1).
+///
+/// This list is used for client-side validation of room input during ticket creation.
 const VALID_ROOMS: &[i16] = &[
     1, 2, 3, 4, 5, 6, 7, 8, 9, 13, 14, 15, 16, 17, 18, 19, 20, 22, 23, 24, 25, 26, 27, 28, 29, 30,
     32, 34, 36, 37, 39, 41, 49, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113,
@@ -18,6 +25,16 @@ const VALID_ROOMS: &[i16] = &[
     -8,
 ];
 
+/// Data transfer object (DTO) for creating a new ticket.
+///
+/// This struct defines the payload sent to the backend when a user submits a new ticket.
+/// It includes all necessary information for initial ticket creation.
+///
+/// # Fields
+/// - `category`: The category of the ticket (e.g., "Internet", "Hardware").
+/// - `betreff`: The subject or brief summary of the ticket.
+/// - `description`: A detailed description of the issue or request.
+/// - `room`: The room number where the issue is located.
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
 pub struct TicketCreateScheme {
     pub category: String,
@@ -26,11 +43,34 @@ pub struct TicketCreateScheme {
     pub room: i16,
 }
 
+/// Data transfer object (DTO) for updating a ticket's status.
+///
+/// This struct is used when sending a request to the backend to change the status
+/// of an existing ticket.
+///
+/// # Fields
+/// - `status`: The new status of the ticket (e.g., "ToDo", "InProgress", "Completed", "Archived").
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
 pub struct TicketUpdateScheme {
     pub status: String,
 }
 
+/// Represents a complete ticket entity retrieved from the backend.
+///
+/// This struct holds all details of a ticket, including its metadata, content,
+/// and associated user information.
+///
+/// # Fields
+/// - `id`: The unique identifier of the ticket.
+/// - `category`: The category of the ticket.
+/// - `betreff`: The subject of the ticket.
+/// - `description`: The detailed description of the ticket.
+/// - `room`: The room number associated with the ticket.
+/// - `status`: The current status of the ticket.
+/// - `date`: The creation date and time of the ticket in UTC.
+/// - `user_id`: The ID of the user who created the ticket.
+/// - `user_first_name`: The first name of the user who created the ticket.
+/// - `user_last_name`: The last name of the user who created the ticket.
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
 pub struct Ticket {
     pub id: i32,
@@ -45,23 +85,79 @@ pub struct Ticket {
     pub user_last_name: String,
 }
 
+/// Properties for components that display a single ticket.
+///
+/// This struct is used to pass the ID of a specific ticket to components
+/// that need to fetch or display its details.
+///
+/// # Fields
+/// - `id`: The unique identifier of the ticket to be displayed.
 #[derive(Properties, PartialEq)]
 pub struct TicketProps {
     pub id: i32,
 }
 
+/// Represents the essential information of the currently authenticated user.
+///
+/// This struct is used to hold a subset of user data relevant for client-side
+/// logic, such as determining if the user is an administrator or filtering
+/// tickets by their ID.
+///
+/// # Fields
+/// - `id`: An `Option<i16>` holding the unique ID of the active user. `None` if not authenticated or ID is unavailable.
+/// - `is_admin`: A boolean indicating if the active user has administrator privileges.
 #[derive(Clone, Debug, PartialEq)]
 pub struct ActiveUser {
     pub id: Option<i16>,
     pub is_admin: bool,
 }
 
+/// Represents a standardized error response from the API.
+///
+/// This struct is used to deserialize error messages returned by the backend API,
+/// providing a consistent way to handle and display error information to the user.
+///
+/// # Fields
+/// - `message`: A descriptive error message.
+/// - `_status`: (Ignored) The HTTP status code or a status string from the API.
 #[derive(Deserialize, Debug)]
 struct ApiError {
     message: String,
     _status: String,
 }
 
+/// A component that provides a form for users to submit new tickets.
+///
+/// This component allows users to input details such as category, subject (`betreff`),
+/// description, and room number for a new support ticket. It includes client-side
+/// validation for the room number and interacts with the backend API to create the ticket.
+///
+/// # State
+/// Uses `use_state` hooks to manage:
+/// - `category`, `betreff`, `description`: Values of the form input fields.
+/// - `room`, `room_input`: The parsed and raw room numbers, respectively.
+/// - `status`: To display messages about submission success or errors.
+///
+/// # Room Input Handling
+/// The `room_change` callback handles parsing the room input:
+/// - Supports numerical room numbers (e.g., "101").
+/// - Supports 'K' prefixed rooms (e.g., "K1" parses to -1).
+/// - Supports 'D' prefixed rooms (e.g., "D1" parses to 1001).
+/// - Validates the parsed room against the `VALID_ROOMS` constant.
+///
+/// # Form Submission
+/// - Prevents default form submission behavior.
+/// - Performs validation for room number and presence in `VALID_ROOMS`.
+/// - Constructs a `TicketCreateScheme` payload.
+/// - Sends a POST request to `/api/tickets/create`.
+/// - Updates the `status` state based on the API response.
+///
+/// # Example
+/// ```rust
+/// html! {
+///     <SubmitTicket />
+/// }
+/// ```
 #[component(SubmitTicket)]
 pub fn submit_ticket_component() -> Html {
     let category = use_state(|| "".to_string());
@@ -240,6 +336,40 @@ pub fn submit_ticket_component() -> Html {
     }
 }
 
+/// A component for displaying, updating, and deleting a single ticket by its ID.
+///
+/// This component fetches a specific ticket's details from the backend based on the
+/// `id` provided in its `TicketProps`. It allows administrators to update the ticket's
+/// status and delete the ticket.
+///
+/// # Props
+/// - `id`: The `i32` ID of the ticket to fetch and display.
+///
+/// # State
+/// Uses `use_state` hooks to manage:
+/// - `ticket`: The fetched [`Ticket`] data, if available.
+/// - `error`: Any error message encountered during API calls.
+/// - `loading`: A boolean indicating if data is currently being fetched.
+/// - `status`: The selected status for updating the ticket.
+/// - `deleting`: A boolean indicating if a delete operation is in progress.
+/// - `delete_error`: Any error message from a delete operation.
+///
+/// # Functionality
+/// - **Data Fetching**: On component mount or `id` change, fetches ticket data from
+///   `/api/tickets/:id`.
+/// - **Status Update**: Provides a dropdown to change the ticket's status. Submitting the
+///   form sends a PATCH request to `/api/tickets/:id` with a `TicketUpdateScheme` payload.
+/// - **Ticket Deletion**: Includes a "Delete" button that, after user confirmation,
+///   sends a DELETE request to `/api/tickets/:id`. On success, clears the ticket from display.
+/// - **Error Handling**: Displays error messages for network issues, API errors, or parsing failures.
+/// - **Date Formatting**: Displays the ticket creation date formatted to `Europe/Berlin` timezone.
+///
+/// # Example
+/// ```rust
+/// html! {
+///     <TicketByID id={123} />
+/// }
+/// ```
 #[component(TicketByID)]
 pub fn ticket_by_id_component(props: &TicketProps) -> Html {
     let ticket = use_state(|| None::<Ticket>);
@@ -423,6 +553,39 @@ pub fn ticket_by_id_component(props: &TicketProps) -> Html {
     }
 }
 
+/// A component for fetching and displaying a list of all tickets.
+///
+/// This component retrieves all tickets from the backend and presents them as a list.
+/// It dynamically filters the displayed tickets based on the current user's role:
+/// administrators see all tickets, while regular users only see tickets they created.
+///
+/// # State
+/// Uses `use_state` hooks to manage:
+/// - `tickets`: A vector of `Ticket` structs to store the fetched tickets.
+/// - `error`: Any error message encountered during API calls.
+/// - `loading`: A boolean indicating if data is currently being fetched.
+/// - `user`: An `ActiveUser` struct holding the current user's ID and admin status.
+///
+/// # Functionality
+/// - **Fetch Tickets**: On component mount, fetches all tickets from `/api/tickets`.
+/// - **Fetch Current User**: Concurrently fetches the current user's details from
+///   `/api/users/current` to determine their `user_id` and `is_admin` status.
+/// - **Conditional Display**:
+///   - If `loading` is true, displays "Loading...".
+///   - If an `error` occurs, displays the error message.
+///   - Otherwise, renders a list of tickets.
+/// - **Filtering**:
+///   - Administrators (`user.is_admin = true`) see all tickets.
+///   - Regular users (`user.is_admin = false`) only see tickets where `t.user_id == user.id`.
+/// - **Navigation**: Each ticket in the list is a link to [`crate::Route::TicketById`]
+///   for viewing individual ticket details.
+///
+/// # Example
+/// ```rust
+/// html! {
+///     <AllTickets />
+/// }
+/// ```
 #[component(AllTickets)]
 pub fn all_tickets_component() -> Html {
     let tickets = use_state(|| Vec::<Ticket>::new());