v1.5.0: Complete documentation rewrite - 50+ files with AlisaReactionBot style

- Box-style header comments (Project, Author, License) on every file
- Section headers using double-line box decorators
- Feature markers (// ---- FEATURE: XYZ ----) before every major function
- JSDoc comments for EVERY function with @param, @returns, @example
- Inline notes (NOTE, WARNING, TIP) for non-obvious logic
- Footer END markers on every module
- Matched code style to AlisaReactionBot repository
- All files now searchable by feature name via grep

Author: Shinei Nouzen <157171073+Shineii86@users.noreply.github.com>

src/controllers/search.controller.js

@@ -1,19 +1,56 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKatoAPI — search.controller.js
+ * Repository: https://github.com/Shineii86/AniKatoAPI
+ *
+ * @description
+ *   Controller for search functionality. Provides both full search
+ *   results with pagination and lightweight autocomplete suggestions.
+ *   Both endpoints require a 'keyword' query parameter.
+ *
+ * @exports
+ *   getSearchResults - Express route handler for GET /api/search
+ *   getSearchSuggestions - Express route handler for GET /api/search/suggest
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
 import { extractSearchResults, extractSearchSuggestions } from "../extractors/search.extractor.js";
 import { getCache, setCache } from "../helper/cache.helper.js";
 
+// ══════════════════════════════════════════════════════════════
+// CONTROLLER: SEARCH RESULTS
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Full search results endpoint ----
+/**
+ * Handles GET /api/search requests with keyword and optional page.
+ * Returns paginated search results from the source site.
+ *
+ * @param {object} req - Express request object
+ * @param {object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {void} Sends JSON response with search results
+ *
+ * @example
+ *   GET /api/search?keyword=naruto&page=2
+ *   Response: { success: true, results: { anime, ... } }
+ *
+ * @throws {400} If 'keyword' query parameter is missing
+ */
 const getSearchResults = async (req, res, next) => {
   try {
     const { keyword, page = 1 } = req.query;
     if (!keyword) {
       return res.status(400).json({ success: false, message: "Keyword is required" });
     }
-
     const cacheKey = `search_${keyword}_${page}`;
     const cached = getCache(cacheKey);
     if (cached) {
       return res.json({ success: true, results: cached });
     }
-
     const data = await extractSearchResults(keyword, page);
     setCache(cacheKey, data);
     res.json({ success: true, results: data });
@@ -22,19 +59,37 @@ const getSearchResults = async (req, res, next) => {
   }
 };
 
+// ══════════════════════════════════════════════════════════════
+// CONTROLLER: SEARCH SUGGESTIONS
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Search autocomplete suggestions endpoint ----
+/**
+ * Handles GET /api/search/suggest requests for autocomplete.
+ * Returns lightweight suggestion list for the given keyword.
+ *
+ * @param {object} req - Express request object
+ * @param {object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {void} Sends JSON response with suggestion list
+ *
+ * @example
+ *   GET /api/search/suggest?keyword=nar
+ *   Response: { success: true, results: [{ id, title, ... }] }
+ *
+ * @throws {400} If 'keyword' query parameter is missing
+ */
 const getSearchSuggestions = async (req, res, next) => {
   try {
     const { keyword } = req.query;
     if (!keyword) {
       return res.status(400).json({ success: false, message: "Keyword is required" });
     }
-
     const cacheKey = `suggest_${keyword}`;
     const cached = getCache(cacheKey);
     if (cached) {
       return res.json({ success: true, results: cached });
     }
-
     const data = await extractSearchSuggestions(keyword);
     setCache(cacheKey, data);
     res.json({ success: true, results: data });
@@ -43,4 +98,6 @@ const getSearchSuggestions = async (req, res, next) => {
   }
 };
 
-export { getSearchResults, getSearchSuggestions };
+export { getSearchResults, getSearchSuggestions };
+
+// ══════════════════════════════════════════════════════════════ END: search.controller.js