📝 Add docstrings to api-routes

app/api/events/[slug]/route.ts

@@ -11,8 +11,15 @@ type RouteParams = {
 };
 
 /**
- * GET /api/events/[slug]
- * Fetches a single events by its slug
+ * Fetches a single event by its slug and returns the event or an appropriate HTTP error response.
+ *
+ * @param req - The incoming Next.js request (unused by this handler).
+ * @param params - An object whose promise resolves to `{ slug: string }`; the slug to look up.
+ * @returns A NextResponse containing the event on success or an error message with one of these statuses:
+ * - `200` when the event is found (body includes `event` and `message`)
+ * - `400` when the slug is missing or invalid
+ * - `404` when no event matches the slug
+ * - `500` for database/configuration or other unexpected errors
  */
 export async function GET(
   req: NextRequest,
@@ -83,4 +90,4 @@ export async function GET(
       { status: 500 }
     );
   }
-}
+}

app/api/events/route.ts

@@ -3,6 +3,18 @@ import { v2 as cloudinary } from "cloudinary";
 import connectDB from "@/lib/mongodb";
 import { NextRequest, NextResponse } from "next/server";
 
+/**
+ * Handle POST requests to create a new event with image upload and persist it to the database.
+ *
+ * Validates and parses multipart form data, requires an `image` file, parses `tags` and `agenda`
+ * fields as JSON, uploads the image to Cloudinary, attaches the uploaded image URL to the event
+ * payload, and creates an Event document.
+ *
+ * @returns A JSON response:
+ * - On success: a message "Event Created Successfully" and the created `event`.
+ * - On client validation errors: a JSON message explaining the issue (e.g., "Invalid JSON data format" or "Image file is required") with a 400 status.
+ * - On server errors: a message "Event Creation Failed" and an `error` string with a 500 status.
+ */
 export async function POST(req: NextRequest) {
   try {
     await connectDB();
@@ -69,6 +81,11 @@ export async function POST(req: NextRequest) {
   }
 }
 
+/**
+ * Retrieve all events from the database, sorted by creation time descending.
+ *
+ * @returns On success, an object with `message: "Events fetched successfully"` and an `events` array (HTTP 200). If no events exist, an object with `message: "No event found"` (HTTP 404). On failure, an object with `message: "Failed to fetch events"` and an `error` string describing the failure (HTTP 500).
+ */
 export async function GET() {
   try {
     await connectDB();
@@ -91,4 +108,4 @@ export async function GET() {
       { status: 500 }
     );
   }
-}
+}

database/event.model.ts

@@ -129,7 +129,12 @@ EventSchema.pre("save", function () {
   }
 });
 
-// Helper function to generate URL-friendly slug
+/**
+ * Creates a URL-friendly slug from an event title.
+ *
+ * @param title - The input title to convert into a slug
+ * @returns A lowercase, trimmed slug containing only letters, numbers, and single hyphens with no leading or trailing hyphens
+ */
 function generateSlug(title: string): string {
   return title
     .toLowerCase()
@@ -140,7 +145,13 @@ function generateSlug(title: string): string {
     .replace(/^-|-$/g, ""); // Remove leading/trailing hyphens
 }
 
-// Helper function to normalize date to ISO format
+/**
+ * Normalize an input date string to the ISO date portion (YYYY-MM-DD).
+ *
+ * @param dateString - A value parseable by the JavaScript Date constructor.
+ * @returns The date formatted as `YYYY-MM-DD`.
+ * @throws Error if `dateString` cannot be parsed as a valid date.
+ */
 function normalizeDate(dateString: string): string {
   const date = new Date(dateString);
   if (isNaN(date.getTime())) {
@@ -149,7 +160,13 @@ function normalizeDate(dateString: string): string {
   return date.toISOString().split("T")[0]; // Return YYYY-MM-DD format
 }
 
-// Helper function to normalize time format
+/**
+ * Normalize a time string into 24-hour "HH:MM" format.
+ *
+ * @param timeString - Time in formats like "H:MM", "HH:MM", or with an AM/PM suffix (e.g., "2:30 PM", "14:30"); case and surrounding whitespace are allowed.
+ * @returns The time converted to 24-hour `HH:MM` format.
+ * @throws Error if the input does not match supported time formats or contains invalid hour or minute values.
+ */
 function normalizeTime(timeString: string): string {
   // Handle various time formats and convert to HH:MM (24-hour format)
   const timeRegex = /^(\d{1,2}):(\d{2})(\s*(AM|PM))?$/i;
@@ -189,4 +206,4 @@ EventSchema.index({ date: 1, mode: 1 });
 
 const Event = models.Event || model<IEvent>("Event", EventSchema);
 
-export default Event;
+export default Event;