docs: add missing, fix existing (#10842)

* docs: add missing, fix existing

* refactor: new stuff

* fix: requested changes

* fix: use `@link` for `@mixes`

Co-authored-by: Qjuh <76154676+Qjuh@users.noreply.github.com>

* chore: disable bad eslint rule

---------

Co-authored-by: Qjuh <76154676+Qjuh@users.noreply.github.com>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

packages/builders/src/components/ActionRow.ts

@@ -1,5 +1,3 @@
-/* eslint-disable jsdoc/check-param-names */
-
 import type {
 	APITextInputComponent,
 	APIActionRowComponent,
@@ -43,10 +41,11 @@ export interface ActionRowBuilderData
 
 /**
  * A builder that creates API-compatible JSON data for action rows.
- *
- * @typeParam ComponentType - The types of components this action row holds
  */
 export class ActionRowBuilder extends ComponentBuilder<APIActionRowComponent<APIComponentInActionRow>> {
+	/**
+	 * @internal
+	 */
 	protected readonly data: ActionRowBuilderData;
 
 	/**
@@ -57,7 +56,7 @@ export class ActionRowBuilder extends ComponentBuilder<APIActionRowComponent<API
 	}
 
 	/**
-	 * Creates a new action row from API data.
+	 * Creates a new action row.
 	 *
 	 * @param data - The API data to create this action row with
 	 * @example
@@ -90,12 +89,15 @@ export class ActionRowBuilder extends ComponentBuilder<APIActionRowComponent<API
 	 * 	.addComponents(button2, button3);
 	 * ```
 	 */
-	public constructor({ components = [], ...data }: Partial<APIActionRowComponent<APIComponentInActionRow>> = {}) {
+	public constructor(data: Partial<APIActionRowComponent<APIComponentInActionRow>> = {}) {
 		super();
+
+		const { components = [], ...rest } = data;
+
 		this.data = {
-			...structuredClone(data),
-			type: ComponentType.ActionRow,
+			...structuredClone(rest),
 			components: components.map((component) => createComponentBuilder(component)),
+			type: ComponentType.ActionRow,
 		};
 	}
 

packages/builders/src/components/Component.ts

@@ -13,6 +13,9 @@ export interface ComponentBuilderBaseData {
 export abstract class ComponentBuilder<Component extends APIBaseComponent<ComponentType>>
 	implements JSONEncodable<Component>
 {
+	/**
+	 * @internal
+	 */
 	protected abstract readonly data: ComponentBuilderBaseData;
 
 	/**

packages/builders/src/components/button/Button.ts

@@ -7,6 +7,9 @@ import { ComponentBuilder } from '../Component.js';
  * A builder that creates API-compatible JSON data for buttons.
  */
 export abstract class BaseButtonBuilder<ButtonData extends APIButtonComponent> extends ComponentBuilder<ButtonData> {
+	/**
+	 * @internal
+	 */
 	declare protected readonly data: Partial<ButtonData>;
 
 	/**

packages/builders/src/components/button/CustomIdButton.ts

@@ -7,6 +7,9 @@ export type CustomIdButtonStyle = APIButtonComponentWithCustomId['style'];
 
 /**
  * A builder that creates API-compatible JSON data for buttons with custom IDs.
+ *
+ * @mixes {@link BaseButtonBuilder}\<{@link discord-api-types/v10#(APIButtonComponentWithCustomId:interface)}\>
+ * @mixes {@link EmojiOrLabelButtonMixin}
  */
 export abstract class CustomIdButtonBuilder extends Mixin(
 	BaseButtonBuilder<APIButtonComponentWithCustomId>,

packages/builders/src/components/button/LinkButton.ts

@@ -10,6 +10,9 @@ import { EmojiOrLabelButtonMixin } from './mixins/EmojiOrLabelButtonMixin.js';
 
 /**
  * A builder that creates API-compatible JSON data for buttons with links.
+ *
+ * @mixes {@link BaseButtonBuilder}\<{@link discord-api-types/v10#(APIButtonComponentWithURL:interface)}\>
+ * @mixes {@link EmojiOrLabelButtonMixin}
  */
 export class LinkButtonBuilder extends Mixin(BaseButtonBuilder<APIButtonComponentWithURL>, EmojiOrLabelButtonMixin) {
 	protected override readonly data: Partial<APIButtonComponentWithURL>;

packages/builders/src/components/button/mixins/EmojiOrLabelButtonMixin.ts

@@ -3,7 +3,13 @@ import type { APIButtonComponent, APIButtonComponentWithSKUId, APIMessageCompone
 export interface EmojiOrLabelButtonData
 	extends Pick<Exclude<APIButtonComponent, APIButtonComponentWithSKUId>, 'emoji' | 'label'> {}
 
+/**
+ * A mixin that adds emoji and label symbols to a button builder.
+ */
 export class EmojiOrLabelButtonMixin {
+	/**
+	 * @internal
+	 */
 	declare protected readonly data: EmojiOrLabelButtonData;
 
 	/**

packages/builders/src/components/selectMenu/BaseSelectMenu.ts

@@ -5,12 +5,15 @@ import { ComponentBuilder } from '../Component.js';
 /**
  * The base select menu builder that contains common symbols for select menu builders.
  *
- * @typeParam SelectMenuType - The type of select menu this would be instantiated for.
+ * @typeParam Data - The type of API data that is stored within the builder
  */
 export abstract class BaseSelectMenuBuilder<Data extends APISelectMenuComponent>
 	extends ComponentBuilder<Data>
 	implements JSONEncodable<APISelectMenuComponent>
 {
+	/**
+	 * @internal
+	 */
 	protected abstract override readonly data: Partial<
 		Pick<Data, 'custom_id' | 'disabled' | 'id' | 'max_values' | 'min_values' | 'placeholder'>
 	>;

packages/builders/src/components/selectMenu/ChannelSelectMenu.ts

@@ -17,9 +17,9 @@ export class ChannelSelectMenuBuilder extends BaseSelectMenuBuilder<APIChannelSe
 	protected override readonly data: Partial<APIChannelSelectComponent>;
 
 	/**
-	 * Creates a new select menu from API data.
+	 * Creates a new channel select menu.
 	 *
-	 * @param data - The API data to create this select menu with
+	 * @param data - The API data to create this channel select menu with
 	 * @example
 	 * Creating a select menu from an API data object:
 	 * ```ts

packages/builders/src/components/selectMenu/MentionableSelectMenu.ts

@@ -17,9 +17,9 @@ export class MentionableSelectMenuBuilder extends BaseSelectMenuBuilder<APIMenti
 	protected override readonly data: Partial<APIMentionableSelectComponent>;
 
 	/**
-	 * Creates a new select menu from API data.
+	 * Creates a new mentionable select menu.
 	 *
-	 * @param data - The API data to create this select menu with
+	 * @param data - The API data to create this mentionable select menu with
 	 * @example
 	 * Creating a select menu from an API data object:
 	 * ```ts

packages/builders/src/components/selectMenu/RoleSelectMenu.ts

@@ -16,9 +16,9 @@ export class RoleSelectMenuBuilder extends BaseSelectMenuBuilder<APIRoleSelectCo
 	protected override readonly data: Partial<APIRoleSelectComponent>;
 
 	/**
-	 * Creates a new select menu from API data.
+	 * Creates a new role select menu.
 	 *
-	 * @param data - The API data to create this select menu with
+	 * @param data - The API data to create this role select menu with
 	 * @example
 	 * Creating a select menu from an API data object:
 	 * ```ts

packages/builders/src/components/selectMenu/StringSelectMenu.ts

@@ -1,5 +1,3 @@
-/* eslint-disable jsdoc/check-param-names */
-
 import { ComponentType } from 'discord-api-types/v10';
 import type { APIStringSelectComponent, APISelectMenuOption } from 'discord-api-types/v10';
 import { normalizeArray, type RestOrArray } from '../../util/normalizeArray.js';
@@ -27,9 +25,9 @@ export class StringSelectMenuBuilder extends BaseSelectMenuBuilder<APIStringSele
 	}
 
 	/**
-	 * Creates a new select menu from API data.
+	 * Creates a new string select menu.
 	 *
-	 * @param data - The API data to create this select menu with
+	 * @param data - The API data to create this string select menu with
 	 * @example
 	 * Creating a select menu from an API data object:
 	 * ```ts
@@ -57,10 +55,13 @@ export class StringSelectMenuBuilder extends BaseSelectMenuBuilder<APIStringSele
 	 * 	});
 	 * ```
 	 */
-	public constructor({ options = [], ...data }: Partial<APIStringSelectComponent> = {}) {
+	public constructor(data: Partial<APIStringSelectComponent> = {}) {
 		super();
+
+		const { options = [], ...rest } = data;
+
 		this.data = {
-			...structuredClone(data),
+			...structuredClone(rest),
 			options: options.map((option) => new StringSelectMenuOptionBuilder(option)),
 			type: ComponentType.StringSelect,
 		};

packages/builders/src/components/selectMenu/StringSelectMenuOption.ts

@@ -10,7 +10,7 @@ export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMen
 	private readonly data: Partial<APISelectMenuOption>;
 
 	/**
-	 * Creates a new string select menu option from API data.
+	 * Creates a new string select menu option.
 	 *
 	 * @param data - The API data to create this string select menu option with
 	 * @example

packages/builders/src/components/selectMenu/UserSelectMenu.ts

@@ -16,9 +16,9 @@ export class UserSelectMenuBuilder extends BaseSelectMenuBuilder<APIUserSelectCo
 	protected override readonly data: Partial<APIUserSelectComponent>;
 
 	/**
-	 * Creates a new select menu from API data.
+	 * Creates a new user select menu.
 	 *
-	 * @param data - The API data to create this select menu with
+	 * @param data - The API data to create this user select menu with
 	 * @example
 	 * Creating a select menu from an API data object:
 	 * ```ts

packages/builders/src/components/textInput/TextInput.ts

@@ -7,10 +7,13 @@ import { textInputPredicate } from './Assertions.js';
  * A builder that creates API-compatible JSON data for text inputs.
  */
 export class TextInputBuilder extends ComponentBuilder<APITextInputComponent> {
+	/**
+	 * @internal
+	 */
 	protected readonly data: Partial<APITextInputComponent>;
 
 	/**
-	 * Creates a new text input from API data.
+	 * Creates a new text input.
 	 *
 	 * @param data - The API data to create this text input with
 	 * @example

packages/builders/src/components/v2/Container.ts

@@ -34,11 +34,32 @@ export interface ContainerBuilderData extends Partial<Omit<APIContainerComponent
 	components: ContainerComponentBuilders[];
 }
 
+/**
+ * A builder that creates API-compatible JSON data for containers.
+ */
 export class ContainerBuilder extends ComponentBuilder<APIContainerComponent> {
+	/**
+	 * @internal
+	 */
 	protected readonly data: ContainerBuilderData;
 
-	public constructor({ components = [], ...rest }: Partial<APIContainerComponent> = {}) {
+	/**
+	 * Gets the components within this container.
+	 */
+	public get components(): readonly ContainerComponentBuilders[] {
+		return this.data.components;
+	}
+
+	/**
+	 * Creates a new container builder.
+	 *
+	 * @param data - The API data to create the container with
+	 */
+	public constructor(data: Partial<APIContainerComponent> = {}) {
 		super();
+
+		const { components = [], ...rest } = data;
+
 		this.data = {
 			...structuredClone(rest),
 			components: components.map((component) => createComponentBuilder(component)),

packages/builders/src/components/v2/File.ts

@@ -3,11 +3,17 @@ import { validate } from '../../util/validation.js';
 import { ComponentBuilder } from '../Component.js';
 import { filePredicate } from './Assertions.js';
 
+/**
+ * A builder that creates API-compatible JSON data for files.
+ */
 export class FileBuilder extends ComponentBuilder<APIFileComponent> {
+	/**
+	 * @internal
+	 */
 	protected readonly data: Partial<APIFileComponent>;
 
 	/**
-	 * Creates a new file from API data.
+	 * Creates a new file.
 	 *
 	 * @param data - The API data to create this file with
 	 * @example
@@ -33,9 +39,12 @@ export class FileBuilder extends ComponentBuilder<APIFileComponent> {
 	 */
 	public constructor(data: Partial<APIFileComponent> = {}) {
 		super();
+
+		const { file, ...rest } = data;
+
 		this.data = {
-			...structuredClone(data),
-			file: data.file ? { url: data.file.url } : undefined,
+			...structuredClone(rest),
+			file: file && { url: file.url },
 			type: ComponentType.File,
 		};
 	}

packages/builders/src/components/v2/MediaGallery.ts

@@ -10,11 +10,24 @@ export interface MediaGalleryBuilderData extends Partial<Omit<APIMediaGalleryCom
 	items: MediaGalleryItemBuilder[];
 }
 
+/**
+ * A builder that creates API-compatible JSON data for media galleries.
+ */
 export class MediaGalleryBuilder extends ComponentBuilder<APIMediaGalleryComponent> {
+	/**
+	 * @internal
+	 */
 	protected readonly data: MediaGalleryBuilderData;
 
 	/**
-	 * Creates a new media gallery from API data.
+	 * The items in this media gallery.
+	 */
+	public get items(): readonly MediaGalleryItemBuilder[] {
+		return this.data.items;
+	}
+
+	/**
+	 * Creates a new media gallery.
 	 *
 	 * @param data - The API data to create this container with
 	 * @example
@@ -49,19 +62,16 @@ export class MediaGalleryBuilder extends ComponentBuilder<APIMediaGalleryCompone
 	 */
 	public constructor(data: Partial<APIMediaGalleryComponent> = {}) {
 		super();
+
+		const { items = [], ...rest } = data;
+
 		this.data = {
-			items: data?.items?.map((item) => new MediaGalleryItemBuilder(item)) ?? [],
+			...structuredClone(rest),
+			items: items.map((item) => new MediaGalleryItemBuilder(item)),
 			type: ComponentType.MediaGallery,
 		};
 	}
 
-	/**
-	 * The items in this media gallery.
-	 */
-	public get items(): readonly MediaGalleryItemBuilder[] {
-		return this.data.items;
-	}
-
 	/**
 	 * Adds a media gallery item to this media gallery.
 	 *

packages/builders/src/components/v2/MediaGalleryItem.ts

@@ -7,7 +7,7 @@ export class MediaGalleryItemBuilder implements JSONEncodable<APIMediaGalleryIte
 	private readonly data: Partial<APIMediaGalleryItem>;
 
 	/**
-	 * Creates a new media gallery item from API data.
+	 * Creates a new media gallery item.
 	 *
 	 * @param data - The API data to create this media gallery item with
 	 * @example
@@ -32,9 +32,7 @@ export class MediaGalleryItemBuilder implements JSONEncodable<APIMediaGalleryIte
 	 * ```
 	 */
 	public constructor(data: Partial<APIMediaGalleryItem> = {}) {
-		this.data = {
-			...structuredClone(data),
-		};
+		this.data = structuredClone(data);
 	}
 
 	/**

packages/builders/src/components/v2/Section.ts

@@ -32,15 +32,24 @@ export interface SectionBuilderData extends Partial<Omit<APISectionComponent, 'a
 	components: TextDisplayBuilder[];
 }
 
+/**
+ * A builder that creates API-compatible JSON data for sections.
+ */
 export class SectionBuilder extends ComponentBuilder<APISectionComponent> {
+	/**
+	 * @internal
+	 */
 	protected readonly data: SectionBuilderData;
 
+	/**
+	 * The components within this section.
+	 */
 	public get components(): readonly TextDisplayBuilder[] {
 		return this.data.components;
 	}
 
 	/**
-	 * Creates a new section from API data.
+	 * Creates a new section.
 	 *
 	 * @param data - The API data to create this section with
 	 * @example
@@ -81,7 +90,7 @@ export class SectionBuilder extends ComponentBuilder<APISectionComponent> {
 
 		this.data = {
 			...structuredClone(rest),
-			accessory: accessory ? resolveAccessoryComponent(accessory) : undefined,
+			accessory: accessory && resolveAccessoryComponent(accessory),
 			components: components.map((component) => new TextDisplayBuilder(component)),
 			type: ComponentType.Section,
 		};

packages/builders/src/components/v2/Separator.ts

@@ -4,11 +4,17 @@ import { validate } from '../../util/validation.js';
 import { ComponentBuilder } from '../Component.js';
 import { separatorPredicate } from './Assertions.js';
 
+/**
+ * A builder that creates API-compatible JSON data for separators.
+ */
 export class SeparatorBuilder extends ComponentBuilder<APISeparatorComponent> {
+	/**
+	 * @internal
+	 */
 	protected readonly data: Partial<APISeparatorComponent>;
 
 	/**
-	 * Creates a new separator from API data.
+	 * Creates a new separator.
 	 *
 	 * @param data - The API data to create this separator with
 	 * @example

packages/builders/src/components/v2/TextDisplay.ts

@@ -4,11 +4,17 @@ import { validate } from '../../util/validation.js';
 import { ComponentBuilder } from '../Component.js';
 import { textDisplayPredicate } from './Assertions.js';
 
+/**
+ * A builder that creates API-compatible JSON data for text displays.
+ */
 export class TextDisplayBuilder extends ComponentBuilder<APITextDisplayComponent> {
+	/**
+	 * @internal
+	 */
 	protected readonly data: Partial<APITextDisplayComponent>;
 
 	/**
-	 * Creates a new text display from API data.
+	 * Creates a new text display.
 	 *
 	 * @param data - The API data to create this text display with
 	 * @example

packages/builders/src/components/v2/Thumbnail.ts

@@ -4,11 +4,17 @@ import { validate } from '../../util/validation.js';
 import { ComponentBuilder } from '../Component.js';
 import { thumbnailPredicate } from './Assertions.js';
 
+/**
+ * A builder that creates API-compatible JSON data for thumbnails.
+ */
 export class ThumbnailBuilder extends ComponentBuilder<APIThumbnailComponent> {
+	/**
+	 * @internal
+	 */
 	protected readonly data: Partial<APIThumbnailComponent>;
 
 	/**
-	 * Creates a new thumbnail from API data.
+	 * Creates a new thumbnail.
 	 *
 	 * @param data - The API data to create this thumbnail with
 	 * @example
@@ -34,9 +40,12 @@ export class ThumbnailBuilder extends ComponentBuilder<APIThumbnailComponent> {
 	 */
 	public constructor(data: Partial<APIThumbnailComponent> = {}) {
 		super();
+
+		const { media, ...rest } = data;
+
 		this.data = {
-			...structuredClone(data),
-			media: data.media ? { url: data.media.url } : undefined,
+			...structuredClone(rest),
+			media: media && { url: media.url },
 			type: ComponentType.Thumbnail,
 		};
 	}