From e0f17cf72ce7c5c2416f5c84a5de758d2bdad559 Mon Sep 17 00:00:00 2001
From: Ahmed Elbohoty <a.ramzielbohoty@gmail.com>
Date: Tue, 10 Sep 2024 19:02:07 +0300
Subject: [PATCH] jsdoc: Add jsdoc for generateId and race API

---
 src/lib/race.ts        | 38 ++++++++++++++++++++++++++++++++++++++
 src/lib/utils/utils.ts | 16 ++++++++++++++++
 tsconfig.json          |  1 -
 3 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/src/lib/race.ts b/src/lib/race.ts
index e700812..8e24ddc 100644
--- a/src/lib/race.ts
+++ b/src/lib/race.ts
@@ -14,6 +14,44 @@ import { type Options, validateOptions } from './options';
 import { registerEvents, DOMEventSubscriber, getTickDetails, type EventType } from './events';
 import type { Race, ApiCallback } from './models';
 
+/**
+ * The main function that generates the racing bar chart.
+ *
+ * @param {Data[] | WideData[] | Promise<Data[]> | Promise<WideData[]> | string} data
+ * The data for the race visualization can be one of:
+ * ```text
+ * 1- Array of `Data` objects.
+ * 2- Array of `WideData` objects.
+ * 3- Promise that resolves to an array of `Data` objects.
+ * 4- Promise that resolves to an array of `WideData` objects.
+ * 5- String representing the file path to load the data from.
+ * ```
+ * @see {@link https://racing-bars.hatemhosny.dev/documentation/data/} for more information.
+ *
+ * @param {string | HTMLElement} [container] Optional. The container element or selector.
+ * If not provided, a new `<div>` element will be created and appended to the document body.
+ *
+ * @param {Partial<Options>} [options={}] Optional. Configuration object for chart options. Defaults to an empty object.
+ * @see {@link https://racing-bars.hatemhosny.dev/api/internal/interfaces/Options/} for detailed options.
+ *
+ * @returns {Promise<Race>} The function returns a promise that resolves to an object that allows interaction with the chart.
+ *
+ * @example
+ * const data: Data[] | WideData[] | Promise<Data[]> | Promise<WideData[]> | string = [ ...fill with data... ];
+ *
+ * const container = document.getElementById('race-container');
+ *
+ * const options: Partial<Options>  = {
+ *   width: 800,
+ *   height: 400,
+ * };
+ *
+ * const raceAPI = await race(data, container, options);
+ *
+ * raceAPI.play();
+ *
+ * @see {@link https://racing-bars.hatemhosny.dev/documentation/api#race} for more details.
+ */
 export async function race(
   data: Data[] | WideData[] | Promise<Data[]> | Promise<WideData[]> | string,
   container?: string | HTMLElement,
diff --git a/src/lib/utils/utils.ts b/src/lib/utils/utils.ts
index 60449e4..80e5e8c 100644
--- a/src/lib/utils/utils.ts
+++ b/src/lib/utils/utils.ts
@@ -86,6 +86,22 @@ export function shuffle(arr: string[], seed: number) {
   return array;
 }
 
+/**
+ * Generates a unique identifier with a given prefix and length.
+ *
+ * @param {string} [prefix='racingbars'] - The prefix to be added to the generated identifier. Default is 'racingbars'.
+ * @param {number} [n=8] - The length of the generated identifier. Default is 8.
+ *
+ * @returns The generated unique identifier.
+ *
+ * @example
+ * ```
+ * const id = generateId('hello', 5);
+ * console.log(id); // Output: helloxxxxx
+ * ```
+ *
+ * @see {@link https://racing-bars.hatemhosny.dev/api/functions/generateId/} for more details.
+ */
 export function generateId(prefix = 'racingbars', n = 8) {
   const rnd = Array(3)
     .fill(null)
diff --git a/tsconfig.json b/tsconfig.json
index 003e2c9..29747b3 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -13,7 +13,6 @@
     "allowUmdGlobalAccess": true,
     "forceConsistentCasingInFileNames": true,
     "importHelpers": true,
-    "removeComments": true,
 
     /* Strict Type-Checking Options */
     // "noImplicitAny": true /* Raise error on expressions and declarations with an implied 'any' type. */,