Added missing (and improved existing) function documentation, Improved error message clarity

src/structs/Api.ts

@@ -16,7 +16,7 @@ import {
 } from "../typings";
 
 /**
- * Top.gg API Client for Posting stats or Fetching data
+ * Top.gg API Client for posting stats or fetching data
  *
  * @example
  * ```js
@@ -86,7 +86,7 @@ export class Api extends EventEmitter {
   }
 
   /**
-   * Post bot stats to Top.gg
+   * Posts bot stats to Top.gg
    *
    * @example
    * ```js
@@ -96,11 +96,12 @@ export class Api extends EventEmitter {
    * });
    * ```
    *
-   * @param {object} stats Stats object
-   * @param {number} stats.serverCount Server count
-   * @param {number} [stats.shardCount] Shard count
+   * @param {BotStats} stats Stats object
+   * @param {number} [stats.serverCount] The amount of servers the bot is in
+   * @param {number} [stats.shards] The amount of servers the bot is in per shard.
+   * @param {number} [stats.shardCount] The amount of shards a bot has
    * @param {number} [stats.shardId] Posting shard (useful for process sharding)
-   * @returns {BotStats} Passed object
+   * @returns {Promise<BotStats>} Passed object
    */
   public async postStats(stats: BotStats): Promise<BotStats> {
     if (!stats?.serverCount) throw new Error("Missing Server Count");
@@ -131,10 +132,10 @@ export class Api extends EventEmitter {
    * ```
    *
    * @param {Snowflake} id Bot ID
-   * @returns {BotStats} Stats of bot requested
+   * @returns {Promise<BotStats>} Stats of bot requested
    */
   public async getStats(id: Snowflake): Promise<BotStats> {
-    if (!id) throw new Error("ID missing");
+    if (!id) throw new Error("Missing parameter bot ID");
     const result = await this._request("GET", `/bots/${id}/stats`);
     return {
       serverCount: result.server_count,
@@ -152,15 +153,15 @@ export class Api extends EventEmitter {
    * ```
    *
    * @param {Snowflake} id Bot ID
-   * @returns {BotInfo} Info for bot
+   * @returns {Promise<BotInfo>} Info for bot
    */
   public async getBot(id: Snowflake): Promise<BotInfo> {
-    if (!id) throw new Error("ID Missing");
+    if (!id) throw new Error("Missing parameter bot ID");
     return this._request("GET", `/bots/${id}`);
   }
 
   /**
-   * Get user info
+   * Retrieves information about a particular user by their top.gg user ID.
    *
    * @example
    * ```js
@@ -170,15 +171,15 @@ export class Api extends EventEmitter {
    * ```
    *
    * @param {Snowflake} id User ID
-   * @returns {UserInfo} Info for user
+   * @returns {Promise<UserInfo>} Info for user
    */
   public async getUser(id: Snowflake): Promise<UserInfo> {
-    if (!id) throw new Error("ID Missing");
+    if (!id) throw new Error("Missing parameter user ID");
     return this._request("GET", `/users/${id}`);
   }
 
   /**
-   * Get a list of bots
+   * Gets a list of bots that match a specific query.
    *
    * @example
    * ```js
@@ -197,9 +198,9 @@ export class Api extends EventEmitter {
    *       username: 'Shiro',
    *       discriminator: '8764',
    *       lib: 'discord.js',
-   *       ...rest of bot object
+   *       // ...rest of bot object
    *     }
-   *     ...other shiro knockoffs B)
+   *     // ...other shiro knockoffs B)
    *   ],
    *   limit: 10,
    *   offset: 0,
@@ -221,14 +222,14 @@ export class Api extends EventEmitter {
    *       id: '493716749342998541',
    *       username: 'Mimu'
    *     },
-   *     ...
+   *     // ...
    *   ],
-   *   ...
+   *   // ...
    * }
    * ```
    *
    * @param {BotsQuery} query Bot Query
-   * @returns {BotsResponse} Return response
+   * @returns {Promise<BotsResponse>} Return response
    */
   public async getBots(query?: BotsQuery): Promise<BotsResponse> {
     if (query) {
@@ -243,7 +244,11 @@ export class Api extends EventEmitter {
   }
 
   /**
-   * Get users who've voted
+   * Gets the last 1000 voters for your bot
+   * 
+   * If your bot receives more than 1000 votes monthly you cannot use this endpoints and must use webhooks and implement your own caching instead.
+   * 
+   * This endpoint only returns unique votes, it does not include double votes (weekend votes).
    *
    * @example
    * ```js
@@ -260,19 +265,19 @@ export class Api extends EventEmitter {
    *     id: '395526710101278721',
    *     avatar: '3d1477390b8d7c3cec717ac5c778f5f4'
    *   }
-   *   ...more
+   *   // ...more
    * ]
    * ```
    *
-   * @returns {ShortUser[]} Array of users who've voted
+   * @returns {Promise<ShortUser[]>} Array of users who've voted
    */
   public async getVotes(): Promise<ShortUser[]> {
-    if (!this.options.token) throw new Error("Missing token");
+    if (!this.options.token) throw new Error("You must provide a token to the Top.gg API instance for this");
     return this._request("GET", "/bots/votes");
   }
 
   /**
-   * Get whether or not a user has voted in the last 12 hours
+   * Checking whether or not a user has voted for your bot in the last 12 hours. Safe to use even if you have over 1k monthly votes.
    *
    * @example
    * ```js
@@ -281,10 +286,10 @@ export class Api extends EventEmitter {
    * ```
    *
    * @param {Snowflake} id User ID
-   * @returns {boolean} Whether the user has voted in the last 12 hours
+   * @returns {Promise<boolean>} Whether the user has voted in the last 12 hours
    */
   public async hasVoted(id: Snowflake): Promise<boolean> {
-    if (!id) throw new Error("Missing ID");
+    if (!id) throw new Error("Missing parameter user ID");
     return this._request("GET", "/bots/check", { userId: id }).then(
       (x) => !!x.voted
     );
@@ -299,9 +304,9 @@ export class Api extends EventEmitter {
    * // => true/false
    * ```
    *
-   * @returns {boolean} Whether the multiplier is active
+   * @returns {Promise<boolean>} Whether the multiplier is active
    */
   public async isWeekend(): Promise<boolean> {
     return this._request("GET", "/weekend").then((x) => x.is_weekend);
   }
-}
+}

src/structs/Webhook.ts

@@ -43,7 +43,9 @@ export class Webhook {
   /**
    * Create a new webhook client instance
    *
-   * @param authorization Webhook authorization to verify requests
+   * @param {string} authorization Webhook authorization to verify requests
+   * @param {WebhookOptions} options The webhook options
+   * @param {((error: Error) => void) | Promise<void>} [options.error] Handles an error created by the function passed to Webhook.listener()
    */
   constructor(private authorization?: string, options: WebhookOptions = {}) {
     this.options = {
@@ -166,4 +168,4 @@ export class Webhook {
       next();
     };
   }
-}
+}

src/utils/ApiError.ts

@@ -5,10 +5,21 @@ const tips = {
   403: "You don't have access to this endpoint",
 };
 
-/** API Error */
+/**
+ * Represents a Top.gg API error
+ * @extends Error
+ */
 export default class TopGGAPIError extends Error {
   /** Possible response from Request */
   public response?: Dispatcher.ResponseData;
+
+  /**
+   * Creates a Top.gg API error instance
+   * 
+   * @param {number} code The error code
+   * @param {string} text The error text
+   * @param {Dispatcher.ResponseData} response 
+   */
   constructor(code: number, text: string, response: Dispatcher.ResponseData) {
     if (code in tips) {
       super(`${code} ${text} (${tips[code as keyof typeof tips]})`);
@@ -17,4 +28,4 @@ export default class TopGGAPIError extends Error {
     }
     this.response = response;
   }
-}
+}