📝 docs: add documentation for bulk insert episode

src/modules/internal/controllers/bulkInsertEpisode.controller.ts

@@ -3,7 +3,44 @@ import { mainErrorHandler } from "../../../helpers/error/handler";
 import { bulkInsertEpisodeService } from "../services/http/bulkInsertEpisode.service";
 import { returnWriteResponse } from "../../../helpers/callback/httpResponse";
 
-// add pagination query
+/**
+ * @function bulkInsertMediaController
+ * @description Perform bulk insert of episodes for a specific media. This operation fetches episode data from external sources and inserts them into the database. The page parameter is optional; if not provided, the first page of episodes will be fetched.
+ *
+ * @param {Context & { body: { media_mal_id: number }; query: { page?: number } }} ctx
+ * The context object containing the request body.
+ * The body must include:
+ * - media_mal_id: number - The MyAnimeList ID of the media for which episodes will be inserted.
+ * The query may include:
+ * - page?: number - (Optional) The page number of episodes to fetch and insert. If not provided, defaults to the first page.
+ *
+ * @example
+ * Request route: POST /internal/episode/bulk-insert
+ * Request body:
+ * {
+ *   "media_mal_id": 12345
+ * }
+ *
+ * @returns {Promise<Object>}
+ * A response object indicating success or failure.
+ * Return example:
+ * {
+ *   success: true,
+ *   status: 201,
+ *   message: "Bulk insert episode operation completed successfully",
+ *   data: { ...bulkInsertResult } // Data returned only if the env run on development mode
+ * }
+ *
+ * @throws {Object}
+ * An error response object if validation fails or an error occurs during bulk insert operation.
+ * Return example:
+ * {
+ *   success: false,
+ *   status: <Status Code>,
+ *   message: "<Error Message>",
+ *   error: { ...errorDetails } // Additional error details if available and the env run on development mode
+ * }
+ */
 export const bulkInsertEpisodeController = async (
   ctx: Context & { body: { media_mal_id: number }; query: { page?: number } },
 ) => {
@@ -15,7 +52,7 @@ export const bulkInsertEpisodeController = async (
     return returnWriteResponse(
       ctx.set,
       201,
-      "Success bulk insert for episode",
+      "Bulk insert episode operation completed successfully",
       bulkInsertResult,
     );
   } catch (err) {