Docs.rs comments

Comments for generating the docs with cargo doc

frontend/src/pages/sidebar.rs

@@ -9,6 +9,15 @@ use yew_router::prelude::*;
 
 const STORAGE_KEY: &str = "sidebar_state";
 
+/// Represents the expansion state of collapsible menus within the sidebar.
+///
+/// This struct is used to persist the open/closed state of sidebar submenus,
+/// improving user experience by remembering their last interaction.
+/// The state is stored in and retrieved from `LocalStorage`.
+///
+/// # Fields
+/// - `ticket_open`: A boolean indicating if the "Tickets" submenu is expanded (`true`) or collapsed (`false`).
+/// - `users_open`: A boolean indicating if the "Users" submenu is expanded (`true`) or collapsed (`false`).
 #[derive(Clone, PartialEq, Serialize, Deserialize)]
 pub struct SidebarExpandState {
     pub ticket_open: bool,
@@ -16,6 +25,7 @@ pub struct SidebarExpandState {
 }
 
 impl Default for SidebarExpandState {
+    /// Provides the default expansion state, where all submenus are collapsed.
     fn default() -> Self {
         Self {
             ticket_open: false,
@@ -24,6 +34,17 @@ impl Default for SidebarExpandState {
     }
 }
 
+/// Represents the shared state for the sidebar's expandable menus.
+///
+/// This context struct is provided via Yew's `ContextProvider` and allows child components
+/// within the sidebar to read and modify the expansion state of the "Tickets" and "Users" menus.
+///
+/// # Fields
+/// - `expand`: The current [`SidebarExpandState`] holding whether each menu is open or closed.
+/// - `set_tickets_open`: A `Callback<bool>` to explicitly set the open state of the "Tickets" menu.
+/// - `toggle_tickets`: A `Callback<()>` to toggle the open state of the "Tickets" menu.
+/// - `set_users_open`: A `Callback<bool>` to explicitly set the open state of the "Users" menu.
+/// - `toggle_users`: A `Callback<()>` to toggle the open state of the "Users" menu.
 #[derive(Clone, PartialEq)]
 pub struct SidebarState {
     pub expand: SidebarExpandState,
@@ -34,6 +55,10 @@ pub struct SidebarState {
 }
 
 impl SidebarState {
+    /// Creates a new `SidebarState` instance.
+    ///
+    /// This constructor is typically used within the [`SidebarStateProvider`] to
+    /// bundle the current expansion state and its associated callbacks for context sharing.
     fn new(
         expand: SidebarExpandState,
         set_tickets_open: Callback<bool>,
@@ -51,11 +76,40 @@ impl SidebarState {
     }
 }
 
+/// Properties for components that provide sidebar state.
+///
+/// This struct is typically used by context providers that wrap child components
+/// and supply them with shared sidebar-related state or functionality.
+///
+/// # Fields
+/// - `children`: The child components that will have access to the provided sidebar state.
 #[derive(Properties, PartialEq)]
 pub struct SidebarProps {
     pub children: Children,
 }
 
+/// A Yew context provider component that manages and supplies the sidebar's expansion state.
+///
+/// This component is responsible for:
+/// 1. Loading the initial `SidebarExpandState` from browser `LocalStorage` (or using defaults).
+/// 2. Providing a `SidebarState` context (`Rc<SidebarState>`) to its children, which includes
+///    the current expansion state and callbacks to modify it.
+/// 3. Persisting any changes to the `SidebarExpandState` back to `LocalStorage`.
+///
+/// Child components (like [`TicketMenu`] and [`UsersMenu`]) can consume this context
+/// to react to and control the sidebar's collapsible sections.
+///
+/// # LocalStorage Key
+/// The state is stored under the key `STORAGE_KEY` ("sidebar_state").
+///
+/// # Example Usage
+/// ```rust
+/// html! {
+///     <SidebarStateProvider>
+///         <Sidebar /> // Sidebar and its sub-components will have access to the state
+///     </SidebarStateProvider>
+/// }
+/// ```
 #[component(SidebarStateProvider)]
 pub fn sidebar_state_provider(props: &SidebarProps) -> Html {
     let default = LocalStorage::get(STORAGE_KEY).unwrap_or_else(|_| SidebarExpandState::default());
@@ -126,6 +180,27 @@ pub fn sidebar_state_provider(props: &SidebarProps) -> Html {
     }
 }
 
+/// A collapsible menu component for "Tickets" within the sidebar.
+///
+/// This component consumes the [`SidebarState`] context to manage its expanded/collapsed state.
+/// It displays a button to toggle its visibility and, when expanded, reveals links
+/// for "Submit Ticket" and "View Tickets".
+///
+/// # Context
+/// Requires [`SidebarStateProvider`] as an ancestor to provide the necessary context.
+///
+/// # Functionality
+/// - **Toggle Button**: Clicking the button toggles the `ticket_open` state in the `SidebarState`.
+/// - **Submenu Links**:
+///   - [`crate::Route::Ticket`]: Link to submit a new ticket.
+///   - [`crate::Route::AllTickets`]: Link to view all tickets.
+///
+/// # Example
+/// ```rust
+/// html! {
+///     <TicketMenu />
+/// }
+/// ```
 #[component(TicketMenu)]
 pub fn ticket_menu() -> Html {
     let ctx =
@@ -169,6 +244,27 @@ pub fn ticket_menu() -> Html {
     }
 }
 
+/// A collapsible menu component for "Users" within the sidebar.
+///
+/// This component consumes the [`SidebarState`] context to manage its expanded/collapsed state.
+/// It displays a button to toggle its visibility and, when expanded, reveals links
+/// for "Create User" and "View Users". This menu is typically only visible to administrators.
+///
+/// # Context
+/// Requires [`SidebarStateProvider`] as an ancestor to provide the necessary context.
+///
+/// # Functionality
+/// - **Toggle Button**: Clicking the button toggles the `users_open` state in the `SidebarState`.
+/// - **Submenu Links**:
+///   - [`crate::Route::Register`]: Link to create a new user account.
+///   - [`crate::Route::AllUsers`]: Link to view all registered users.
+///
+/// # Example
+/// ```rust
+/// html! {
+///     <UsersMenu />
+/// }
+/// ```
 #[component(UsersMenu)]
 pub fn users_menu() -> Html {
     let ctx =
@@ -212,6 +308,30 @@ pub fn users_menu() -> Html {
     }
 }
 
+/// The main sidebar component of the application.
+///
+/// This component dynamically renders its content based on the user's authentication
+/// and administrative status. It fetches the current user's details via `/api/users/current`
+/// to determine what menu items to display.
+///
+/// # Structure
+/// - Wraps its content in a [`SidebarStateProvider`] to allow nested menus to manage their state.
+/// - Contains a navigation (`<nav>`) element with an unordered list (`<ul>`) of menu items.
+///
+/// # Conditional Rendering
+/// - **Loading**: Displays "Loading..." while fetching user data.
+/// - **Non-Admin User**: Renders a condensed sidebar including:
+///   - [`TicketMenu`]: For managing tickets.
+///   - A "Logout" button.
+/// - **Admin User**: Renders a full sidebar including:
+///   - [`TicketMenu`]: For managing tickets.
+///   - [`UsersMenu`]: For managing user accounts.
+///   - A direct link to [`crate::Route::Diagnostics`] (Statistiken).
+///   - A "Logout" button.
+///
+/// # Logout Functionality
+/// The "Logout" button sends a GET request to `/api/logout`, clears the user's session,
+/// and then redirects the user to the login page (`crate::Route::Login`).
 #[component(Sidebar)]
 pub fn sidebar() -> Html {
     let is_admin = use_state(|| None::<bool>);