📝 Add docstrings to feature/add-api-routes

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

@@ -10,8 +10,10 @@ type RouteParams = {
 }
 
 /**
- * GET /api/events/[slug]
- * Fetches a single events by its slug
+ * Fetches an event by its slug and returns the result as a JSON response.
+ *
+ * @param params - Route params (a promise resolving to an object with a `slug` string)
+ * @returns A NextResponse whose JSON body includes `message` and `success`; when an event is found the body also includes `event`; on failure the body may include `error`. The response status is 200 on success, 400 for invalid input, 404 if not found, 503 for database connection issues, or 500 for other errors.
  */
 export async function GET(
   req: NextRequest,
@@ -98,4 +100,4 @@ export async function GET(
       { status: 500 }
     );
   }
-}
+}

app/api/events/route.ts

@@ -4,6 +4,14 @@ import connectDB from "@/lib/mongodb";
 import Event from '@/database/event.model';
 
 
+/**
+ * Create a new event from multipart/form-data and persist it to the database.
+ *
+ * Expects form fields including `image` (file), `tags` (JSON string), and `agenda` (JSON string). Uploads the provided image to Cloudinary, assigns the uploaded image URL to the event, saves the event document, and returns the created record on success.
+ *
+ * @param req - Incoming NextRequest containing multipart/form-data with event fields and the `image` file
+ * @returns JSON response with a success or error message. On success (status 201) includes the created event object; responds with status 400 for malformed input (e.g., missing image or invalid JSON fields) and 500 for server errors.
+ */
 export async function POST(req: NextRequest){    try{
         await connectDB();
         console.log("1. 🚀 ROUTE: Handing data to the Model...");
@@ -53,6 +61,11 @@ export async function POST(req: NextRequest){    try{
     }
 }
 
+/**
+ * Handle GET requests to retrieve all events sorted by newest first.
+ *
+ * @returns A NextResponse with a JSON body: on success `{ message, events }` and HTTP status 200; on failure `{ message, error }` and HTTP status 500.
+ */
 export async function GET(){
     try {
         await connectDB();
@@ -64,4 +77,4 @@ export async function GET(){
     } catch (e) {
         return NextResponse.json({message: 'Event Fetching failed', error:e}, { status: 500});
     }
-}
+}

database/event.model.ts

@@ -150,7 +150,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 to 24-hour "HH:MM" format.
+ *
+ * @param timeString - A time expressed as "HH:MM" or "HH:MM AM/PM" (case-insensitive, optional AM/PM).
+ * @returns The time formatted as `HH:MM` using a 24-hour clock.
+ * @throws Error if the input does not match accepted formats or contains invalid hour/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;

lib/mongodb.ts

@@ -23,9 +23,15 @@ if (!global.mongoose) {
 }
 
 /**
- * Establishes a connection to MongoDB using Mongoose.
- * Caches the connection to prevent multiple connections during development hot reloads.
- * @returns Promise resolving to the Mongoose instance
+ * Establishes and caches a Mongoose connection to the MongoDB instance.
+ *
+ * Caches the connection to avoid creating multiple connections across hot reloads
+ * (e.g., in development). If a connection or connection promise already exists,
+ * the cached value is reused.
+ *
+ * @returns The connected Mongoose instance
+ * @throws Error if the `MONGODB_URI` environment variable is not defined
+ * @throws Any error thrown while attempting to establish the connection
  */
 async function connectDB(): Promise<typeof mongoose> {
     // Return existing connection if available