From 946d6ea0ca9c5d0b82140bc74a5f5c28d1d0d137 Mon Sep 17 00:00:00 2001
From: JakkrapartXD <jakkrapart_in66@live.rmutl.ac.th>
Date: Mon, 19 Jan 2026 10:09:10 +0700
Subject: [PATCH] docs: Add JSDoc comments to all instructor course controller
 methods and update HTTP verbs for instructor management endpoints.

---
 .../CoursesInstructorController.ts            | 57 ++++++++++++++++++-
 1 file changed, 54 insertions(+), 3 deletions(-)

diff --git a/Backend/src/controllers/CoursesInstructorController.ts b/Backend/src/controllers/CoursesInstructorController.ts
index 761471df..8682d2af 100644
--- a/Backend/src/controllers/CoursesInstructorController.ts
+++ b/Backend/src/controllers/CoursesInstructorController.ts
@@ -1,4 +1,4 @@
-import { Get, Body, Post, Route, Tags, SuccessResponse, Response, Security, Put, Path, Delete, Request } from 'tsoa';
+import { Get, Body, Post, Route, Tags, SuccessResponse, Response, Security, Put, Path, Delete, Request, Example } from 'tsoa';
 import { ValidationError } from '../middleware/errorHandler';
 import { CoursesInstructorService } from '../services/CoursesInstructor.service';
 import {
@@ -27,6 +27,10 @@ import { config } from '../config';
 @Tags('CoursesInstructor')
 export class CoursesInstructorController {
 
+    /**
+     * ดึงรายการคอร์สทั้งหมดของผู้สอน
+     * Get all courses where the authenticated user is an instructor
+     */
     @Get('')
     @Security('jwt', ['instructor'])
     @SuccessResponse('200', 'Courses retrieved successfully')
@@ -40,6 +44,11 @@ export class CoursesInstructorController {
         return await CoursesInstructorService.listMyCourses(token);
     }
 
+    /**
+     * ดึงข้อมูลคอร์สเฉพาะของผู้สอน (พร้อมบทเรียนและเนื้อหา)
+     * Get detailed course information including chapters, lessons, attachments, and quizzes
+     * @param courseId - รหัสคอร์ส / Course ID
+     */
     @Get('{courseId}')
     @Security('jwt', ['instructor'])
     @SuccessResponse('200', 'Course retrieved successfully')
@@ -53,6 +62,11 @@ export class CoursesInstructorController {
         return await CoursesInstructorService.getmyCourse({ token, course_id: courseId });
     }
 
+    /**
+     * แก้ไขข้อมูลคอร์ส
+     * Update course information (only for course instructors)
+     * @param courseId - รหัสคอร์ส / Course ID
+     */
     @Put('{courseId}')
     @Security('jwt', ['instructor'])
     @SuccessResponse('200', 'Course updated successfully')
@@ -66,6 +80,10 @@ export class CoursesInstructorController {
         return await CoursesInstructorService.updateCourse(token, courseId, body.data);
     }
 
+    /**
+     * สร้างคอร์สใหม่
+     * Create a new course (status will be DRAFT by default)
+     */
     @Post('')
     @Security('jwt', ['instructor'])
     @SuccessResponse('201', 'Course created successfully')
@@ -80,6 +98,11 @@ export class CoursesInstructorController {
         return course;
     }
 
+    /**
+     * ลบคอร์ส (เฉพาะผู้สอนหลักเท่านั้น)
+     * Delete a course (only primary instructor can delete)
+     * @param courseId - รหัสคอร์ส / Course ID
+     */
     @Delete('{courseId}')
     @Security('jwt', ['instructor'])
     @SuccessResponse('200', 'Course deleted successfully')
@@ -93,6 +116,11 @@ export class CoursesInstructorController {
         return await CoursesInstructorService.deleteCourse(token, courseId);
     }
 
+    /**
+     * ส่งคอร์สเพื่อขออนุมัติจากแอดมิน
+     * Submit course for admin review and approval
+     * @param courseId - รหัสคอร์ส / Course ID
+     */
     @Post('send-review/{courseId}')
     @Security('jwt', ['instructor'])
     @SuccessResponse('200', 'Course submitted successfully')
@@ -106,6 +134,11 @@ export class CoursesInstructorController {
         return await CoursesInstructorService.sendCourseForReview({ token, course_id: courseId });
     }
 
+    /**
+     * ดึงรายชื่อผู้สอนทั้งหมดในคอร์ส
+     * Get list of all instructors in a specific course
+     * @param courseId - รหัสคอร์ส / Course ID
+     */
     @Get('listinstructor/{courseId}')
     @Security('jwt', ['instructor'])
     @SuccessResponse('200', 'Instructors retrieved successfully')
@@ -119,6 +152,12 @@ export class CoursesInstructorController {
         return await CoursesInstructorService.listInstructorsOfCourse({ token, course_id: courseId });
     }
 
+    /**
+     * เพิ่มผู้สอนเข้าในคอร์ส
+     * Add a new instructor to the course
+     * @param courseId - รหัสคอร์ส / Course ID
+     * @param userId - รหัสผู้ใช้ที่ต้องการเพิ่มเป็นผู้สอน / User ID to add as instructor
+     */
     @Post('add-instructor/{courseId}/{userId}')
     @Security('jwt', ['instructor'])
     @SuccessResponse('200', 'Instructor added successfully')
@@ -132,7 +171,13 @@ export class CoursesInstructorController {
         return await CoursesInstructorService.addInstructorToCourse({ token, course_id: courseId, user_id: userId });
     }
 
-    @Post('remove-instructor/{courseId}/{userId}')
+    /**
+     * ลบผู้สอนออกจากคอร์ส
+     * Remove an instructor from the course
+     * @param courseId - รหัสคอร์ส / Course ID
+     * @param userId - รหัสผู้ใช้ที่ต้องการลบออกจากผู้สอน / User ID to remove from instructors
+     */
+    @Delete('remove-instructor/{courseId}/{userId}')
     @Security('jwt', ['instructor'])
     @SuccessResponse('200', 'Instructor removed successfully')
     @Response('401', 'Invalid or expired token')
@@ -145,7 +190,13 @@ export class CoursesInstructorController {
         return await CoursesInstructorService.removeInstructorFromCourse({ token, course_id: courseId, user_id: userId });
     }
 
-    @Post('set-primary-instructor/{courseId}/{userId}')
+    /**
+     * กำหนดผู้สอนหลักของคอร์ส
+     * Set a user as the primary instructor of the course
+     * @param courseId - รหัสคอร์ส / Course ID
+     * @param userId - รหัสผู้ใช้ที่ต้องการตั้งเป็นผู้สอนหลัก / User ID to set as primary instructor
+     */
+    @Put('set-primary-instructor/{courseId}/{userId}')
     @Security('jwt', ['instructor'])
     @SuccessResponse('200', 'Primary instructor set successfully')
     @Response('401', 'Invalid or expired token')