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/messages/AllowedMentions.ts

@@ -8,12 +8,15 @@ import { allowedMentionPredicate } from './Assertions.js';
  * A builder that creates API-compatible JSON data for allowed mentions.
  */
 export class AllowedMentionsBuilder implements JSONEncodable<APIAllowedMentions> {
+	/**
+	 * The API data associated with these allowed mentions.
+	 */
 	private readonly data: Partial<APIAllowedMentions>;
 
 	/**
-	 * Creates a new allowed mentions builder from API data.
+	 * Creates a new allowed mentions builder.
 	 *
-	 * @param data - The API data to create this allowed mentions builder with
+	 * @param data - The API data to create this allowed mentions with
 	 */
 	public constructor(data: Partial<APIAllowedMentions> = {}) {
 		this.data = structuredClone(data);

packages/builders/src/messages/Attachment.ts

@@ -7,12 +7,15 @@ import { attachmentPredicate } from './Assertions.js';
  * A builder that creates API-compatible JSON data for attachments.
  */
 export class AttachmentBuilder implements JSONEncodable<RESTAPIAttachment> {
+	/**
+	 * The API data associated with this attachment.
+	 */
 	private readonly data: Partial<RESTAPIAttachment>;
 
 	/**
-	 * Creates a new attachment builder from API data.
+	 * Creates a new attachment builder.
 	 *
-	 * @param data - The API data to create this attachment builder with
+	 * @param data - The API data to create this attachment with
 	 */
 	public constructor(data: Partial<RESTAPIAttachment> = {}) {
 		this.data = structuredClone(data);

packages/builders/src/messages/Message.ts

@@ -1,5 +1,3 @@
-/* eslint-disable jsdoc/check-param-names */
-
 import type { JSONEncodable } from '@discordjs/util';
 import type {
 	APIActionRowComponent,
@@ -86,21 +84,15 @@ export class MessageBuilder implements JSONEncodable<RESTPostAPIChannelMessageJS
 	}
 
 	/**
-	 * Creates a new message builder from API data.
+	 * Creates a new message builder.
 	 *
-	 * @param data - The API data to create this message builder with
+	 * @param data - The API data to create this message with
 	 */
-	public constructor({
-		attachments = [],
-		embeds = [],
-		components = [],
-		message_reference,
-		poll,
-		allowed_mentions,
-		...data
-	}: Partial<RESTPostAPIChannelMessageJSONBody> = {}) {
+	public constructor(data: Partial<RESTPostAPIChannelMessageJSONBody> = {}) {
+		const { attachments = [], embeds = [], components = [], message_reference, poll, allowed_mentions, ...rest } = data;
+
 		this.data = {
-			...structuredClone(data),
+			...structuredClone(rest),
 			allowed_mentions: allowed_mentions && new AllowedMentionsBuilder(allowed_mentions),
 			attachments: attachments.map((attachment) => new AttachmentBuilder(attachment)),
 			embeds: embeds.map((embed) => new EmbedBuilder(embed)),

packages/builders/src/messages/MessageReference.ts

@@ -7,12 +7,15 @@ import { messageReferencePredicate } from './Assertions.js';
  * A builder that creates API-compatible JSON data for message references.
  */
 export class MessageReferenceBuilder implements JSONEncodable<RESTAPIMessageReference> {
+	/**
+	 * The API data associated with this message reference.
+	 */
 	private readonly data: Partial<RESTAPIMessageReference>;
 
 	/**
-	 * Creates a new message reference builder from API data.
+	 * Creates a new message reference builder.
 	 *
-	 * @param data - The API data to create this message reference builder with
+	 * @param data - The API data to create this message reference with
 	 */
 	public constructor(data: Partial<RESTAPIMessageReference> = {}) {
 		this.data = structuredClone(data);

packages/builders/src/messages/embed/Embed.ts

@@ -35,16 +35,18 @@ export class EmbedBuilder implements JSONEncodable<APIEmbed> {
 	}
 
 	/**
-	 * Creates a new embed from API data.
+	 * Creates a new embed.
 	 *
 	 * @param data - The API data to create this embed with
 	 */
-	public constructor(data: APIEmbed = {}) {
+	public constructor(data: Partial<APIEmbed> = {}) {
+		const { author, fields = [], footer, ...rest } = data;
+
 		this.data = {
-			...structuredClone(data),
-			author: data.author && new EmbedAuthorBuilder(data.author),
-			fields: data.fields?.map((field) => new EmbedFieldBuilder(field)) ?? [],
-			footer: data.footer && new EmbedFooterBuilder(data.footer),
+			...structuredClone(rest),
+			author: author && new EmbedAuthorBuilder(author),
+			fields: fields.map((field) => new EmbedFieldBuilder(field)),
+			footer: footer && new EmbedFooterBuilder(footer),
 		};
 	}
 
@@ -338,9 +340,9 @@ export class EmbedBuilder implements JSONEncodable<APIEmbed> {
 		const data = {
 			...structuredClone(rest),
 			// Disable validation because the embedPredicate below will validate those as well
-			author: this.data.author?.toJSON(false),
-			fields: this.data.fields?.map((field) => field.toJSON(false)),
-			footer: this.data.footer?.toJSON(false),
+			author: author?.toJSON(false),
+			fields: fields.map((field) => field.toJSON(false)),
+			footer: footer?.toJSON(false),
 		};
 
 		validate(embedPredicate, data, validationOverride);

packages/builders/src/messages/embed/EmbedAuthor.ts

@@ -7,15 +7,18 @@ import { embedAuthorPredicate } from './Assertions.js';
  * A builder that creates API-compatible JSON data for the embed author.
  */
 export class EmbedAuthorBuilder implements JSONEncodable<APIEmbedAuthor> {
+	/**
+	 * The API data associated with this embed author.
+	 */
 	private readonly data: Partial<APIEmbedAuthor>;
 
 	/**
-	 * Creates a new embed author from API data.
+	 * Creates a new embed author.
 	 *
-	 * @param data - The API data to use
+	 * @param data - The API data to create this embed author with
 	 */
-	public constructor(data?: Partial<APIEmbedAuthor>) {
-		this.data = structuredClone(data) ?? {};
+	public constructor(data: Partial<APIEmbedAuthor> = {}) {
+		this.data = structuredClone(data);
 	}
 
 	/**

packages/builders/src/messages/embed/EmbedField.ts

@@ -7,15 +7,18 @@ import { embedFieldPredicate } from './Assertions.js';
  * A builder that creates API-compatible JSON data for embed fields.
  */
 export class EmbedFieldBuilder implements JSONEncodable<APIEmbedField> {
+	/**
+	 * The API data associated with this embed field.
+	 */
 	private readonly data: Partial<APIEmbedField>;
 
 	/**
-	 * Creates a new embed field from API data.
+	 * Creates a new embed field.
 	 *
-	 * @param data - The API data to use
+	 * @param data - The API data to create this embed field with
 	 */
-	public constructor(data?: Partial<APIEmbedField>) {
-		this.data = structuredClone(data) ?? {};
+	public constructor(data: Partial<APIEmbedField> = {}) {
+		this.data = structuredClone(data);
 	}
 
 	/**

packages/builders/src/messages/embed/EmbedFooter.ts

@@ -7,15 +7,18 @@ import { embedFooterPredicate } from './Assertions.js';
  * A builder that creates API-compatible JSON data for the embed footer.
  */
 export class EmbedFooterBuilder implements JSONEncodable<APIEmbedFooter> {
+	/**
+	 * The API data associated with this embed footer.
+	 */
 	private readonly data: Partial<APIEmbedFooter>;
 
 	/**
-	 * Creates a new embed footer from API data.
+	 * Creates a new embed footer.
 	 *
-	 * @param data - The API data to use
+	 * @param data - The API data to create this embed footer with
 	 */
-	public constructor(data?: Partial<APIEmbedFooter>) {
-		this.data = structuredClone(data) ?? {};
+	public constructor(data: Partial<APIEmbedFooter> = {}) {
+		this.data = structuredClone(data);
 	}
 
 	/**

packages/builders/src/messages/poll/Poll.ts

@@ -29,15 +29,17 @@ export class PollBuilder implements JSONEncodable<RESTAPIPoll> {
 	}
 
 	/**
-	 * Creates a new poll from API data.
+	 * Creates a new poll.
 	 *
 	 * @param data - The API data to create this poll with
 	 */
 	public constructor(data: Partial<RESTAPIPoll> = {}) {
+		const { question, answers = [], ...rest } = data;
+
 		this.data = {
-			...structuredClone(data),
-			question: new PollQuestionBuilder(data.question),
-			answers: data.answers?.map((answer) => new PollAnswerBuilder(answer)) ?? [],
+			...structuredClone(rest),
+			question: new PollQuestionBuilder(question),
+			answers: answers.map((answer) => new PollAnswerBuilder(answer)),
 		};
 	}
 

packages/builders/src/messages/poll/PollAnswer.ts

@@ -9,6 +9,9 @@ export interface PollAnswerData extends Omit<APIPollAnswer, 'answer_id' | 'poll_
 	poll_media: PollAnswerMediaBuilder;
 }
 
+/**
+ * A builder that creates API-compatible JSON data for poll answers.
+ */
 export class PollAnswerBuilder implements JSONEncodable<Omit<APIPollAnswer, 'answer_id'>> {
 	/**
 	 * The API data associated with this poll answer.
@@ -16,14 +19,16 @@ export class PollAnswerBuilder implements JSONEncodable<Omit<APIPollAnswer, 'ans
 	private readonly data: PollAnswerData;
 
 	/**
-	 * Creates a new poll answer from API data.
+	 * Creates a new poll answer.
 	 *
 	 * @param data - The API data to create this poll answer with
 	 */
 	public constructor(data: Partial<Omit<APIPollAnswer, 'answer_id'>> = {}) {
+		const { poll_media, ...rest } = data;
+
 		this.data = {
-			...structuredClone(data),
-			poll_media: new PollAnswerMediaBuilder(data.poll_media),
+			...structuredClone(rest),
+			poll_media: new PollAnswerMediaBuilder(poll_media),
 		};
 	}
 

packages/builders/src/messages/poll/PollMedia.ts

@@ -6,13 +6,15 @@ import type { APIPollMedia } from 'discord-api-types/v10';
 export abstract class PollMediaBuilder {
 	/**
 	 * The API data associated with this poll media.
+	 *
+	 * @internal
 	 */
 	protected readonly data: Partial<APIPollMedia>;
 
 	/**
-	 * Creates new poll media from API data.
+	 * Creates new poll media.
 	 *
-	 * @param data - The API data to use
+	 * @param data - The API data to create this poll media with
 	 */
 	public constructor(data: Partial<APIPollMedia> = {}) {
 		this.data = structuredClone(data);