diff --git a/.changeset/large-feet-applaud.md b/.changeset/large-feet-applaud.md new file mode 100644 index 0000000..b72b921 --- /dev/null +++ b/.changeset/large-feet-applaud.md @@ -0,0 +1,5 @@ +--- +"jellycommands": patch +--- + +feat: add more jsdoc comments to exports diff --git a/packages/jellycommands/src/JellyCommands.ts b/packages/jellycommands/src/JellyCommands.ts index e948157..93b7858 100644 --- a/packages/jellycommands/src/JellyCommands.ts +++ b/packages/jellycommands/src/JellyCommands.ts @@ -12,11 +12,47 @@ import { jellyCommandsOptionsSchema, } from './options'; +/** + * JellyCommands wraps the discord.js Client to provide a framework for building Discord Bots. + * If you’re familiar with discord.js you’ll see the similarities: + * + * ```js + * import { JellyCommands } from 'jellycommands'; + * import { IntentsBitField } from 'discord.js'; + * + * const client = new JellyCommands({ + * clientOptions: { + * intents: [IntentsBitField.Flags.Guilds], + * }, + * }); + * + * client.login(); + * ``` + * + * @see https://jellycommands.dev/guide/overview/#the-client + */ export class JellyCommands extends Client { // todo these options include data that isn't relevant (like given components) so mayb shouldn't be here + /** + * The options you pass to JellyCommands when creating your client. + */ public readonly joptions: JellyCommandsOptions; + + /** + * todo https://github.com/ghostdevv/jellycommands/issues/209 + */ private readonly plugins: SortedPlugins; + + /** + * Props are used to pass data around your client. + * @see https://jellycommands.dev/guide/props/ + */ public readonly props: Props; + + /** + * A wrapper of console.log that adds a nice prefix. + * Designed for internal use, so won't expand upon current functionality. + */ public readonly log: Logger; constructor(options: JellyCommandsOptions) { @@ -56,6 +92,10 @@ export class JellyCommands extends Client { }; } + /** + * Internal fetch wrapper for making Discord API requests. + * Please don't use this, as it may have breaking changes or disappear. + */ async $fetch< R = any, D extends Record = any, diff --git a/packages/jellycommands/src/components/buttons/buttons.ts b/packages/jellycommands/src/components/buttons/buttons.ts index d65ff2c..a03cea7 100644 --- a/packages/jellycommands/src/components/buttons/buttons.ts +++ b/packages/jellycommands/src/components/buttons/buttons.ts @@ -12,6 +12,10 @@ export type ButtonCallback = (context: { interaction: ButtonInteraction; }) => MaybePromise; +/** + * Represents a button. + * @see https://jellycommands.dev/guide/buttons/files/ + */ export class Button extends Component { public readonly options: ButtonOptions; @@ -28,6 +32,10 @@ export class Button extends Component { } } +/** + * Creates a button. + * @see https://jellycommands.dev/guide/buttons/files/ + */ export const button = (options: ButtonOptions & { run: ButtonCallback }) => { const { run, ...rest } = options; return new Button(rest, run); diff --git a/packages/jellycommands/src/components/commands/types/BaseCommand.ts b/packages/jellycommands/src/components/commands/types/BaseCommand.ts index 446ade4..2d69d3d 100644 --- a/packages/jellycommands/src/components/commands/types/BaseCommand.ts +++ b/packages/jellycommands/src/components/commands/types/BaseCommand.ts @@ -31,9 +31,19 @@ export abstract class BaseCommand< OptionsType extends BaseOptions = BaseOptions, InteractionType extends AnyCommandInteraction = AnyCommandInteraction, > extends Component { + /** + * The options you pass to when creating this command. + */ public readonly options: OptionsType; + + /** + * The callback function to call when your command is executed. + */ public readonly run: CommandCallback; + /** + * The command type for API purposes. + */ public abstract readonly type: ApplicationCommandType; constructor({ @@ -75,6 +85,9 @@ export abstract class BaseCommand< } } + /** + * This is for internal use and is subject to change. + */ get applicationCommandData(): RESTPostAPIApplicationCommandsJSONBody { return { name: this.options.name, @@ -86,6 +99,9 @@ export abstract class BaseCommand< }; } + /** + * This is for internal use and is subject to change. + */ get applicationCommandPermissions(): string | null { if (this.options.guards?.permissions) { const { bitfield } = new PermissionsBitField( @@ -97,6 +113,9 @@ export abstract class BaseCommand< return null; } + /** + * This is for internal use and is subject to change. + */ get hashId() { return createHash('sha256') .update(JSON.stringify(this.applicationCommandData)) diff --git a/packages/jellycommands/src/components/commands/types/commands/Command.ts b/packages/jellycommands/src/components/commands/types/commands/Command.ts index e2b2f12..352b958 100644 --- a/packages/jellycommands/src/components/commands/types/commands/Command.ts +++ b/packages/jellycommands/src/components/commands/types/commands/Command.ts @@ -20,6 +20,10 @@ export type AutocompleteHandler = (options: { client: JellyCommands; }) => MaybePromise; +/** + * Represents a slash command. + * @see https://jellycommands.dev/guide/commands/files/#slash-commands + */ export class Command extends BaseCommand< CommandOptions, ChatInputCommandInteraction @@ -46,6 +50,9 @@ export class Command extends BaseCommand< this.autocomplete = autocomplete; } + /** + * This is for internal use and is subject to change. + */ static transformOptionType( option: JellyApplicationCommandOption, ): ApplicationCommandOptionData { @@ -71,6 +78,9 @@ export class Command extends BaseCommand< return { ...option, options, type } as ApplicationCommandOption; } + /** + * This is for internal use and is subject to change. + */ static transformOption( option: JellyApplicationCommandOption, ): APIApplicationCommandOption { @@ -96,8 +106,15 @@ export class Command extends BaseCommand< } } +/** + * Creates a slash command. + * @see https://jellycommands.dev/guide/commands/files/#slash-commands + */ export const command = ( options: CommandOptions & { + /** + * The callback function to call when your command is executed. + */ run: CommandCallback; autocomplete?: AutocompleteHandler; }, diff --git a/packages/jellycommands/src/components/commands/types/messageCommands/MessageCommand.ts b/packages/jellycommands/src/components/commands/types/messageCommands/MessageCommand.ts index 2b0856a..85c77a1 100644 --- a/packages/jellycommands/src/components/commands/types/messageCommands/MessageCommand.ts +++ b/packages/jellycommands/src/components/commands/types/messageCommands/MessageCommand.ts @@ -5,6 +5,10 @@ import { messageCommandSchema, type MessageCommandOptions } from './options'; import { ApplicationCommandType } from 'discord-api-types/v10'; import { BaseCommand } from '../BaseCommand'; +/** + * Represents a Message Context Menu command. + * @see https://jellycommands.dev/guide/commands/files/#message-commands + */ export class MessageCommand extends BaseCommand< MessageCommandOptions, MessageContextMenuCommandInteraction @@ -19,8 +23,15 @@ export class MessageCommand extends BaseCommand< } } +/** + * Creates a Message Context Menu command. + * @see https://jellycommands.dev/guide/commands/files/#message-commands + */ export const messageCommand = ( options: MessageCommandOptions & { + /** + * The callback function to call when your command is executed. + */ run: CommandCallback; }, ) => { diff --git a/packages/jellycommands/src/components/commands/types/userCommands/UserCommand.ts b/packages/jellycommands/src/components/commands/types/userCommands/UserCommand.ts index 1e5df10..83aa290 100644 --- a/packages/jellycommands/src/components/commands/types/userCommands/UserCommand.ts +++ b/packages/jellycommands/src/components/commands/types/userCommands/UserCommand.ts @@ -5,6 +5,10 @@ import { userCommandSchema, type UserCommandOptions } from './options'; import { ApplicationCommandType } from 'discord-api-types/v10'; import { BaseCommand } from '../BaseCommand'; +/** + * Represents a User Context Menu command. + * @see https://jellycommands.dev/guide/commands/files/#user-commands + */ export class UserCommand extends BaseCommand< UserCommandOptions, UserContextMenuCommandInteraction @@ -19,8 +23,15 @@ export class UserCommand extends BaseCommand< } } +/** + * Creates a User Context Menu command. + * @see https://jellycommands.dev/guide/commands/files/#user-commands + */ export const userCommand = ( options: UserCommandOptions & { + /** + * The callback function to call when your command is executed. + */ run: CommandCallback; }, ) => { diff --git a/packages/jellycommands/src/components/components.ts b/packages/jellycommands/src/components/components.ts index 4b82b31..4627251 100644 --- a/packages/jellycommands/src/components/components.ts +++ b/packages/jellycommands/src/components/components.ts @@ -11,6 +11,9 @@ export interface BaseComponentOptions { export const COMPONENT_SYMBOL = Symbol.for('jellycommands.component'); +/** + * In JellyCommands component is a part of your Discord bot such as a `command`/`event`/etc. + */ export abstract class Component< O extends BaseComponentOptions = BaseComponentOptions, > { diff --git a/packages/jellycommands/src/components/events/Event.ts b/packages/jellycommands/src/components/events/Event.ts index de903c3..aac0b27 100644 --- a/packages/jellycommands/src/components/events/Event.ts +++ b/packages/jellycommands/src/components/events/Event.ts @@ -6,14 +6,28 @@ import { EVENTS_COMPONENT_ID } from './plugin'; import type { ClientEvents } from 'discord.js'; import { parseSchema } from '../../utils/zod'; +/** + * The Discord event name + * @see https://discord.js.org/docs/packages/discord.js/14.16.3/ClientEvents:Interface + */ export type EventName = keyof ClientEvents | (string & {}); +/** + * This callback will be run when your event is fired. + * It takes in a base JellyCommands context as it's first param, + * followed by all the arguments your event provides. + * + * @see https://jellycommands.dev/guide/events/files/ + */ export type EventCallback = ( ctx: { client: JellyCommands; props: Props }, ...args: E extends keyof ClientEvents ? ClientEvents[E] : any[] ) => MaybePromise; export class Event extends Component { + /** + * The options you pass to when creating this event. + */ public readonly options: Required>; constructor( @@ -38,13 +52,30 @@ export class Event extends Component { ); } + /** + * Type narrowing utility to check whether something is an event. + * @param item The thing to check + */ static is(item: any): item is Event { return isComponent(item) && item.id === EVENTS_COMPONENT_ID; } } +/** + * This creates an event component for your bot. Events can be used + * to respond to actions such as a new user joining a guild. + * + * @see https://jellycommands.dev/guide/events/files/ + */ export const event = ( options: EventOptions & { + /** + * This callback will be run when your event is fired. + * It takes in a base JellyCommands context as it's first param, + * followed by all the arguments your event provides. + * + * @see https://jellycommands.dev/guide/events/files/ + */ run: EventCallback; }, ) => { diff --git a/packages/jellycommands/src/components/events/options.ts b/packages/jellycommands/src/components/events/options.ts index eabbc61..cbab3db 100644 --- a/packages/jellycommands/src/components/events/options.ts +++ b/packages/jellycommands/src/components/events/options.ts @@ -4,7 +4,8 @@ import type { EventName } from './Event'; export interface EventOptions extends BaseComponentOptions { /** - * The event name: https://discord.js.org/#/docs/main/stable/class/Client + * The Discord event name + * @see https://discord.js.org/docs/packages/discord.js/14.16.3/ClientEvents:Interface */ name: Event; diff --git a/packages/jellycommands/src/options.ts b/packages/jellycommands/src/options.ts index aa577dd..a2bfdae 100644 --- a/packages/jellycommands/src/options.ts +++ b/packages/jellycommands/src/options.ts @@ -65,7 +65,10 @@ export interface JellyCommandsOptions { components?: LoadableComponents; /** - * Base discord.js client options + * You can use this to pass options to the base Discord.js client. + * This will need to be used to set `intents` at a minimum. + * + * @see https://discord.js.org/docs/packages/discord.js/14.16.3/ClientOptions:Interface */ clientOptions: ClientOptions; @@ -76,22 +79,37 @@ export interface JellyCommandsOptions { // plugins?: AnyPlugin[]; /** - * Inital props + * Props are used to pass data around your client. + * @see https://jellycommands.dev/guide/props/ */ props?: Props; /** - * Customisable responses + * This allows you to control the default messages sent by JellyCommands + * when your code is unable to handle them. Currently only handles + * an unknownCommand state. + * + * @see https://jellycommands.dev/guide/messages/ */ messages?: { /** - * This is sent when a unknown command is given + * This is sent when your bot recieves an unknown command. This only + * happens if your user sends a command just as you re-register them + * as we respond to commands based on id rather than name currently. + * + * @see https://jellycommands.dev/guide/messages/#unknown-command */ unknownCommand?: string | MessagePayload | InteractionReplyOptions; }; /** - * Developer mode options + * Developer mode makes it easier to iterate on your commands + * by registering them locally to a guild rather than locally. + * Discord checks for fresh guild commands every time, while global + * commands are only checked periodically. You should enable this + * when developing, and disable this in production. + * + * @see https://jellycommands.dev/guide/commands/dev/ */ dev?: { /** @@ -106,13 +124,22 @@ export interface JellyCommandsOptions { }; /** - * Should jelly cache commands - highly recommended + * Controls whether commands should be cached. This allows for restarting + * your Discord Bot repeatedly without having to re-register commands each + * time. It computes a hash of all your commands, and stores it locally to + * the `.jellycommands` folder which you should add to your git ignore. + * When you run your bot it uses this to see if you made any changes to your + * commands. If you have it'll automatically re-register them! + * + * We recommend you leave this on, at least when developing. + * * @default true */ cache?: boolean; /** - * Whether jelly should emit debug messages + * Controls whether debug messages are logged to console. + * By default it's false, unless the `DEBUG` environment variable is set. */ debug?: boolean;