Doc Changes made (JhaSourav07#3309)

## Description

Fixes JhaSourav07#3308 

This PR improves project documentation by adding missing JSDoc comments
to exported utility functions and updating middleware documentation to
accurately reflect protected routes.

### Changes Made (Documentation Only — No Logic Changes)

#### `utils/urls.ts`

* Added JSDoc for `getOrigin()`

  * Documents origin resolution priority chain:

    * `window.location.origin`
    * Environment variable
    * Local fallback
* Added JSDoc for `getDashboardUrl()`

  * Includes `@param` and `@returns`

#### `utils/tracking.ts`

* Added JSDoc for `trackUser()`

  * Documents beacon-first / fetch-fallback tracking strategy
  * Explains no-op conditions
  * Includes parameter and return documentation

#### `utils/dashboardPeriod.ts`

* Added JSDoc for `resolveDashboardPeriod()`

  * Documents period resolution priority chain
* Added JSDoc for `shiftDashboardPeriod()`

  * Documents period shifting behavior for each period type
* Added JSDoc for `dashboardPeriodToSearchParams()`

  * Documents query parameter serialization behavior

#### `middleware.ts`

* Updated existing JSDoc header
* Added `/api/compare` to the protected routes list to match the
middleware matcher configuration

### Impact

* Improves code readability and maintainability
* Enhances IDE autocomplete and hover documentation
* Makes onboarding easier for new contributors
* Ensures documentation remains consistent with implementation
* No functional or behavioral changes

---

## Pillar

* [ ] 🎨 Pillar 1 — New Theme Design
* [ ] 📐 Pillar 2 — Geometric SVG Improvement
* [ ] 🕐 Pillar 3 — Timezone Logic Optimization
* [x] 🛠️ Other (Bug fix, refactoring, docs)

---

## Visual Preview

N/A – Documentation-only changes with no UI or SVG modifications.

---

## Checklist before requesting a review:

* [x] I have read the `CONTRIBUTING.md` file.
* [x] I have tested these changes locally
(`localhost:3000/api/streak?user=YOUR_USERNAME`).
* [x] I have run `npm run format` and `npm run lint` locally and
resolved all errors (CI will fail otherwise).
* [x] My commits follow the Conventional Commits format (e.g.,
`feat(themes): ...`, `fix(calculate): ...`).
* [x] I have updated `README.md` if I added a new theme or URL
parameter. (Not applicable)
* [x] I have starred the repo.
* [x] I have made sure that I have only one commit to merge in this PR.
* [x] The SVG output matches the CommitPulse "premium quality" aesthetic
standard (no raw elements, smooth animations, correct fonts).
* [x] (Recommended) I joined the CommitPulse Discord community for
contributor discussions, mentorship, and faster PR support.

Author: JhaSourav07

middleware.ts

@@ -13,6 +13,7 @@ import { getClientIp } from './utils/getClientIp';
  * - /api/stats
  * - /api/og
  * - /api/notify
+ * - /api/compare
  *
  * Limit: 60 requests per minute per IP.
  */

utils/dashboardPeriod.ts

@@ -74,6 +74,19 @@ function formatRollingLabel(start: Date, end: Date): string {
   return `${formatter.format(start)} to ${formatter.format(end)}`;
 }
 
+/**
+ * Resolves a {@link DashboardPeriod} from a loose set of URL search-param inputs.
+ *
+ * Resolution priority (first match wins):
+ * 1. **Custom range** — both `input.from` and `input.to` are valid ISO date strings.
+ * 2. **Month** — `input.month` matches `YYYY-MM` and represents a valid calendar month.
+ * 3. **Year** — `input.year` matches `YYYY` and falls within the range 2008–(now+5).
+ * 4. **Rolling 12 months** — default fallback when none of the above match.
+ *
+ * @param {DashboardPeriodInput} input - Raw query-string values (year, month, from, to).
+ * @param {Date} [now=new Date()] - Reference date used for the rolling-window default and year validation.
+ * @returns {DashboardPeriod} A fully resolved period object with `kind`, `label`, `from`, and `to`.
+ */
 export function resolveDashboardPeriod(
   input: DashboardPeriodInput,
   now: Date = new Date()
@@ -145,6 +158,22 @@ export function resolveDashboardPeriod(
   };
 }
 
+/**
+ * Shifts a {@link DashboardPeriod} one step forwards or backwards.
+ *
+ * Shift semantics vary by period kind:
+ * - **month** — moves to the previous or next calendar month.
+ * - **year** — moves to the previous or next calendar year.
+ * - **range** — shifts by the exact number of days spanned by the current range.
+ * - **rolling** — shifts the 12-month window by one month in the requested direction.
+ *
+ * The function always delegates to {@link resolveDashboardPeriod} so that the returned
+ * period is normalised and fully hydrated.
+ *
+ * @param {DashboardPeriod} period - The currently active period.
+ * @param {'prev' | 'next'} direction - Direction to shift: `'prev'` for earlier, `'next'` for later.
+ * @returns {DashboardPeriod} The shifted, fully resolved period.
+ */
 export function shiftDashboardPeriod(
   period: DashboardPeriod,
   direction: 'prev' | 'next'
@@ -183,6 +212,18 @@ export function shiftDashboardPeriod(
   return resolveDashboardPeriod({ from: shiftedFrom.toISOString(), to: shiftedTo.toISOString() });
 }
 
+/**
+ * Serialises a {@link DashboardPeriod} into a `URLSearchParams` instance suitable for
+ * appending to a dashboard URL.
+ *
+ * Serialisation strategy:
+ * - **month** — emits a single `month=YYYY-MM` param.
+ * - **year** — emits a single `year=YYYY` param.
+ * - **range / rolling** — emits `from` and `to` ISO timestamp params.
+ *
+ * @param {DashboardPeriod} period - The period to serialise.
+ * @returns {URLSearchParams} The query-string representation of the period.
+ */
 export function dashboardPeriodToSearchParams(period: DashboardPeriod): URLSearchParams {
   const params = new URLSearchParams();
 

utils/tracking.ts

@@ -1,3 +1,16 @@
+/**
+ * Fires a fire-and-forget analytics ping to `/api/track-user` for the given GitHub username.
+ *
+ * Uses `navigator.sendBeacon` when available (reliable on page unload), falling back to
+ * `fetch` with `keepalive: true` for environments that do not support the Beacon API.
+ *
+ * The function is a no-op when:
+ * - Running outside of a browser context (`navigator` or `window` is undefined).
+ * - `username` is an empty string or falsy.
+ *
+ * @param {string} username - The GitHub username to record the visit for.
+ * @returns {void}
+ */
 export function trackUser(username: string) {
   if (typeof navigator === 'undefined' || typeof window === 'undefined') return;
   if (!username) return;

utils/urls.ts

@@ -1,12 +1,28 @@
 const FALLBACK_ORIGIN = 'https://commitpulse.vercel.app';
 
+/**
+ * Resolves the base origin URL for the current environment.
+ *
+ * Priority order:
+ * 1. `window.location.origin` — used when running in the browser.
+ * 2. `NEXT_PUBLIC_SITE_URL` environment variable — used in server-side contexts.
+ * 3. Hardcoded fallback (`https://commitpulse.vercel.app`).
+ *
+ * @returns {string} The resolved base origin URL (e.g. `https://commitpulse.app` or `http://localhost:3000`).
+ */
 export function getOrigin(): string {
   const envOrigin = process.env.NEXT_PUBLIC_SITE_URL?.trim() || null;
   return (
     (typeof window !== 'undefined' ? window.location.origin : null) ?? envOrigin ?? FALLBACK_ORIGIN
   );
 }
 
+/**
+ * Constructs the full absolute URL for a user's dashboard page.
+ *
+ * @param {string} username - The GitHub username whose dashboard URL should be generated.
+ * @returns {string} The absolute dashboard URL (e.g. `https://commitpulse.app/dashboard/octocat`).
+ */
 export function getDashboardUrl(username: string): string {
   return `${getOrigin()}/dashboard/${encodeURIComponent(username)}`;
 }