From 95ba89e602c2bfcce921b2002a5f388971637b75 Mon Sep 17 00:00:00 2001 From: GRZANA <74425958+GRZ4NA@users.noreply.github.com> Date: Sat, 13 Nov 2021 15:40:39 +0100 Subject: [PATCH] more detailed jsdoc documentation (partial commands) --- src/commands/ChatCommand.ts | 56 +++++++++++++++------ src/commands/base/Command.ts | 12 +++++ src/commands/base/FunctionCommand.ts | 10 ++++ src/commands/base/GuildCommand.ts | 8 +++ src/commands/base/PermissionCommand.ts | 6 +++ src/commands/base/PermissionGuildCommand.ts | 9 ++++ src/commands/types/HelpMessage.ts | 2 +- src/commands/types/InitOptions.ts | 18 +++---- src/commands/types/commands.ts | 20 ++++++++ src/commands/types/permissions.ts | 4 +- 10 files changed, 119 insertions(+), 26 deletions(-) diff --git a/src/commands/ChatCommand.ts b/src/commands/ChatCommand.ts index 1c1cb40..b1d32fa 100644 --- a/src/commands/ChatCommand.ts +++ b/src/commands/ChatCommand.ts @@ -12,50 +12,71 @@ import { applicationState } from "../state.js"; import { InputManager } from "../structures/InputManager.js"; /** - * @class A representation of CHAT_INPUT command (also known as a slash command) + * A representation of CHAT_INPUT command (also known as a slash command) + * @class + * @extends {PermissionGuildCommand} */ export class ChatCommand extends PermissionGuildCommand { + /** + * Subcommands and groups of this command + * @type {Array} + * @private + * @readonly + */ private readonly _children: ChildCommandResolvable[] = []; /** * List of parameters that can passed to this command * @type {Array>} + * @public + * @readonly */ public readonly parameters: Parameter[]; /** * List of different names that can be used to invoke a command (when using prefix interactions) * @type {Array} + * @public + * @readonly */ public readonly aliases?: string[]; /** * Command description displayed in the help message or in slash commands menu (Default description: "No description") * @type {string} + * @public + * @readonly */ public readonly description: string; /** * Command usage displayed in the help message * @type {string} + * @public + * @readonly */ public readonly usage?: string; /** * Whether this command is visible in the help message (default: true) * @type {boolean} + * @public + * @readonly */ public readonly visible: boolean; /** * Whether this command should be registered as a slash command (default: true) * @type {boolean} + * @public + * @readonly */ public readonly slash: boolean; /** - * @constructor ChatCommand constructor - * @param manager - a manager that this command belongs to - * @param options - {@link ChatCommandInit} object containing all options needed to create a {@link ChatCommand} + * ChatCommand constructor + * @constructor + * @param {CommandManager} manager - a manager that this command belongs to + * @param {ChatCommandInit} options - {@link ChatCommandInit} object containing all options needed to create a {@link ChatCommand} */ constructor(manager: CommandManager, options: ChatCommandInit) { super(manager, "CHAT", { @@ -114,7 +135,10 @@ export class ChatCommand extends PermissionGuildCommand { /** * Invoke the command - * @param input - input data manager + * @param {InputManager} input - input data manager + * @returns {Promise} + * @public + * @async */ public async start(input: InputManager): Promise { if (!this.slash && input.interaction instanceof Interaction) { @@ -125,9 +149,10 @@ export class ChatCommand extends PermissionGuildCommand { /** * Attaches subcommand or subcommand group to this ChatCommand (this makes the base command usable only via prefix interactions) - * @param type - subcommand type - * @param options - initialization options - * @returns A computed subcommand object + * @param {T} type - subcommand type + * @param {ChildCommandInit} options - initialization options + * @returns {ChildCommands} A computed subcommand object + * @public */ public append(type: T, options: ChildCommandInit): ChildCommands { const command = @@ -149,9 +174,10 @@ export class ChatCommand extends PermissionGuildCommand { /** * - * @param options - parameter options - * @param interaction - Discord interaction - * @returns an {@link InputManager} containing all interaction-related data or *null* + * @param {Array} options - parameter options + * @param {Interaction | Message} interaction - Discord interaction + * @returns {InputManager} an {@link InputManager} containing all interaction-related data or *null* + * @public */ public fetchSubcommand(options: CommandInteractionOption[], interaction: Interaction | Message): InputManager | null { if (!this.hasSubCommands) return null; @@ -208,9 +234,9 @@ export class ChatCommand extends PermissionGuildCommand { /** * - * @param name - subcommand name - * @param group - name of the group (if any) - * @returns a {@link SubCommand} object or *null* + * @param {string} name - subcommand name + * @param {string} [group] - name of the group (if any) + * @returns {SubCommand} a {@link SubCommand} object or *null* */ public getSubcommand(name: string, group?: string): SubCommand | null { if (!this.hasSubCommands) return null; @@ -228,7 +254,7 @@ export class ChatCommand extends PermissionGuildCommand { /** * Converts {@link ChatCommand} instance to object that is recognized by the Discord API - * @returns Discord API object + * @returns {ChatCommandObject} Discord API object */ public toObject(): ChatCommandObject { const obj: ChatCommandObject = { diff --git a/src/commands/base/Command.ts b/src/commands/base/Command.ts index 03d0539..3279402 100644 --- a/src/commands/base/Command.ts +++ b/src/commands/base/Command.ts @@ -17,24 +17,32 @@ export class Command { /** * Manager in which this command is registered * @type {CommandManager} + * @public + * @readonly */ public readonly manager: CommandManager; /** * Command name * @type {string} + * @public + * @readonly */ public readonly name: string; /** * CommandBot's internal command type * @type {CommandType} + * @public + * @readonly */ public readonly type: CommandType; /** * Discord API default_permission * @type {boolean} + * @public + * @readonly */ public readonly default_permission: boolean; @@ -62,6 +70,7 @@ export class Command { /** * Converts a command instance to an {@link APICommandObject} * @returns {APICommandObject} An object that is accepted by the Discord API + * @public */ public toObject(): APICommandObject { return { @@ -74,6 +83,7 @@ export class Command { * Check base command type * @param {BaseCommandType} type - base command type * @returns {boolean} Whether this command can be used as the given type + * @public */ public isBaseCommandType(type: T): this is BaseCommands { switch (type) { @@ -113,6 +123,7 @@ export class Command { * Checks command type * @param {CommandType} type - command type * @returns {boolean} Whether this command can be used as the given type + * @public */ public isCommandType(type: T): this is Commands { switch (type) { @@ -139,6 +150,7 @@ export class Command { * Check child command type * @param {ChildCommandType} type - child command type * @returns {boolean} Whether this command can be used as a child command of the given type + * @public */ public isChildCommandType(type: T): this is ChildCommands { switch (type) { diff --git a/src/commands/base/FunctionCommand.ts b/src/commands/base/FunctionCommand.ts index f1877e2..e05f486 100644 --- a/src/commands/base/FunctionCommand.ts +++ b/src/commands/base/FunctionCommand.ts @@ -9,16 +9,21 @@ import { InputManager } from "../../structures/InputManager.js"; /** * Function (executable) command * @class + * @extends {Command} */ export class FunctionCommand extends Command { /** * Command function (called on command execution) * @type {CommandFunction} + * @private + * @readonly */ private readonly _function: CommandFunction; /** * Whether a SUCCESS message should be sent after executing the command function (when there is no other reply) * @type {boolean} + * @public + * @readonly */ public readonly announceSuccess: boolean; @@ -48,6 +53,8 @@ export class FunctionCommand extends Command { * Invoke the command * @param {InputManager} input - input data manager * @returns {Promise} A *Promise* that resolves after the function command is completed + * @public + * @async */ public async start(input: InputManager): Promise { if (input.interaction instanceof Interaction && !input.interaction.isCommand() && !input.interaction.isContextMenu()) throw new TypeError(`Interaction not recognized`); @@ -59,6 +66,9 @@ export class FunctionCommand extends Command { * Reply handler * @param {Message | Interaction} interaction - Discord interaction object * @param {void | string | MessageEmbed | ReplyMessageOptions} result - result of command function execution + * @return {Promise} + * @private + * @async */ private async handleReply(interaction: Message | Interaction, result: void | string | MessageEmbed | ReplyMessageOptions) { if (interaction instanceof Interaction && !interaction.isCommand() && !interaction.isContextMenu()) throw new TypeError(`Interaction not recognized`); diff --git a/src/commands/base/GuildCommand.ts b/src/commands/base/GuildCommand.ts index 5a2e809..b554460 100644 --- a/src/commands/base/GuildCommand.ts +++ b/src/commands/base/GuildCommand.ts @@ -7,17 +7,22 @@ import { InputManager } from "../../structures/InputManager.js"; /** * Guild-scoped executable command * @class + * @extends {FunctionCommand} */ export class GuildCommand extends FunctionCommand { /** * List of Discord guild (server) IDs in which this command can be used * @type {Array} + * @public + * @readonly */ public readonly guilds?: string[]; /** * If set to *false*, all interactions that get invoked from private/direct conversations (outside a guild) will result a PermissionError * @type {boolean} + * @public + * @readonly */ public readonly dm: boolean; @@ -43,6 +48,9 @@ export class GuildCommand extends FunctionCommand { /** * Invoke the command * @param {InputManager} input - input data + * @returns {Promise} + * @public + * @async */ public async start(input: InputManager): Promise { if (!input.interaction.guild && !this.dm) throw new Error(`Command "${this.name}" is only available inside a guild.`); diff --git a/src/commands/base/PermissionCommand.ts b/src/commands/base/PermissionCommand.ts index 2ca5571..e332d5e 100644 --- a/src/commands/base/PermissionCommand.ts +++ b/src/commands/base/PermissionCommand.ts @@ -9,11 +9,14 @@ import { InputManager } from "../../structures/InputManager.js"; /** * Executable command with attached permission system * @class + * @extends {FunctionCommand} */ export class PermissionCommand extends FunctionCommand { /** * Object containing check functions and permission bitfields * @type {CommandPermissions} + * @public + * @readonly */ public readonly permissions: CommandPermissions; @@ -38,6 +41,9 @@ export class PermissionCommand extends FunctionCommand { /** * Invoke the command * @param {InputManager} input - input data + * @returns {Promise} + * @public + * @async */ public async start(input: InputManager): Promise { if (this.permissions.check(input.interaction)) { diff --git a/src/commands/base/PermissionGuildCommand.ts b/src/commands/base/PermissionGuildCommand.ts index 14c1cdf..da40e0f 100644 --- a/src/commands/base/PermissionGuildCommand.ts +++ b/src/commands/base/PermissionGuildCommand.ts @@ -8,17 +8,23 @@ import { InputManager } from "../../structures/InputManager.js"; /** * Guild-scoped executable command with permissions attached * @class + * @extends {PermissionCommand} + * @implements {GuildCommand} */ export class PermissionGuildCommand extends PermissionCommand implements GuildCommand { /** * List of Discord guild (server) IDs in which this command can be used * @type {Array} + * @public + * @readonly */ public readonly guilds?: string[]; /** * If set to *false*, all interactions that get invoked from private/direct conversations (outside a guild) will result a PermissionError * @type {boolean} + * @public + * @readonly */ public readonly dm: boolean; @@ -45,6 +51,9 @@ export class PermissionGuildCommand extends PermissionCommand implements GuildCo /** * Invoke the command * @param {InputManager} input - input data + * @returns {Promise} + * @public + * @async */ public async start(input: InputManager): Promise { if (!input.interaction.guild && !this.dm) throw new Error(`Command "${this.name}" is only available inside a guild.`); diff --git a/src/commands/types/HelpMessage.ts b/src/commands/types/HelpMessage.ts index 4c74c55..5ed30c3 100644 --- a/src/commands/types/HelpMessage.ts +++ b/src/commands/types/HelpMessage.ts @@ -1,8 +1,8 @@ import { ColorResolvable } from "discord.js"; /** - * @interface * All properties used to customize the appearance of a help message + * @interface */ export interface HelpMessageParams { /** diff --git a/src/commands/types/InitOptions.ts b/src/commands/types/InitOptions.ts index 263543a..a544972 100644 --- a/src/commands/types/InitOptions.ts +++ b/src/commands/types/InitOptions.ts @@ -3,8 +3,8 @@ import { CommandPermissionsInit } from "./permissions.js"; import { CommandFunction, ContextType } from "./commands.js"; /** - * @interface * Initialization options of core {@link Command} object + * @interface */ export interface APICommandInit { /** @@ -20,8 +20,8 @@ export interface APICommandInit { } /** - * @interface * Initialization options of base executable command + * @interface * @extends {APICommandInit} */ export interface FunctionCommandInit extends APICommandInit { @@ -38,8 +38,8 @@ export interface FunctionCommandInit extends APICommandInit { } /** - * @interface * Initialization options of base guild-scoped command + * @interface * @extends {FunctionCommandInit} */ export interface GuildCommandInit extends FunctionCommandInit { @@ -56,8 +56,8 @@ export interface GuildCommandInit extends FunctionCommandInit { } /** - * @interface * Initialization options of base command with attached permissions + * @interface * @extends {FunctionCommandInit} */ export interface PermissionCommandInit extends FunctionCommandInit { @@ -69,8 +69,8 @@ export interface PermissionCommandInit extends FunctionCommandInit { } /** - * @interface * Initialization options of base guild-scoped command with attached permisisions + * @interface * @extends {PermissionCommandInit} */ export interface PermissionGuildCommandInit extends PermissionCommandInit { @@ -87,8 +87,8 @@ export interface PermissionGuildCommandInit extends PermissionCommandInit { } /** - * @interface * Intialization options of chat command + * @interface * @extends {PermissionGuildCommandInit} */ export interface ChatCommandInit extends PermissionGuildCommandInit { @@ -125,8 +125,8 @@ export interface ChatCommandInit extends PermissionGuildCommandInit { } /** - * @interface * Initialization options of context menu interactions + * @interface * @extends {PermissionGuildCommandInit} */ export interface ContextMenuCommandInit extends PermissionGuildCommandInit { @@ -138,8 +138,8 @@ export interface ContextMenuCommandInit extends PermissionGuildCommandInit { } /** - * @interface * Subcommand initialization options + * @interface * @extends {PermissionCommandInit} */ export interface SubCommandInit extends PermissionCommandInit { @@ -161,8 +161,8 @@ export interface SubCommandInit extends PermissionCommandInit { } /** - * @interface * Intialization options of subcommand group + * @interface * @extends {APICommandInit} */ export interface SubCommandGroupInit extends APICommandInit { diff --git a/src/commands/types/commands.ts b/src/commands/types/commands.ts index b197967..35d559d 100644 --- a/src/commands/types/commands.ts +++ b/src/commands/types/commands.ts @@ -23,21 +23,25 @@ import { InputManager } from "../../structures/InputManager.js"; /** * Types of command bases + * @type */ export type BaseCommandType = "BASE" | "FUNCTION" | "GUILD" | "PERMISSION" | "PERMISSIONGUILD"; /** * Command types + * @type */ export type CommandType = "CHAT" | "CONTEXT"; /** * Child command types + * @type */ export type ChildCommandType = "COMMAND" | "GROUP"; /** * Base command type selector + * @type */ export type BaseCommands = T extends "BASE" ? Command @@ -53,16 +57,19 @@ export type BaseCommands = T extends "BASE" /** * Command type selector + * @type */ export type Commands = T extends "CHAT" ? ChatCommand : T extends "CONTEXT" ? ContextMenuCommand : never; /** * Child command type selector + * @type */ export type ChildCommands = T extends "COMMAND" ? SubCommand : T extends "GROUP" ? SubCommandGroup : never; /** * Base command initializer selector + * @type */ export type BaseCommandInit = T extends "BASE" ? APICommandInit @@ -78,46 +85,59 @@ export type BaseCommandInit = T extends "BASE" /** * Command initializer selector + * @type */ export type CommandInit = T extends "CHAT" ? ChatCommandInit : T extends "CONTEXT" ? ContextMenuCommandInit : never; /** * Child command initializer selector + * @type */ export type ChildCommandInit = T extends "COMMAND" ? SubCommandInit : T extends "GROUP" ? SubCommandGroupInit : never; /** * Base command resolvables + * @type */ export type BaseCommandResolvable = Command | FunctionCommand | GuildCommand | PermissionCommand | PermissionGuildCommand; /** * Command resolvables + * @type */ export type CommandResolvable = ChatCommand | ContextMenuCommand; /** * Child command resolvables + * @type */ export type ChildCommandResolvable = SubCommandGroup | SubCommand; /** * Context menu command types + * @type */ export type ContextType = "USER" | "MESSAGE"; /** * All types that can be returned from a command function + * @type */ export type CommandFunctionReturnTypes = void | string | MessageEmbed | ReplyMessageOptions | Promise; /** * Command function definition + * @type */ export type CommandFunction = (input: InputManager) => CommandFunctionReturnTypes; /** * Regular expressions used globally to perform name checking + * @property {RegExp} baseName - base command name (used for context menu) + * @property {RegExp} chatName - chat command name + * @property {RegExp} chatDescription - chat command description + * @property {RegExp} separator - argument and command separators + * @property {RegExp} prefix - global and guild-scoped prefixes */ export const CommandRegExps = { baseName: /^.{1,32}$/, diff --git a/src/commands/types/permissions.ts b/src/commands/types/permissions.ts index 91fb5a0..ad2908c 100644 --- a/src/commands/types/permissions.ts +++ b/src/commands/types/permissions.ts @@ -2,17 +2,19 @@ import { PermissionResolvable, Message, Interaction } from "discord.js"; /** * Permission checking methods + * @type */ export type PermissionCheckTypes = "ALL" | "ANY"; /** * Definition of permission function + * @type */ export type PermissionFunction = (i: Interaction | Message) => boolean; /** - * @interface * Command permissions initialization object + * @interface */ export interface CommandPermissionsInit { /**