chore: add thorough JSDoc comments to most classes

packages/guilded.js/lib/managers/global/CacheableStructManager.ts

@@ -1,7 +1,14 @@
 import { Collection } from "@discordjs/collection";
 import type { Client } from "../../structures/Client";
+import { GlobalManager } from "./GlobalManager";
 
-export class CacheableStructManager<K, V> {
+/**
+ * This represents any manager that can cache structures locally. 
+ * The cache is a KV store with K usually being a string and V being an object.
+ * @template K Type of the key of the cache
+ * @template V Type of the value of the cache
+ * @extends GlobalManager
+ */
+export class CacheableStructManager<K, V> extends GlobalManager {
     cache = new Collection<K, V>();
-    constructor(public readonly client: Client) {}
 }

packages/guilded.js/lib/managers/global/CalendarManager.ts

@@ -3,6 +3,9 @@ import type { RESTGetCalendarEventsBody, RESTPatchCalendarEventBody, RESTPostCal
 import { CacheableStructManager } from "./CacheableStructManager";
 import { CalendarEvent, CalendarEventRsvp } from "../../structures/CalendarEvent";
 
+/**
+ * The manager is used to interact with calendars on a server.
+ */
 export class GlobalCalendarManager extends CacheableStructManager<number, CalendarEvent> {
     get shouldCacheCalendar() {
         return this.client.options?.cache?.cacheCalendars !== false;
@@ -12,14 +15,25 @@ export class GlobalCalendarManager extends CacheableStructManager<number, Calend
         return this.client.options?.cache?.cacheCalendarsRsvps !== false;
     }
 
-    /** Create a calendar event. */
+    /**
+     * Creates a calendar event.
+     * @param channelId The ID of the channel in which to create the event.
+     * @param options The options for the event.
+     * @returns A promise that resolves with the created calendar event.
+     */
     create(channelId: string, options: RESTPostCalendarEventBody): Promise<CalendarEvent> {
         return this.client.rest.router.createCalendarEvent(channelId, options).then((data) => {
             return new CalendarEvent(this.client, data.calendarEvent);
         });
     }
 
-    /** Get a single calendar event. */
+    /**
+     * Fetches a single calendar event.
+     * @param channelId The ID of the channel in which to fetch the event.
+     * @param calendarEventId The ID of the event to fetch.
+     * @param force Whether or not to force a fetch instead of using a cached version.
+     * @returns A promise that resolves with the fetched calendar event.
+     */
     fetch(channelId: string, calendarEventId: number, force?: boolean): Promise<CalendarEvent> {
         if (!force) {
             const existingCalendar = this.client.calendars.cache.get(calendarEventId);
@@ -32,7 +46,12 @@ export class GlobalCalendarManager extends CacheableStructManager<number, Calend
         });
     }
 
-    /** Get multiple calendar events. */
+    /**
+     * Fetches multiple calendar events.
+     * @param channelId The ID of the channel in which to fetch the events.
+     * @param options The options for the fetch.
+     * @returns A promise that resolves with a collection of the fetched calendar events.
+     */
     fetchMany(channelId: string, options: RESTGetCalendarEventsBody): Promise<Collection<number, CalendarEvent>> {
         return this.client.rest.router.getCalendarEvents(channelId, options).then((data) => {
             const calendarEvents = new Collection<number, CalendarEvent>();
@@ -45,7 +64,13 @@ export class GlobalCalendarManager extends CacheableStructManager<number, Calend
         });
     }
 
-    /** Update a calendar event. */
+    /**
+     * Updates a calendar event.
+     * @param channelId The ID of the channel in which the event exists.
+     * @param calendarEventId The ID of the event to update.
+     * @param options The options for the update.
+     * @returns A promise that resolves with the updated calendar event.
+     */
     update(channelId: string, calendarEventId: number, options: RESTPatchCalendarEventBody): Promise<CalendarEvent> {
         return this.client.rest.router.updateCalendarEvent(channelId, calendarEventId, options).then((data) => {
             const existingCalendar = this.cache.get(calendarEventId);
@@ -57,15 +82,27 @@ export class GlobalCalendarManager extends CacheableStructManager<number, Calend
         });
     }
 
-    /** Delete a calendar event. */
+    /**
+     * Delete a calendar event.
+     * @param channelId - The ID of the channel where the calendar event is located.
+     * @param calendarEventId - The ID of the calendar event to delete.
+     * @returns A Promise that resolves with the deleted calendar event or `undefined` if the event was not cached.
+     */
     delete(channelId: string, calendarEventId: number): Promise<CalendarEvent | void> {
         return this.client.rest.router.deleteCalendarEvent(channelId, calendarEventId).then((data) => {
             const cachedCalendar = this.cache.get(calendarEventId);
             return cachedCalendar ?? void 0;
         });
     }
 
-    /** Get a single rsvp from a caldenar event */
+    /**
+     * Get a single RSVP from a calendar event.
+     * @param channelId - The ID of the channel where the calendar event is located.
+     * @param calendarEventId - The ID of the calendar event to get the RSVP from.
+     * @param userId - The ID of the user who made the RSVP.
+     * @param force - Whether to force a request to the API instead of returning the cached RSVP.
+     * @returns A Promise that resolves with the requested RSVP.
+     */
     fetchRsvp(channelId: string, calendarEventId: number, userId: string, force?: boolean): Promise<CalendarEventRsvp> {
         if (!force) {
             const existingRsvp = this.client.calendars.cache.get(calendarEventId)?.rsvps?.get(userId);
@@ -78,7 +115,12 @@ export class GlobalCalendarManager extends CacheableStructManager<number, Calend
         });
     }
 
-    /** Fetch rsvps for a calendar event */
+    /**
+     * Fetch RSVPs for a calendar event.
+     * @param channelId - The ID of the channel where the calendar event is located.
+     * @param calendarEventId - The ID of the calendar event to fetch RSVPs for.
+     * @returns A Promise that resolves with a collection of RSVPs.
+     */
     fetchManyRsvps(channelId: string, calendarEventId: number): Promise<Collection<string, CalendarEventRsvp>> {
         return this.client.rest.router.getCalendarEventRsvps(channelId, calendarEventId).then((data) => {
             const rsvpEvents = new Collection<string, CalendarEventRsvp>();
@@ -93,7 +135,14 @@ export class GlobalCalendarManager extends CacheableStructManager<number, Calend
         });
     }
 
-    /** Create or update an rsvp for a calendar event */
+    /**
+     * Creates or updates an RSVP for a calendar event.
+     * @param channelId The ID of the channel.
+     * @param calendarEventId The ID of the calendar event.
+     * @param userId The ID of the user.
+     * @param options The options for updating the RSVP.
+     * @returns A promise that resolves with the updated or created RSVP.
+     */
     updateRsvp(channelId: string, calendarEventId: number, userId: string, options: RESTPatchCalendarEventRsvpBody): Promise<CalendarEventRsvp> {
         return this.client.rest.router.updateCalendarEventRvsp(channelId, calendarEventId, userId, options).then((data) => {
             const existingRsvp = this.cache.get(calendarEventId)?.rsvps?.get(userId);
@@ -105,7 +154,13 @@ export class GlobalCalendarManager extends CacheableStructManager<number, Calend
         });
     }
 
-    /** Delete an rsvp for a calendar event */
+    /**
+     * Deletes an RSVP for a calendar event.
+     * @param channelId The ID of the channel.
+     * @param calendarEventId The ID of the calendar event.
+     * @param userId The ID of the user.
+     * @returns A promise that resolves with the deleted RSVP or void if it was not cached.
+     */
     deleteRsvp(channelId: string, calendarEventId: number, userId: string): Promise<CalendarEventRsvp | void> {
         return this.client.rest.router.deleteCalendarEventRvsp(channelId, calendarEventId, userId).then((data) => {
             if (this.shouldCacheCalendar && this.shouldCacheCalendarRsvps) {

packages/guilded.js/lib/managers/global/ChannelManager.ts

@@ -3,18 +3,37 @@ import { Channel, DocChannel, ForumChannel, ListChannel } from "../../structures
 import { CacheableStructManager } from "./CacheableStructManager";
 import type { ChannelType as APIChannelType } from "@guildedjs/guilded-api-typings";
 
+/**
+ * Manages channels on the global scope. This can hold channels of any type, with all of them extending Channel.
+ * You will likely need to cast the returned values from cache or fetches
+ * @extends CacheableStructManager
+ */
 export class GlobalChannelManager extends CacheableStructManager<string, Channel> {
+
+	/** Determine whether a channel should be cached or not */
 	get shouldCacheChannel() {
 		return this.client.options?.cache?.cacheChannels !== false;
 	}
 
+	/**
+	 * Create a new channel
+	 * @param options Channel creation options
+	 * @returns Promise that resolves with the newly created channel
+	 */
 	create(options: RESTPostChannelsBody): Promise<Channel> {
 		return this.client.rest.router.createChannel(options).then((data) => {
 			const newChannel = new (transformTypeToChannel(data.channel.type))(this.client, data.channel);
 			return newChannel;
 		});
 	}
 
+	/**
+	 * Fetch a channel by ID
+	 * Notice: if you're using TypeScript, you will need to upcast to your desired channel type.
+	 * @param channelId ID of the channel to fetch
+	 * @param force Whether to force a fetch from the API
+	 * @returns Promise that resolves with the fetched channel
+	 */
 	fetch(channelId: string, force?: boolean): Promise<Channel> {
 		if (!force) {
 			const existingChannel = this.client.channels.cache.get(channelId);
@@ -27,6 +46,12 @@ export class GlobalChannelManager extends CacheableStructManager<string, Channel
 		});
 	}
 
+	/**
+	 * Update a channel by ID
+	 * @param channelId ID of the channel to update
+	 * @param options Channel update options
+	 * @returns Promise that resolves with the updated channel
+	 */
 	update(channelId: string, options: RESTPatchChannelBody): Promise<Channel> {
 		return this.client.rest.router.updateChannel(channelId, options).then((data) => {
 			const existingChannel = this.cache.get(channelId);
@@ -38,6 +63,11 @@ export class GlobalChannelManager extends CacheableStructManager<string, Channel
 		});
 	}
 
+	/**
+	 * Delete a channel by ID
+	 * @param channelId ID of the channel to delete
+	 * @returns Promise that resolves with the deleted channel, or void if not cached.
+	 */
 	delete(channelId: string): Promise<Channel | void> {
 		return this.client.rest.router.deleteChannel(channelId).then((data) => {
 			const cachedChannel = this.cache.get(channelId);
@@ -46,8 +76,14 @@ export class GlobalChannelManager extends CacheableStructManager<string, Channel
 	}
 }
 
+/**
+ * Transforms the string APIChannelType to its corresponding channel class
+ * @param str String representing the channel type
+ * @returns Channel class for the given channel type
+ */
 export const transformTypeToChannel = (str: APIChannelType) => typeToChannel[str as "forums" | "docs" | "list"] ?? Channel;
 
+/** Mapping between the string APIChannelType and the corresponding channel class */
 export const typeToChannel = {
 	forums: ForumChannel,
 	docs: DocChannel,

packages/guilded.js/lib/managers/global/DocManager.ts

@@ -1,28 +1,57 @@
 import type { DocPayload, RESTPostDocsBody, RESTPutDocBody } from "@guildedjs/guilded-api-typings";
 import { GlobalManager } from "./GlobalManager";
 
+/**
+ * A manager class for Docs
+ */
 export class GlobalDocManager extends GlobalManager {
-    /** Create a doc. */
+
+    /**
+     * Create a new Doc.
+     * @param channelId - The ID of the channel where the Doc should be created.
+     * @param options - The options for the Doc to be created.
+     * @returns A Promise that resolves with the Doc payload of the newly created Doc.
+     */
     create(channelId: string, options: RESTPostDocsBody): Promise<DocPayload> {
         return this.client.rest.router.createDoc(channelId, options).then((data) => data.doc);
     }
 
-    /** Get the docs from a channel. */
+    /**
+     * Fetches multiple Docs from a channel.
+     * @param channelId - The ID of the channel where the Docs are located.
+     * @returns A Promise that resolves with an array of Doc payloads.
+     */
     fetchMany(channelId: string): Promise<DocPayload[]> {
         return this.client.rest.router.getDocs(channelId).then((data) => data.docs);
     }
 
-    /** Get a doc from a channel. */
+    /**
+     * Fetch a Doc from a channel.
+     * @param channelId - The ID of the channel where the Doc is located.
+     * @param docId - The ID of the Doc to fetch.
+     * @returns A Promise that resolves with the Doc payload of the fetched Doc.
+     */
     fetch(channelId: string, docId: number): Promise<DocPayload> {
         return this.client.rest.router.getDoc(channelId, docId).then((data) => data.doc);
     }
 
-    /** Update a doc */
+    /**
+     * Update a Doc.
+     * @param channelId - The ID of the channel where the Doc is located.
+     * @param docId - The ID of the Doc to update.
+     * @param options - The options for the Doc update.
+     * @returns A Promise that resolves with the Doc payload of the updated Doc.
+     */
     update(channelId: string, docId: number, options: RESTPutDocBody): Promise<DocPayload> {
         return this.client.rest.router.updateDoc(channelId, docId, options).then((data) => data.doc);
     }
 
-    /** Delete a doc from a channel. */
+    /**
+     * Delete a Doc from a channel.
+     * @param channelId - The ID of the channel where the Doc is located.
+     * @param docId - The ID of the Doc to delete.
+     * @returns A Promise that resolves with void when the Doc is successfully deleted.
+     */
     delete(channelId: string, docId: number): Promise<void> {
         return this.client.rest.router.deleteDoc(channelId, docId).then(() => void 0);
     }