feat(website): Show constructor information (#8540)

discordjs · Aug 22, 2022 · e42fd16 · e42fd16 · vercel · Aug 22, 2022
1 parent dd44e8b
commit e42fd16
Show file tree

Hide file tree

Showing 66 changed files with 689 additions and 625 deletions.
diff --git a/packages/builders/.eslintrc.json b/packages/builders/.eslintrc.json
@@ -1,3 +1,7 @@
 {
-	"extends": "../../.eslintrc.json"
+	"extends": "../../.eslintrc.json",
+	"plugins": ["eslint-plugin-tsdoc"],
+	"rules": {
+		"tsdoc/syntax": "warn"
+	}
 }
diff --git a/packages/builders/package.json b/packages/builders/package.json
@@ -74,6 +74,7 @@
 		"eslint-config-prettier": "^8.5.0",
 		"eslint-import-resolver-typescript": "^3.4.1",
 		"eslint-plugin-import": "^2.26.0",
+		"eslint-plugin-tsdoc": "^0.2.16",
 		"prettier": "^2.7.1",
 		"rollup-plugin-typescript2": "0.32.1",
 		"typescript": "^4.7.4",

diff --git a/packages/builders/src/components/ActionRow.ts b/packages/builders/src/components/ActionRow.ts
@@ -59,7 +59,7 @@ export class ActionRowBuilder<T extends AnyComponentBuilder> extends ComponentBu
 	}
 
 	/**
-	 * {@inheritDoc JSONEncodable.toJSON}
+	 * {@inheritDoc ComponentBuilder.toJSON}
 	 */
 	public toJSON(): APIActionRowComponent<ReturnType<T['toJSON']>> {
 		// eslint-disable-next-line @typescript-eslint/consistent-type-assertions

diff --git a/packages/builders/src/components/Component.ts b/packages/builders/src/components/Component.ts
@@ -23,7 +23,11 @@ export abstract class ComponentBuilder<
 	public readonly data: Partial<DataType>;
 
 	/**
-	 * {@inheritDoc JSONEncodable.toJSON}
+	 * Serializes this component to an API-compatible JSON object
+	 *
+	 * @remarks
+	 * This method runs validations on the data before serializing it.
+	 * As such, it may throw an error if the data is invalid.
 	 */
 	public abstract toJSON(): AnyAPIActionRowComponent;
 

diff --git a/packages/builders/src/components/button/Button.ts b/packages/builders/src/components/button/Button.ts
@@ -21,6 +21,35 @@ import { ComponentBuilder } from '../Component';
  * Represents a button component
  */
 export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {
+	/**
+	 * Creates a new button from API data
+	 * @param data - The API data to create this button with
+	 *
+	 * @example
+	 * Creating a button from an API data object
+	 * ```ts
+	 * const button = new ButtonBuilder({
+	 * 	style: 'primary',
+	 * 	label: 'Click Me',
+	 * 	emoji: {
+	 * 		name: ':smile:',
+	 * 		id: '12345678901234567890123456789012',
+	 * 	},
+	 *  custom_id: '12345678901234567890123456789012',
+	 * });
+	 * ```
+	 *
+	 * @example
+	 * Creating a button using setters and API data
+	 * ```ts
+	 * const button = new ButtonBuilder({
+	 * 	style: 'primary',
+	 * 	label: 'Click Me',
+	 * })
+	 * .setEmoji({ name: ':smile:', id: '12345678901234567890123456789012' })
+	 * .setCustomId('12345678901234567890123456789012');
+	 * ```
+	 */
 	public constructor(data?: Partial<APIButtonComponent>) {
 		super({ type: ComponentType.Button, ...data });
 	}
@@ -38,6 +67,10 @@ export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {
 	/**
 	 * Sets the URL for this button
 	 *
+	 * @remarks
+	 * This method is only available to buttons using the `Link` button style.
+	 * Only three types of URL schemes are currently supported: `https://`, `http://` and `discord://`
+	 *
 	 * @param url - The URL to open when this button is clicked
 	 */
 	public setURL(url: string) {
@@ -48,6 +81,9 @@ export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {
 	/**
 	 * Sets the custom id for this button
 	 *
+	 * @remarks
+	 * This method is only applicable to buttons that are not using the `Link` button style.
+	 *
 	 * @param customId - The custom id to use for this button
 	 */
 	public setCustomId(customId: string) {
@@ -86,7 +122,7 @@ export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {
 	}
 
 	/**
-	 * {@inheritDoc JSONEncodable.toJSON}
+	 * {@inheritDoc ComponentBuilder.toJSON}
 	 */
 	public toJSON(): APIButtonComponent {
 		validateRequiredButtonParameters(

diff --git a/packages/builders/src/components/selectMenu/SelectMenu.ts b/packages/builders/src/components/selectMenu/SelectMenu.ts
@@ -117,7 +117,7 @@ export class SelectMenuBuilder extends ComponentBuilder<APISelectMenuComponent>
 	}
 
 	/**
-	 * {@inheritDoc JSONEncodable.toJSON}
+	 * {@inheritDoc ComponentBuilder.toJSON}
 	 */
 	public toJSON(): APISelectMenuComponent {
 		validateRequiredSelectMenuParameters(this.options, this.data.custom_id);

diff --git a/packages/builders/src/components/selectMenu/SelectMenuOption.ts b/packages/builders/src/components/selectMenu/SelectMenuOption.ts
@@ -65,7 +65,7 @@ export class SelectMenuOptionBuilder implements JSONEncodable<APISelectMenuOptio
 	}
 
 	/**
-	 * {@inheritDoc JSONEncodable.toJSON}
+	 * {@inheritDoc ComponentBuilder.toJSON}
 	 */
 	public toJSON(): APISelectMenuOption {
 		validateRequiredSelectMenuOptionParameters(this.data.label, this.data.value);

diff --git a/packages/builders/src/components/textInput/TextInput.ts b/packages/builders/src/components/textInput/TextInput.ts
@@ -104,7 +104,7 @@ export class TextInputBuilder
 	}
 
 	/**
-	 * {@inheritDoc JSONEncodable.toJSON}
+	 * {@inheritDoc ComponentBuilder.toJSON}
 	 */
 	public toJSON(): APITextInputComponent {
 		validateRequiredParameters(this.data.custom_id, this.data.style, this.data.label);

diff --git a/packages/builders/src/interactions/contextMenuCommands/ContextMenuCommandBuilder.ts b/packages/builders/src/interactions/contextMenuCommands/ContextMenuCommandBuilder.ts
@@ -35,7 +35,7 @@ export class ContextMenuCommandBuilder {
 	 * Whether the command is enabled by default when the app is added to a guild
 	 *
 	 * @deprecated This property is deprecated and will be removed in the future.
-	 * You should use `setDefaultMemberPermissions` or `setDMPermission` instead.
+	 * You should use {@link ContextMenuCommandBuilder.setDefaultMemberPermissions} or {@link ContextMenuCommandBuilder.setDMPermission} instead.
 	 */
 	public readonly default_permission: boolean | undefined = undefined;
 
@@ -86,7 +86,7 @@ export class ContextMenuCommandBuilder {
 	 * @param value - Whether or not to enable this command by default
 	 *
 	 * @see https://discord.com/developers/docs/interactions/application-commands#permissions
-	 * @deprecated Use `setDefaultMemberPermissions` or `setDMPermission` instead.
+	 * @deprecated Use {@link ContextMenuCommandBuilder.setDefaultMemberPermissions} or {@link ContextMenuCommandBuilder.setDMPermission} instead.
 	 */
 	public setDefaultPermission(value: boolean) {
 		// Assert the value matches the conditions

diff --git a/packages/builders/src/interactions/modals/Modal.ts b/packages/builders/src/interactions/modals/Modal.ts
@@ -70,6 +70,9 @@ export class ModalBuilder implements JSONEncodable<APIModalInteractionResponseCa
 		return this;
 	}
 
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
 	public toJSON(): APIModalInteractionResponseCallbackData {
 		validateRequiredParameters(this.data.custom_id, this.data.title, this.components);
 		// eslint-disable-next-line @typescript-eslint/consistent-type-assertions

diff --git a/packages/builders/src/interactions/slashCommands/options/integer.ts b/packages/builders/src/interactions/slashCommands/options/integer.ts
@@ -14,6 +14,9 @@ export class SlashCommandIntegerOption
 {
 	public readonly type = ApplicationCommandOptionType.Integer as const;
 
+	/**
+	 * {@inheritDoc ApplicationCommandNumericOptionMinMaxValueMixin.setMaxValue}
+	 */
 	public setMaxValue(max: number): this {
 		numberValidator.parse(max);
 
@@ -22,6 +25,9 @@ export class SlashCommandIntegerOption
 		return this;
 	}
 
+	/**
+	 * {@inheritDoc ApplicationCommandNumericOptionMinMaxValueMixin.setMinValue}
+	 */
 	public setMinValue(min: number): this {
 		numberValidator.parse(min);
 

diff --git a/packages/builders/src/interactions/slashCommands/options/number.ts b/packages/builders/src/interactions/slashCommands/options/number.ts
@@ -14,6 +14,9 @@ export class SlashCommandNumberOption
 {
 	public readonly type = ApplicationCommandOptionType.Number as const;
 
+	/**
+	 * {@inheritDoc ApplicationCommandNumericOptionMinMaxValueMixin.setMaxValue}
+	 */
 	public setMaxValue(max: number): this {
 		numberValidator.parse(max);
 
@@ -22,6 +25,9 @@ export class SlashCommandNumberOption
 		return this;
 	}
 
+	/**
+	 * {@inheritDoc ApplicationCommandNumericOptionMinMaxValueMixin.setMinValue}
+	 */
 	public setMinValue(min: number): this {
 		numberValidator.parse(min);
 

diff --git a/packages/builders/src/messages/embed/Embed.ts b/packages/builders/src/messages/embed/Embed.ts
@@ -76,7 +76,7 @@ export class EmbedBuilder {
 	 * 	);
 	 * ```
 	 *
-	 * @param fields The fields to add
+	 * @param fields - The fields to add
 	 */
 	public addFields(...fields: RestOrArray<APIEmbedField>): this {
 		fields = normalizeArray(fields);
@@ -120,9 +120,9 @@ export class EmbedBuilder {
 	 * embed.spliceFields(-1, 1);
 	 * ```
 	 *
-	 * @param index The index to start at
-	 * @param deleteCount The number of fields to remove
-	 * @param fields The replacing field objects
+	 * @param index - The index to start at
+	 * @param deleteCount - The number of fields to remove
+	 * @param fields - The replacing field objects
 	 */
 	public spliceFields(index: number, deleteCount: number, ...fields: APIEmbedField[]): this {
 		// Ensure adding these fields won't exceed the 25 field limit
@@ -144,7 +144,7 @@ export class EmbedBuilder {
 	 *
 	 * You can set a maximum of 25 fields.
 	 *
-	 * @param fields The fields to set
+	 * @param fields - The fields to set
 	 */
 	public setFields(...fields: RestOrArray<APIEmbedField>) {
 		this.spliceFields(0, this.data.fields?.length ?? 0, ...normalizeArray(fields));
@@ -154,7 +154,7 @@ export class EmbedBuilder {
 	/**
 	 * Sets the author of this embed
 	 *
-	 * @param options The options for the author
+	 * @param options - The options for the author
 	 */
 
 	public setAuthor(options: EmbedAuthorOptions | null): this {
@@ -173,7 +173,7 @@ export class EmbedBuilder {
 	/**
 	 * Sets the color of this embed
 	 *
-	 * @param color The color of the embed
+	 * @param color - The color of the embed
 	 */
 	public setColor(color: number | RGBTuple | null): this {
 		// Data assertions
@@ -191,7 +191,7 @@ export class EmbedBuilder {
 	/**
 	 * Sets the description of this embed
 	 *
-	 * @param description The description
+	 * @param description - The description
 	 */
 	public setDescription(description: string | null): this {
 		// Data assertions
@@ -204,7 +204,7 @@ export class EmbedBuilder {
 	/**
 	 * Sets the footer of this embed
 	 *
-	 * @param options The options for the footer
+	 * @param options - The options for the footer
 	 */
 	public setFooter(options: EmbedFooterOptions | null): this {
 		if (options === null) {
@@ -222,7 +222,7 @@ export class EmbedBuilder {
 	/**
 	 * Sets the image of this embed
 	 *
-	 * @param url The URL of the image
+	 * @param url - The URL of the image
 	 */
 	public setImage(url: string | null): this {
 		// Data assertions
@@ -235,7 +235,7 @@ export class EmbedBuilder {
 	/**
 	 * Sets the thumbnail of this embed
 	 *
-	 * @param url The URL of the thumbnail
+	 * @param url - The URL of the thumbnail
 	 */
 	public setThumbnail(url: string | null): this {
 		// Data assertions
@@ -248,7 +248,7 @@ export class EmbedBuilder {
 	/**
 	 * Sets the timestamp of this embed
 	 *
-	 * @param timestamp The timestamp or date
+	 * @param timestamp - The timestamp or date
 	 */
 	public setTimestamp(timestamp: number | Date | null = Date.now()): this {
 		// Data assertions
@@ -261,7 +261,7 @@ export class EmbedBuilder {
 	/**
 	 * Sets the title of this embed
 	 *
-	 * @param title The title
+	 * @param title - The title
 	 */
 	public setTitle(title: string | null): this {
 		// Data assertions
@@ -274,7 +274,7 @@ export class EmbedBuilder {
 	/**
 	 * Sets the URL of this embed
 	 *
-	 * @param url The URL
+	 * @param url - The URL
 	 */
 	public setURL(url: string | null): this {
 		// Data assertions

diff --git a/packages/collection/.eslintrc.json b/packages/collection/.eslintrc.json
@@ -1,3 +1,7 @@
 {
-	"extends": "../../.eslintrc.json"
+	"extends": "../../.eslintrc.json",
+	"plugins": ["eslint-plugin-tsdoc"],
+	"rules": {
+		"tsdoc/syntax": "warn"
+	}
 }
diff --git a/packages/collection/package.json b/packages/collection/package.json
@@ -63,6 +63,7 @@
 		"eslint-config-prettier": "^8.5.0",
 		"eslint-import-resolver-typescript": "^3.4.1",
 		"eslint-plugin-import": "^2.26.0",
+		"eslint-plugin-tsdoc": "^0.2.16",
 		"prettier": "^2.7.1",
 		"rollup-plugin-typescript2": "0.32.1",
 		"typescript": "^4.7.4",

diff --git a/packages/proxy/.eslintrc.json b/packages/proxy/.eslintrc.json
@@ -1,3 +1,7 @@
 {
-	"extends": "../../.eslintrc.json"
+	"extends": "../../.eslintrc.json",
+	"plugins": ["eslint-plugin-tsdoc"],
+	"rules": {
+		"tsdoc/syntax": "warn"
+	}
 }
diff --git a/packages/rest/.eslintrc.json b/packages/rest/.eslintrc.json
@@ -1,3 +1,7 @@
 {
-	"extends": "../../.eslintrc.json"
+	"extends": "../../.eslintrc.json",
+	"plugins": ["eslint-plugin-tsdoc"],
+	"rules": {
+		"tsdoc/syntax": "warn"
+	}
 }
diff --git a/packages/rest/package.json b/packages/rest/package.json
@@ -74,6 +74,7 @@
 		"eslint-config-prettier": "^8.5.0",
 		"eslint-import-resolver-typescript": "^3.4.1",
 		"eslint-plugin-import": "^2.26.0",
+		"eslint-plugin-tsdoc": "^0.2.16",
 		"prettier": "^2.7.1",
 		"rollup-plugin-typescript2": "0.32.1",
 		"typescript": "^4.7.4",

diff --git a/packages/rest/src/lib/REST.ts b/packages/rest/src/lib/REST.ts
@@ -91,7 +91,7 @@ export interface RESTOptions {
 	/**
 	 * Extra information to add to the user agent
 	 *
-	 * @defaultValue ``Node.js ${process.version}``
+	 * @defaultValue `Node.js ${process.version}`
 	 */
 	userAgentAppendix: string;
 	/**

diff --git a/packages/rest/src/lib/RequestManager.ts b/packages/rest/src/lib/RequestManager.ts
@@ -65,7 +65,7 @@ export interface RequestData {
 	 */
 	body?: BodyInit | unknown;
 	/**
-	 * The {@link https://undici.nodejs.org/#/docs/api/Agent Agent} to use for the request.
+	 * The {@link https://undici.nodejs.org/#/docs/api/Agent | Agent} to use for the request.
 	 */
 	dispatcher?: Agent;
 	/**
@@ -174,7 +174,7 @@ export interface RequestManager {
  */
 export class RequestManager extends EventEmitter {
 	/**
-	 * The {@link https://undici.nodejs.org/#/docs/api/Agent Agent} for all requests
+	 * The {@link https://undici.nodejs.org/#/docs/api/Agent | Agent} for all requests
 	 * performed by this manager.
 	 */
 	public agent: Dispatcher | null = null;
@@ -342,7 +342,7 @@ export class RequestManager extends EventEmitter {
 	 * @param hash - The hash for the route
 	 * @param majorParameter - The major parameter for this handler
 	 *
-	 * @private
+	 * @internal
 	 */
 	private createHandler(hash: string, majorParameter: string) {
 		// Create the async request queue to handle requests
@@ -487,7 +487,7 @@ export class RequestManager extends EventEmitter {
 	 * @param endpoint - The raw endpoint to generalize
 	 * @param method - The HTTP method this endpoint is called without
 	 *
-	 * @private
+	 * @internal
 	 */
 	private static generateRouteData(endpoint: RouteLike, method: RequestMethod): RouteData {
 		const majorIdMatch = /^\/(?:channels|guilds|webhooks)\/(\d{16,19})/.exec(endpoint);