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/extractors/trendingSidebar.extractor.js

@@ -1,10 +1,55 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKatoAPI — trendingSidebar.extractor.js
+ * Repository: https://github.com/Shineii86/AniKatoAPI
+ *
+ * @description
+ *   Extracts trending sidebar data including top anime rankings
+ *   and latest episodes. Provides comprehensive sidebar content.
+ *
+ * @exports
+ *   extractTrendingSidebar
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
 import * as cheerio from "cheerio";
 import axios from "axios";
 import { headers } from "../configs/header.config.js";
 import { URLS } from "../configs/dataUrl.js";
 
+// ══════════════════════════════════════════════════════════════
+// TRENDING SIDEBAR EXTRACTION
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Extract trending sidebar with top rankings and latest episodes ----
+/**
+ * Fetches and parses the trending sidebar from the homepage.
+ * Returns daily, weekly, and monthly top anime plus latest episodes.
+ *
+ * @returns {Promise<Object>} Object containing day, week, month, and latestEpisodes
+ * @returns {Array<Object>} return.day - Daily top anime
+ * @returns {Array<Object>} return.week - Weekly top anime
+ * @returns {Array<Object>} return.month - Monthly top anime
+ * @returns {Array<Object>} return.latestEpisodes - Recently updated episodes
+ * @returns {string} return.day[].slug - URL slug for the anime
+ * @returns {number} return.day[].rank - Ranking position
+ * @returns {string} return.day[].name - Anime name
+ * @returns {string} return.day[].poster - Poster image URL
+ * @returns {number} return.day[].sub - Subbed episode count
+ * @returns {number} return.day[].dub - Dubbed episode count
+ * @returns {string} return.day[].type - Anime type
+ *
+ * @example
+ *   const sidebar = await extractTrendingSidebar();
+ *   console.log(sidebar.day[0].name); // Top anime today
+ *   console.log(sidebar.latestEpisodes[0].title); // Latest episode
+ */
 const extractTrendingSidebar = async () => {
   try {
+    // NOTE: The sidebar content is embedded in the homepage HTML
     const { data } = await axios.get(URLS.home, { headers });
     const $ = cheerio.load(data);
 
@@ -12,6 +57,7 @@ const extractTrendingSidebar = async () => {
     const week = [];
     const month = [];
 
+    // NOTE: Daily rankings use the 'day' tab content
     $("#top-anime .tab-content[data-name='day'] a.item").each((i, el) => {
       const slug = $(el).attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find(".poster img").attr("src") || "";
@@ -21,11 +67,13 @@ const extractTrendingSidebar = async () => {
       const type = $(el).find(".type").text().trim() || "";
       const rank = i + 1;
 
+      // NOTE: Only include items with valid slugs
       if (slug) {
         day.push({ slug, rank, name, poster, sub, dub, type });
       }
     });
 
+    // NOTE: Weekly rankings use the 'week' tab content
     $("#top-anime .tab-content[data-name='week'] a.item").each((i, el) => {
       const slug = $(el).attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find(".poster img").attr("src") || "";
@@ -40,6 +88,7 @@ const extractTrendingSidebar = async () => {
       }
     });
 
+    // NOTE: Monthly rankings use the 'month' tab content
     $("#top-anime .tab-content[data-name='month'] a.item").each((i, el) => {
       const slug = $(el).attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find(".poster img").attr("src") || "";
@@ -54,6 +103,7 @@ const extractTrendingSidebar = async () => {
       }
     });
 
+    // NOTE: Latest episodes section provides recently updated content
     const latestEpisodes = [];
     $("#recent-update .item, .section-updated .item").each((i, el) => {
       const slug = $(el).find("a.name.d-title").attr("href")?.split("/watch/").pop() || "";
@@ -76,4 +126,6 @@ const extractTrendingSidebar = async () => {
   }
 };
 
-export { extractTrendingSidebar };
+export { extractTrendingSidebar };
+
+// ══════════════════════════════════════════════════════════════ END: trendingSidebar.extractor.js