From 8444576f45da5fdddbf8ba2d91b4cb31a3b51c04 Mon Sep 17 00:00:00 2001 From: Almeida Date: Mon, 19 Sep 2022 01:32:28 +0100 Subject: [PATCH] docs(builders/components): document constructors (#8636) --- packages/builders/src/components/ActionRow.ts | 36 +++++++++++++++++++ .../builders/src/components/button/Button.ts | 14 ++++---- .../src/components/selectMenu/SelectMenu.ts | 31 ++++++++++++++++ .../components/selectMenu/SelectMenuOption.ts | 22 ++++++++++++ .../src/components/textInput/TextInput.ts | 23 ++++++++++++ 5 files changed, 119 insertions(+), 7 deletions(-) diff --git a/packages/builders/src/components/ActionRow.ts b/packages/builders/src/components/ActionRow.ts index e328e4664812..1f10ddc85e8c 100644 --- a/packages/builders/src/components/ActionRow.ts +++ b/packages/builders/src/components/ActionRow.ts @@ -1,3 +1,5 @@ +/* eslint-disable jsdoc/check-param-names */ + import { type APIActionRowComponent, ComponentType, @@ -33,6 +35,40 @@ export class ActionRowBuilder extends ComponentBu */ public readonly components: T[]; + /** + * Creates a new action row from API data + * + * @param data - The API data to create this action row with + * @example + * Creating an action row from an API data object + * ```ts + * const actionRow = new ActionRowBuilder({ + * components: [ + * { + * custom_id: "custom id", + * label: "Type something", + * style: TextInputStyle.Short, + * type: ComponentType.TextInput, + * }, + * ], + * }); + * ``` + * @example + * Creating an action row using setters and API data + * ```ts + * const actionRow = new ActionRowBuilder({ + * components: [ + * { + * custom_id: "custom id", + * label: "Click me", + * style: ButtonStyle.Primary, + * type: ComponentType.Button, + * }, + * ], + * }) + * .addComponents(button2, button3); + * ``` + */ public constructor({ components, ...data }: Partial> = {}) { super({ type: ComponentType.ActionRow, ...data }); this.components = (components?.map((component) => createComponentBuilder(component)) ?? []) as T[]; diff --git a/packages/builders/src/components/button/Button.ts b/packages/builders/src/components/button/Button.ts index 7f05c636a529..f6edbb863ed0 100644 --- a/packages/builders/src/components/button/Button.ts +++ b/packages/builders/src/components/button/Button.ts @@ -29,24 +29,24 @@ export class ButtonBuilder extends ComponentBuilder { * Creating a button from an API data object * ```ts * const button = new ButtonBuilder({ - * style: 'primary', + * custom_id: 'a cool button', + * style: ButtonStyle.Primary, * label: 'Click Me', * emoji: { - * name: ':smile:', - * id: '12345678901234567890123456789012', + * name: 'smile', + * id: '123456789012345678', * }, - * custom_id: '12345678901234567890123456789012', * }); * ``` * @example * Creating a button using setters and API data * ```ts * const button = new ButtonBuilder({ - * style: 'primary', + * style: ButtonStyle.Secondary, * label: 'Click Me', * }) - * .setEmoji({ name: ':smile:', id: '12345678901234567890123456789012' }) - * .setCustomId('12345678901234567890123456789012'); + * .setEmoji({ name: '🙂' }) + * .setCustomId('another cool button'); * ``` */ public constructor(data?: Partial) { diff --git a/packages/builders/src/components/selectMenu/SelectMenu.ts b/packages/builders/src/components/selectMenu/SelectMenu.ts index a3806ad3aef3..496138a020ac 100644 --- a/packages/builders/src/components/selectMenu/SelectMenu.ts +++ b/packages/builders/src/components/selectMenu/SelectMenu.ts @@ -21,6 +21,37 @@ export class SelectMenuBuilder extends ComponentBuilder */ public readonly options: SelectMenuOptionBuilder[]; + /** + * Creates a new select menu from API data + * + * @param data - The API data to create this select menu with + * @example + * Creating a select menu from an API data object + * ```ts + * const selectMenu = new SelectMenuBuilder({ + * custom_id: 'a cool select menu', + * placeholder: 'select an option', + * max_values: 2, + * options: [ + * { label: 'option 1', value: '1' }, + * { label: 'option 2', value: '2' }, + * { label: 'option 3', value: '3' }, + * ], + * }); + * ``` + * @example + * Creating a select menu using setters and API data + * ```ts + * const selectMenu = new SelectMenuBuilder({ + * custom_id: 'a cool select menu', + * }) + * .setMinValues(1) + * .addOptions({ + * label: 'Catchy', + * value: 'catch', + * }); + * ``` + */ public constructor(data?: Partial) { const { options, ...initData } = data ?? {}; super({ type: ComponentType.SelectMenu, ...initData }); diff --git a/packages/builders/src/components/selectMenu/SelectMenuOption.ts b/packages/builders/src/components/selectMenu/SelectMenuOption.ts index 2529eeff2143..1b2249db59f5 100644 --- a/packages/builders/src/components/selectMenu/SelectMenuOption.ts +++ b/packages/builders/src/components/selectMenu/SelectMenuOption.ts @@ -11,6 +11,28 @@ import { * Represents a option within a select menu component */ export class SelectMenuOptionBuilder implements JSONEncodable { + /** + * Creates a new select menu option from API data + * + * @param data - The API data to create this select menu option with + * @example + * Creating a select menu option from an API data object + * ```ts + * const selectMenuOption = new SelectMenuOptionBuilder({ + * label: 'catchy label', + * value: '1', + * }); + * ``` + * @example + * Creating a select menu option using setters and API data + * ```ts + * const selectMenuOption = new SelectMenuOptionBuilder({ + * default: true, + * value: '1', + * }) + * .setLabel('woah') + * ``` + */ public constructor(public data: Partial = {}) {} /** diff --git a/packages/builders/src/components/textInput/TextInput.ts b/packages/builders/src/components/textInput/TextInput.ts index 04f4dfa2cbe7..6a9677ca1184 100644 --- a/packages/builders/src/components/textInput/TextInput.ts +++ b/packages/builders/src/components/textInput/TextInput.ts @@ -19,6 +19,29 @@ export class TextInputBuilder extends ComponentBuilder implements Equatable> { + /** + * Creates a new text input from API data + * + * @param data - The API data to create this text input with + * @example + * Creating a select menu option from an API data object + * ```ts + * const textInput = new TextInputBuilder({ + * custom_id: 'a cool select menu', + * label: 'Type something', + * style: TextInputStyle.Short, + * }); + * ``` + * @example + * Creating a select menu option using setters and API data + * ```ts + * const textInput = new TextInputBuilder({ + * label: 'Type something else', + * }) + * .setCustomId('woah') + * .setStyle(TextInputStyle.Paragraph); + * ``` + */ public constructor(data?: APITextInputComponent & { type?: ComponentType.TextInput }) { super({ type: ComponentType.TextInput, ...data }); }