Docs.rs comments

Comments for generating the docs with cargo doc

frontend/src/pages/utilities.rs

@@ -8,17 +8,42 @@ use yew::prelude::*;
 
 use crate::pages::ticket::{ActiveUser, Ticket};
 
+/// A partial representation of a ticket, containing only the fields necessary for statistical analysis.
+///
+/// This struct is used to efficiently retrieve and process ticket data for diagnostics
+/// without fetching the full ticket details.
+///
+/// # Fields
+/// - `date`: The creation date and time of the ticket in UTC.
+/// - `room`: The room number associated with the ticket.
 #[derive(Debug, Deserialize, Clone, PartialEq)]
 struct TicketPartial {
     date: DateTime<Utc>,
     room: i16,
 }
 
+/// Properties for components that display room-wise ticket totals.
+///
+/// This struct passes a list of partial ticket data to a component responsible
+/// for calculating and visualizing ticket distribution per room.
+///
+/// # Fields
+/// - `tickets`: A vector of `TicketPartial` containing ticket data relevant for room totals.
 #[derive(Properties, PartialEq)]
 struct RoomTotalsProps {
     tickets: Vec<TicketPartial>,
 }
 
+/// Converts a `chrono::DateTime<Utc>` object's weekday to a 0-indexed integer.
+///
+/// This function maps `chrono::Weekday` values (where Monday is 1, Sunday is 7)
+/// to a 0-indexed system (Monday = 0, Sunday = 6).
+///
+/// # Arguments
+/// - `dt`: A reference to a `DateTime<Utc>` object.
+///
+/// # Returns
+/// A `usize` representing the weekday index (0 for Monday, ..., 6 for Sunday).
 fn weekday_index(dt: &DateTime<Utc>) -> usize {
     // chrono::Weekday: Mon = 1 ... Sun = 7
     match dt.weekday() {
@@ -32,6 +57,17 @@ fn weekday_index(dt: &DateTime<Utc>) -> usize {
     }
 }
 
+/// Counts the number of tickets submitted on each day of the week.
+///
+/// This function takes a slice of `TicketPartial` and returns an array where each
+/// element corresponds to a day of the week (Monday=0, Sunday=6) and contains
+/// the total count of tickets submitted on that day.
+///
+/// # Arguments
+/// - `tickets`: A slice of `TicketPartial` items to count.
+///
+/// # Returns
+/// An array `[usize; 7]` with ticket counts for each weekday.
 fn count_by_weekday(tickets: &[TicketPartial]) -> [usize; 7] {
     let mut counts = [0usize; 7];
     for t in tickets {
@@ -40,6 +76,18 @@ fn count_by_weekday(tickets: &[TicketPartial]) -> [usize; 7] {
     counts
 }
 
+/// Calculates the occurrences of each weekday within the date range covered by the tickets.
+///
+/// This function determines the minimum and maximum dates from the provided `TicketPartial`
+/// slice and then counts how many times each weekday occurs within that inclusive date range.
+/// This is useful for normalizing ticket counts against the number of available days for each weekday.
+///
+/// # Arguments
+/// - `partials`: A slice of `TicketPartial` items defining the date range.
+///
+/// # Returns
+/// An array `[usize; 7]` where each element represents the number of times a
+/// specific weekday (Monday=0, ..., Sunday=6) appears in the date range.
 fn day_counts(partials: &[TicketPartial]) -> [usize; 7] {
     if partials.is_empty() {
         return [0usize; 7];
@@ -82,6 +130,17 @@ fn day_counts(partials: &[TicketPartial]) -> [usize; 7] {
     occ
 }
 
+/// Converts a numerical room representation back into a human-readable string format.
+///
+/// This function is the inverse of the room parsing logic in `SubmitTicket` component.
+/// It converts negative numbers back to "K" prefixed rooms, numbers >= 1000 back to "D" prefixed rooms,
+/// and other numbers to their string representation.
+///
+/// # Arguments
+/// - `r`: An `i16` representing the internal numerical representation of a room.
+///
+/// # Returns
+/// A `String` containing the formatted room number (e.g., "K1", "D1", "101").
 fn parse_room(r: i16) -> String {
     if r < 0 {
         format!("K{}", r.abs())
@@ -92,6 +151,21 @@ fn parse_room(r: i16) -> String {
     }
 }
 
+/// The main diagnostics dashboard component.
+///
+/// This component serves as a container for various statistical and diagnostic
+/// views related to the application's tickets.
+///
+/// # Components Rendered
+/// - [`TicketCount`]: Displays the count of open tickets.
+/// - [`SubmitStats`]: Displays statistics related to ticket submissions (e.g., by weekday, by room).
+///
+/// # Example
+/// ```rust
+/// html! {
+///     <Diagnostics />
+/// }
+/// ```
 #[component(Diagnostics)]
 pub fn diagnostics_component() -> Html {
     html! {
@@ -102,6 +176,31 @@ pub fn diagnostics_component() -> Html {
     }
 }
 
+/// A component that displays the count of currently open (ToDo or InProgress) tickets.
+///
+/// This component fetches all tickets and the current user's details. It then filters
+/// the tickets to count only those that are "ToDo" or "InProgress" and are either
+/// created by the current user (for non-admins) or all tickets (for admins).
+///
+/// # State
+/// Uses `use_state` hooks to manage:
+/// - `tickets`: A vector of `Ticket` structs for all fetched tickets.
+/// - `error`: Any error message from API calls.
+/// - `loading`: A boolean indicating if data is being fetched.
+/// - `user`: The `ActiveUser` details for conditional filtering.
+///
+/// # Functionality
+/// - Fetches all tickets from `/api/tickets`.
+/// - Fetches current user details from `/api/users/current`.
+/// - Filters tickets by status ("ToDo" or "InProgress") and user ID (if not admin).
+/// - Displays the count of matching tickets.
+///
+/// # Example
+/// ```rust
+/// html! {
+///     <TicketCount />
+/// }
+/// ```
 #[component(TicketCount)]
 pub fn ticket_count_component() -> Html {
     let tickets = use_state(|| Vec::<Ticket>::new());
@@ -196,6 +295,33 @@ pub fn ticket_count_component() -> Html {
     }
 }
 
+/// A component that displays various statistics about ticket submissions.
+///
+/// This component fetches all tickets (in a partial format for efficiency)
+/// and calculates statistics such as tickets per weekday and tickets per room.
+/// It renders these statistics visually using simple bar charts.
+///
+/// # State
+/// Uses `use_state` hooks to manage:
+/// - `tickets`: A vector of `TicketPartial` for statistical analysis.
+/// - `error`: Any error message from API calls.
+/// - `loading`: A boolean indicating if data is being fetched.
+///
+/// # Functionality
+/// - Fetches all tickets (as `TicketPartial`) from `/api/tickets`.
+/// - Calculates:
+///   - `counts`: Number of tickets submitted on each weekday.
+///   - `occ`: Number of occurrences of each weekday in the ticket date range.
+///   - `avg`: Average number of tickets per day for each weekday, normalized by `occ`.
+/// - Renders a bar chart for average tickets per weekday.
+/// - Renders a [`RoomTotalTickets`] component to display tickets per room.
+///
+/// # Example
+/// ```rust
+/// html! {
+///     <SubmitStats />
+/// }
+/// ```
 #[component(SubmitStats)]
 pub fn submit_stats_component() -> Html {
     let tickets = use_state(|| Vec::<TicketPartial>::new());
@@ -293,6 +419,29 @@ pub fn submit_stats_component() -> Html {
     }
 }
 
+/// A component that displays the total number of tickets per room.
+///
+/// This component takes a list of `TicketPartial` items and calculates the
+/// total number of tickets for each room. It then displays these totals
+/// in a sorted list with a bar chart visualization.
+///
+/// # Props
+/// - `tickets`: A `Vec<TicketPartial>` containing the partial ticket data for analysis.
+///
+/// # Functionality
+/// - **Calculates Totals**: Aggregates ticket counts for each unique room.
+/// - **Sorts Results**: Displays rooms sorted by ticket count in descending order.
+/// - **Visualizes Data**: Renders a bar chart where the width of each bar is
+///   proportional to the ticket count for that room, relative to the room with the maximum tickets.
+/// - **Room Formatting**: Uses the `parse_room` function to display room numbers
+///   in a human-readable format.
+///
+/// # Example
+/// ```rust
+/// html! {
+///     <RoomTotalTickets tickets={my_ticket_partials} />
+/// }
+/// ```
 #[component(RoomTotalTickets)]
 fn room_total_component(props: &RoomTotalsProps) -> Html {
     let mut totals: HashMap<i16, usize> = HashMap::new();