From 2ce1f108a6c5f9b500f5c5a7193be944a683a190 Mon Sep 17 00:00:00 2001
From: Gabb-c <gdgabrieldacunha71@gmail.com>
Date: Wed, 3 Jul 2024 13:57:41 -0300
Subject: [PATCH] docs: update base client documentation

---
 src/clients/base.ts | 42 +++++++++++++++++++++++++++++++-----------
 1 file changed, 31 insertions(+), 11 deletions(-)

diff --git a/src/clients/base.ts b/src/clients/base.ts
index 4babc5e1..0115edf4 100644
--- a/src/clients/base.ts
+++ b/src/clients/base.ts
@@ -21,28 +21,23 @@ import type { NamedAPIResourceList } from "../models/Common/resource";
  * Used to pass optional configuration for logging and cache to the clients.
  */
 export interface ClientArgs {
-  /**
-   * ## Enable logs
-   */
+  /** Enables or disables logging. */
   logs?: boolean;
   /**
-   * ## Axios Cache Options
-   * Options for cache.
+   * Options for cache configuration.
    * @see https://axios-cache-interceptor.js.org/
    */
   cacheOptions?: CacheOptions;
-  /**
-   * ## Base URL
-   * Location of the PokéAPI. Leave empty to use the official PokéAPI instance.
-   */
+  /** Location of the PokéAPI. Leave empty to use the official PokéAPI instance. */
   baseURL?: string;
 }
 
 /**
- * ### Base Client
+ * ## Base Client
+ * Base class for interacting with the PokéAPI. Provides methods for resource retrieval with caching and logging capabilities.
  */
 export class BaseClient {
-  private api: AxiosCacheInstance;
+  private readonly api: AxiosCacheInstance;
 
   constructor(clientOptions?: ClientArgs) {
     this.api = setupCache(
@@ -55,6 +50,7 @@ export class BaseClient {
       clientOptions?.cacheOptions,
     );
 
+    // Setting up request and response interceptors for logging
     this.api.interceptors.request.use(
       (config: InternalCacheRequestConfig) => handleRequest(config, clientOptions?.logs),
       (error: AxiosError<string>) => handleRequestError(error, clientOptions?.logs),
@@ -66,17 +62,41 @@ export class BaseClient {
     );
   }
 
+  /**
+   * Retrieves a single resource from the PokéAPI by its endpoint and identifier.
+   *
+   * @template T - The type of the resource to be returned.
+   * @param endpoint - The endpoint of the resource.
+   * @param identifier - The identifier of the resource. If not provided, an empty string will be used.
+   * @returns A promise that resolves to the requested resource.
+   */
   protected async getResource<T>(endpoint: string, identifier?: string | number): Promise<T> {
     return (
       await this.api.get<T>(`${endpoint}/${identifier || identifier === 0 ? identifier : ""}`)
     ).data;
   }
 
+  /**
+   * Retrieves a resource by its URL.
+   *
+   * @template T - The type of the resource to be returned.
+   * @param url - The URL of the resource.
+   * @param baseURL - The base URL to use. Defaults to BASE_URL.REST.
+   * @returns A promise that resolves to the requested resource.
+   */
   protected async getResourceByURL<T>(url: string, baseURL = BASE_URL.REST): Promise<T> {
     const ENDPOINT = url.split("v2")[1] as string;
     return (await this.api.get<T>(ENDPOINT, { baseURL })).data;
   }
 
+  /**
+   * Retrieves a list of resources from the PokéAPI with pagination support.
+   *
+   * @param endpoint - The endpoint of the resource.
+   * @param offset - The offset for pagination. Defaults to 0.
+   * @param limit - The limit for pagination. Defaults to 20.
+   * @returns A promise that resolves to a list of named API resources.
+   */
   protected async getListResource(
     endpoint: Endpoint,
     offset = 0,