Docs.rs comments

Comments for generating the docs with cargo doc

backend/src/handlers/ticket.rs

@@ -14,6 +14,23 @@ use crate::{
     models::{FilteredUser, TicketCreateScheme, TicketResponse, TicketUpdateScheme},
 };
 
+/// Creates a new support ticket.
+///
+/// Associates the ticket with the authenticated user and sets the current timestamp.
+/// Tickets are automatically created with "open" status.
+///
+/// # Arguments
+/// - `user`: Authenticated user (extracted from JWT token)
+/// - `body`: Ticket details (category, subject, description, room)
+///
+/// # Returns
+/// - `200 OK` on successful creation
+/// - `500 Internal Server Error` if database insertion fails
+///
+/// # Database Fields Set Automatically
+/// - `user_id`: From authenticated user
+/// - `status`: Defaults to "open"
+/// - `date`: Current UTC timestamp
 pub async fn create_ticket(
     Extension(user): Extension<FilteredUser>,
     State(data): State<Arc<AppState>>,
@@ -41,6 +58,17 @@ pub async fn create_ticket(
     Ok(Json(response_status))
 }
 
+/// Deletes a ticket by ID.
+///
+/// Only admins can delete tickets. Marks the ticket as deleted or removes from database.
+///
+/// # Arguments
+/// - `id`: Ticket ID to delete
+///
+/// # Returns
+/// - `204 No Content` on successful deletion
+/// - `404 Not Found` if ticket doesn't exist
+/// - `500 Internal Server Error` if database error occurs
 pub async fn delete_ticket(
     Path(id): Path<i32>,
     State(data): State<Arc<AppState>>,
@@ -67,10 +95,40 @@ pub async fn delete_ticket(
     Ok(StatusCode::NO_CONTENT)
 }
 
+/// Retrieves all non-archived tickets.
+///
+/// Returns a list of all active tickets with user information denormalized for easier rendering.
+/// Tickets are ordered by creation date (newest first).
+///
+/// # Filtering
+/// - Excludes tickets with status "Archived"
+/// - Uses LEFT JOIN to include creator information
+///
+/// # Returns
+/// - `200 OK` with array of TicketResponse objects
+/// - `500 Internal Server Error` if database query fails
+///
+/// # Example Response
+/// ```json
+/// [
+///   {
+///     "id": 1,
+///     "category": "maintenance",
+///     "betreff": "Broken light",
+///     "description": "Ceiling light not working",
+///     "room": 101,
+///     "status": "open",
+///     "date": "2024-01-15T10:30:00Z",
+///     "user_id": 5,
+///     "user_first_name": "John",
+///     "user_last_name": "Doe"
+///   }
+/// ]
+/// ```
 pub async fn get_tickets(
     State(data): State<Arc<AppState>>,
 ) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
-    println!("get_tickets called");
+    // Query tickets with denormalized user info, excluding archived tickets
     let tickets = sqlx::query(
         r#"SELECT t.id, t.category, t.betreff, t.description, t.room, t.status, t.date, t.user_id, u.first_name, u.last_name
            FROM tickets t
@@ -86,8 +144,8 @@ pub async fn get_tickets(
         });
         (StatusCode::INTERNAL_SERVER_ERROR, Json(error_response))
     })?;
-    println!("Tickets fetched");
 
+    // Transform raw database rows into TicketResponse structs
     let ticket_response: Vec<TicketResponse> = tickets
         .iter()
         .map(|row| TicketResponse {
@@ -105,10 +163,36 @@ pub async fn get_tickets(
         .collect();
 
     let json_response = serde_json::json!(ticket_response);
-    println!("Json contructed");
     Ok(Json(json_response))
 }
 
+/// Retrieves a specific ticket by ID.
+///
+/// Includes full ticket details and denormalized user information (creator name).
+///
+/// # Arguments
+/// - `id`: Ticket ID to retrieve
+///
+/// # Returns
+/// - `200 OK` with TicketResponse object
+/// - `404 Not Found` if ticket doesn't exist
+/// - `500 Internal Server Error` if database error occurs
+///
+/// # Example Response
+/// ```json
+/// {
+///   "id": 1,
+///   "category": "maintenance",
+///   "betreff": "Broken light in room 101",
+///   "description": "The ceiling light is not working",
+///   "room": 101,
+///   "status": "open",
+///   "date": "2024-01-15T10:30:00Z",
+///   "user_id": 5,
+///   "user_first_name": "John",
+///   "user_last_name": "Doe"
+/// }
+/// ```
 pub async fn get_ticket_by_id(
     Path(id): Path<i32>,
     State(data): State<Arc<AppState>>,
@@ -156,11 +240,30 @@ pub async fn get_ticket_by_id(
     };
 }
 
+/// Updates a ticket's status.
+///
+/// Only admins can update ticket status. This is typically used to transition tickets
+/// through their lifecycle (open → in_progress → resolved → archived).
+///
+/// # Arguments
+/// - `id`: Ticket ID to update
+/// - `body`: Update payload containing new status
+///
+/// # Returns
+/// - `200 OK` with updated TicketResponse
+/// - `500 Internal Server Error` if ticket not found or database error
+///
+/// # Typical Status Flow
+/// - `open`: Initial state, waiting for action
+/// - `in_progress`: Currently being worked on
+/// - `resolved`: Issue fixed
+/// - `archived`: Closed/hidden from normal view
 pub async fn edit_ticket(
     Path(id): Path<i32>,
     State(data): State<Arc<AppState>>,
     Json(body): Json<TicketUpdateScheme>,
 ) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
+    // Update the ticket status
     let update_result = sqlx::query(r#"UPDATE tickets SET status = $1 WHERE id = $2"#)
         .bind(body.status.to_owned())
         .bind(id)
@@ -181,6 +284,7 @@ pub async fn edit_ticket(
         return Err((StatusCode::INTERNAL_SERVER_ERROR, Json(error_response)));
     }
 
+    // Fetch and return the updated ticket
     let updated_ticket = sqlx::query(
         r#"SELECT t.id, t.category, t.betreff, t.description, t.room, t.status, t.date, t.user_id, u.first_name, u.last_name
            FROM tickets t