Merge pull request #26 from m1-dev/master

Add JSDoc

packages/commandkit/src/CommandKit.ts

@@ -6,6 +6,11 @@ import colors from './utils/colors';
 export class CommandKit {
     #data: CommandKitData;
 
+    /**
+     * Create a new handler with CommandKit.
+     * @param options - Options to use (client, commandsPath, eventsPath, etc.)
+     * @see {@link https://commandkit.js.org/docs/commandkit-setup}
+     */
     constructor(options: CommandKitOptions) {
         if (!options.client) {
             throw new Error(colors.red('"client" is required when instantiating CommandKit.'));
@@ -22,6 +27,9 @@ export class CommandKit {
         this.#init();
     }
 
+    /**
+     * (Private) Initialize CommandKit.
+     */
     async #init() {
         // <!-- Setup event handler -->
         if (this.#data.eventsPath) {

packages/commandkit/src/handlers/command-handler/CommandHandler.ts

@@ -12,6 +12,9 @@ import rdfc from 'rfdc';
 
 const clone = rdfc();
 
+/**
+ * A handler for client application commands.
+ */
 export class CommandHandler {
     #data: CommandHandlerData;
 

packages/commandkit/src/handlers/command-handler/functions/loadCommandsWithRest.ts

@@ -3,13 +3,38 @@ import type { CommandFileObject, ReloadOptions } from '../../../typings';
 
 import colors from '../../../utils/colors';
 
-export default async function loadCommandsWithRest(props: {
+type LoadCommandsWithRestProps = {
+    /**
+     * The main client.
+     */
     client: Client;
+
+    /**
+     * An array of command objects.
+     */
     commands: CommandFileObject[];
+
+    /**
+     * An array of developer guild IDs.
+     */
     devGuildIds: string[];
+
+    /**
+     * A boolean indicating whether these commands are reloading.
+     */
     reloading?: boolean;
+
+    /**
+     * A type for reloading the commands (if this is reloading).
+     */
     type?: ReloadOptions;
-}) {
+};
+
+/**
+ * Use REST to load commands.
+ * @param props - Options for loading commands.
+ */
+export default async function loadCommandsWithRest(props: LoadCommandsWithRestProps) {
     if (props.reloading) {
         if (props.client.isReady()) {
             await handleLoading(
@@ -29,6 +54,14 @@ export default async function loadCommandsWithRest(props: {
     }
 }
 
+/**
+ * Handles loading commands.
+ * @param client - The discord.js client instance.
+ * @param commands - An array of command file objects.
+ * @param devGuildIds - An array of developer guild IDs.
+ * @param reloading - A boolean indicating whether this is reloading.
+ * @param type - A type for reloading the commands (if this is reloading).
+ */
 async function handleLoading(
     client: Client<true>,
     commands: CommandFileObject[],
@@ -50,6 +83,12 @@ async function handleLoading(
     }
 }
 
+/**
+ * Load commands globally.
+ * @param client - The discord.js client instance.
+ * @param commands - An array of command file objects.
+ * @param reloading - A boolean indicating whether the commands are reloading.
+ */
 async function loadGlobalCommands(
     client: Client<true>,
     commands: CommandFileObject[],
@@ -77,6 +116,13 @@ async function loadGlobalCommands(
     );
 }
 
+/**
+ * Load commands for dev guilds.
+ * @param client - The discord.js client instance.
+ * @param commands - An array of command file objects.
+ * @param guildIds - An array of developer guild IDs.
+ * @param reloading - A boolean indicating whether the commands are reloading.
+ */
 async function loadDevCommands(
     client: Client<true>,
     commands: CommandFileObject[],

packages/commandkit/src/handlers/command-handler/functions/registerCommands.ts

@@ -11,13 +11,19 @@ import areSlashCommandsDifferent from '../utils/areSlashCommandsDifferent';
 
 import colors from '../../../utils/colors';
 
-export default async function registerCommands(props: {
+type RegisterCommandProps = {
     client: Client;
     commands: CommandFileObject[];
     devGuildIds: string[];
     reloading?: boolean;
     type?: ReloadOptions;
-}) {
+};
+
+/**
+ * Register client commands to Discord.
+ * @param props
+ */
+export default async function registerCommands(props: RegisterCommandProps) {
     if (props.reloading) {
         if (props.client.isReady()) {
             await handleRegistration(props.client, props.commands, props.devGuildIds, props.type);

packages/commandkit/src/handlers/command-handler/typings.ts

@@ -3,28 +3,98 @@ import { CommandKit } from '../../CommandKit';
 import { CommandFileObject } from '../../typings';
 import { ValidationHandler } from '../validation-handler/ValidationHandler';
 
+/**
+ * Command handler options.
+ * Similar to CommandKit options in structure.
+ */
 export interface CommandHandlerOptions {
+    /**
+     * The client created by the user.
+     */
     client: Client;
+
+    /**
+     * Path to the user's commands.
+     */
     commandsPath: string;
+
+    /**
+     * An array of developer guild IDs.
+     */
     devGuildIds: string[];
+
+    /**
+     * An array of developer user IDs.
+     */
     devUserIds: string[];
+
+    /**
+     * An array of developer role IDs.
+     */
     devRoleIds: string[];
+
+    /**
+     * A validation handler instance to run validations before commands.
+     */
     validationHandler?: ValidationHandler;
+
+    /**
+     * A boolean indicating whether to skip CommandKit's built-in validations (permission checking, etc.)
+     */
     skipBuiltInValidations: boolean;
+
+    /**
+     * The CommandKit handler that instantiated this.
+     */
     commandkitInstance: CommandKit;
+
+    /**
+     * A boolean indicating whether to register all commands in bulk.
+     */
     bulkRegister: boolean;
 }
 
+/**
+ * Private command handler data.
+ */
 export interface CommandHandlerData extends CommandHandlerOptions {
+    /**
+     * An array of command file objects.
+     */
     commands: CommandFileObject[];
-    builtInValidations: Array<BuiltInValidation>;
+
+    /**
+     * An array of built-in validations.
+     */
+    builtInValidations: BuiltInValidation[];
+
+    /**
+     * A validation handler instance to run validations before commands.
+     */
     validationHandler?: ValidationHandler;
 }
 
+/**
+ * Parameters for CommandKit's built-in validations.
+ */
 export interface BuiltInValidationParams {
+    /**
+     * The target command to validate.
+     */
     targetCommand: CommandFileObject;
+
+    /**
+     * The interaction of the target command.
+     */
     interaction: ChatInputCommandInteraction | ContextMenuCommandInteraction;
+
+    /**
+     * The command handler's data.
+     */
     handlerData: CommandHandlerData;
 }
 
+/**
+ * A built in validation. Returns a boolean or void.
+ */
 export type BuiltInValidation = ({}: BuiltInValidationParams) => boolean | void;

packages/commandkit/src/handlers/command-handler/utils/areSlashCommandsDifferent.ts

@@ -1,3 +1,9 @@
+/**
+ * Test if two slash commands are different.
+ * @param appCommand - The application command.
+ * @param localCommand - The local command.
+ * @returns A boolean indicating whether these commands are different
+ */
 export default function areSlashCommandsDifferent(appCommand: any, localCommand: any) {
     if (!appCommand.options) appCommand.options = [];
     if (!localCommand.options) localCommand.options = [];

packages/commandkit/src/handlers/event-handler/EventHandler.ts

@@ -7,6 +7,9 @@ import rdfc from 'rfdc';
 
 const clone = rdfc();
 
+/**
+ * A handler for client events.
+ */
 export class EventHandler {
     #data: EventHandlerData;
 

packages/commandkit/src/handlers/event-handler/typings.ts

@@ -1,12 +1,18 @@
 import type { Client } from 'discord.js';
 import type { CommandKit } from '../../CommandKit';
 
+/**
+ * Event handler options.
+ */
 export interface EventHandlerOptions {
     client: Client;
     eventsPath: string;
     commandKitInstance: CommandKit;
 }
 
+/**
+ * Private event handler data.
+ */
 export interface EventHandlerData extends EventHandlerOptions {
     events: { name: string; functions: Function[] }[];
 }

packages/commandkit/src/handlers/validation-handler/ValidationHandler.ts

@@ -6,6 +6,9 @@ import rdfc from 'rfdc';
 
 const clone = rdfc();
 
+/**
+ * A handler for command validations.
+ */
 export class ValidationHandler {
     #data: ValidationHandlerData;
 

packages/commandkit/src/handlers/validation-handler/typings.ts

@@ -1,7 +1,13 @@
+/**
+ * Validation handler options (validationsPath).
+ */
 export interface ValidationHandlerOptions {
     validationsPath: string;
 }
 
+/**
+ * Private validation handler data.
+ */
 export interface ValidationHandlerData extends ValidationHandlerOptions {
     validations: Function[];
 }

packages/commandkit/src/index.ts

@@ -1,4 +1,4 @@
 export * from './CommandKit';
 export * from './components';
 export * from './utils/signal';
-export * from './types';
+export type * from './types';