fix(website): misc improvements (#9940)

* refactor: use tokenRange for typeParams in heritage * fix: correct type param replacement * fix: ae config, link builtin in summary, `: | T` => `: T`, mainlib tsdoc * fix: requested changes and tests * chore: better deprecation messages and code cleanup * fix: cleanup optional chainings --------- Co-authored-by: Almeida <almeidx@pm.me>
2026-03-13 18:13:29 +01:00 · 2023-11-13 09:55:23 +01:00
parent 2d63d93558
commit b79351ba99
7 changed files with 134 additions and 97 deletions
--- a/packages/api-extractor/config/api-extractor.json
+++ b/packages/api-extractor/config/api-extractor.json
@@ -5,12 +5,12 @@

 	"apiReport": {
 		"enabled": true,
-		"reportFolder": "../../../common/reviews/api"
+		"reportFolder": "<projectFolder>/docs/review"
 	},

 	"docModel": {
 		"enabled": true,
-		"apiJsonFilePath": "../../../common/temp/api/<unscopedPackageName>.api.json"
+		"apiJsonFilePath": "<projectFolder>/docs/<unscopedPackageName>.api.json"
 	},

 	"dtsRollup": {
--- a/packages/api-extractor/src/collector/Collector.ts
+++ b/packages/api-extractor/src/collector/Collector.ts
@@ -4,7 +4,7 @@
 import { ReleaseTag } from '@discordjs/api-extractor-model';
 import * as tsdoc from '@microsoft/tsdoc';
 import { PackageJsonLookup, Sort, InternalError } from '@rushstack/node-core-library';
-import * as ts from 'typescript';
+import ts from 'typescript';
 import { PackageDocComment } from '../aedoc/PackageDocComment.js';
 import type { AstDeclaration } from '../analyzer/AstDeclaration.js';
 import type { AstEntity } from '../analyzer/AstEntity.js';
--- a/packages/api-extractor/src/generators/ApiModelGenerator.ts
+++ b/packages/api-extractor/src/generators/ApiModelGenerator.ts
@@ -36,7 +36,6 @@ import {
 	Navigation,
 } from '@discordjs/api-extractor-model';
 import type * as tsdoc from '@microsoft/tsdoc';
-import { TSDocParser } from '@microsoft/tsdoc';
 import { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference.js';
 import { JsonFile, Path } from '@rushstack/node-core-library';
 import * as ts from 'typescript';
@@ -220,12 +219,16 @@ export class ApiModelGenerator {

 	private readonly _apiModel: ApiModel;

+	private readonly _tsDocParser: tsdoc.TSDocParser;
+
 	private readonly _referenceGenerator: DeclarationReferenceGenerator;

 	public constructor(collector: Collector) {
 		this._collector = collector;
 		this._apiModel = new ApiModel();
 		this._referenceGenerator = new DeclarationReferenceGenerator(collector);
+		// @ts-expect-error we reuse the private tsdocParser from collector here
+		this._tsDocParser = collector._tsdocParser;
 	}

 	public get apiModel(): ApiModel {
@@ -500,7 +503,7 @@ export class ApiModelGenerator {
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
 			const docComment: tsdoc.DocComment | undefined = parent?.construct
-				? new TSDocParser().parseString(
+				? this._tsDocParser.parseString(
 						`/*+\n * ${fixLinkTags(parent.construct.description)}\n${
 							parent.construct.params
 								?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`)
@@ -586,7 +589,7 @@ export class ApiModelGenerator {
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
 			const docComment: tsdoc.DocComment | undefined = jsDoc
-				? new TSDocParser().parseString(
+				? this._tsDocParser.parseString(
 						`/**\n * ${fixLinkTags(jsDoc.description)}\n${jsDoc.see?.map((see) => ` * @see ${see}\n`).join('') ?? ''}${
 							jsDoc.deprecated
 								? ` * @deprecated ${
@@ -658,7 +661,7 @@ export class ApiModelGenerator {
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
 			const docComment: tsdoc.DocComment | undefined = parent?.construct
-				? new TSDocParser().parseString(
+				? this._tsDocParser.parseString(
 						`/*+\n * ${fixLinkTags(parent.construct.description)}\n${
 							parent.construct.params
 								?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`)
@@ -789,7 +792,7 @@ export class ApiModelGenerator {
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
 			const docComment: tsdoc.DocComment | undefined = jsDoc
-				? new TSDocParser().parseString(
+				? this._tsDocParser.parseString(
 						`/**\n * ${fixLinkTags(jsDoc.description)}\n${
 							jsDoc.params?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('') ??
 							''
@@ -916,7 +919,7 @@ export class ApiModelGenerator {
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
 			const docComment: tsdoc.DocComment | undefined = jsDoc
-				? new TSDocParser().parseString(
+				? this._tsDocParser.parseString(
 						`/**\n * ${fixLinkTags(jsDoc.description)}\n${jsDoc.see?.map((see) => ` * @see ${see}\n`).join('') ?? ''}${
 							jsDoc.deprecated
 								? ` * @deprecated ${
@@ -980,7 +983,7 @@ export class ApiModelGenerator {
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
 			const docComment: tsdoc.DocComment | undefined = jsDoc
-				? new TSDocParser().parseString(
+				? this._tsDocParser.parseString(
 						`/**\n * ${fixLinkTags(jsDoc.description)}\n${
 							jsDoc.params?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('') ??
 							''
@@ -1058,7 +1061,7 @@ export class ApiModelGenerator {
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
 			const docComment: tsdoc.DocComment | undefined = jsDoc
-				? new TSDocParser().parseString(
+				? this._tsDocParser.parseString(
 						`/**\n * ${fixLinkTags(jsDoc.description)}\n${
 							jsDoc.params?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('') ??
 							''
@@ -1166,7 +1169,7 @@ export class ApiModelGenerator {
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
 			const docComment: tsdoc.DocComment | undefined = jsDoc
-				? new TSDocParser().parseString(
+				? this._tsDocParser.parseString(
 						`/**\n * ${fixLinkTags(jsDoc.description)}\n${
 							'see' in jsDoc ? jsDoc.see.map((see) => ` * @see ${see}\n`).join('') : ''
 						}${'readonly' in jsDoc && jsDoc.readonly ? ' * @readonly\n' : ''}${
@@ -1229,7 +1232,7 @@ export class ApiModelGenerator {
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
 			const docComment: tsdoc.DocComment | undefined = jsDoc
-				? new TSDocParser().parseString(
+				? this._tsDocParser.parseString(
 						`/**\n * ${fixLinkTags(jsDoc.description)}\n${
 							'see' in jsDoc ? jsDoc.see.map((see) => ` * @see ${see}\n`).join('') : ''
 						}${'readonly' in jsDoc && jsDoc.readonly ? ' * @readonly\n' : ''}${
@@ -1290,7 +1293,7 @@ export class ApiModelGenerator {
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
 			const docComment: tsdoc.DocComment | undefined = jsDoc
-				? new TSDocParser().parseString(
+				? this._tsDocParser.parseString(
 						`/**\n * ${fixLinkTags(jsDoc.description) ?? ''}\n${
 							'params' in jsDoc
 								? jsDoc.params.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('')
@@ -1425,7 +1428,7 @@ export class ApiModelGenerator {
 				});
 			}

-			const docComment: tsdoc.DocComment | undefined = new TSDocParser().parseString(
+			const docComment: tsdoc.DocComment | undefined = this._tsDocParser.parseString(
 				`/**\n * ${fixLinkTags(jsDoc.description)}\n${
 					jsDoc.params?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('') ?? ''
 				}${'see' in jsDoc ? jsDoc.see.map((see) => ` * @see ${see}\n`).join('') : ''}${
--- a/packages/api-extractor/src/generators/ExcerptBuilder.ts
+++ b/packages/api-extractor/src/generators/ExcerptBuilder.ts
@@ -135,7 +135,7 @@ export class ExcerptBuilder {
 		return { startIndex: 0, endIndex: 0, typeParameters: [] };
 	}

-	public static isPrimitiveKeyword(node: ts.Node): boolean {
+	private static _isPrimitiveKeyword(node: ts.Node): boolean {
 		switch (node.kind) {
 			case ts.SyntaxKind.AnyKeyword:
 			case ts.SyntaxKind.BigIntKeyword:
@@ -156,6 +156,15 @@ export class ExcerptBuilder {
 		}
 	}

+	private static _isRedundantBarAfterColon(span: Span) {
+		return (
+			span.kind === ts.SyntaxKind.BarToken &&
+			span.previousSibling === undefined &&
+			(span.parent?.parent?.previousSibling?.kind === ts.SyntaxKind.LessThanToken ||
+				span.parent?.parent?.previousSibling?.kind === ts.SyntaxKind.ColonToken)
+		);
+	}
+
 	private static _buildSpan(excerptTokens: IExcerptToken[], span: Span, state: IBuildSpanState): boolean {
 		if (span.kind === ts.SyntaxKind.JSDocComment) {
 			// Discard any comments
@@ -174,21 +183,21 @@ export class ExcerptBuilder {
 		if (span.prefix) {
 			let canonicalReference: DeclarationReference | undefined;

-			if (span.kind === ts.SyntaxKind.Identifier) {
-				const name: ts.Identifier = span.node as ts.Identifier;
+			if (ts.isIdentifier(span.node)) {
+				const name: ts.Identifier = span.node;
 				canonicalReference = state.referenceGenerator.getDeclarationReferenceForIdentifier(name);
 			}

 			if (canonicalReference) {
 				ExcerptBuilder._appendToken(excerptTokens, ExcerptTokenKind.Reference, span.prefix, canonicalReference);
 			} else if (
-				ExcerptBuilder.isPrimitiveKeyword(span.node) ||
-				(span.node.kind === ts.SyntaxKind.Identifier &&
+				ExcerptBuilder._isPrimitiveKeyword(span.node) ||
+				(ts.isIdentifier(span.node) &&
 					((ts.isTypeReferenceNode(span.node.parent) && span.node.parent.typeName === span.node) ||
 						(ts.isTypeParameterDeclaration(span.node.parent) && span.node.parent.name === span.node)))
 			) {
 				ExcerptBuilder._appendToken(excerptTokens, ExcerptTokenKind.Reference, span.prefix);
-			} else {
+			} else if (!ExcerptBuilder._isRedundantBarAfterColon(span)) {
 				ExcerptBuilder._appendToken(excerptTokens, ExcerptTokenKind.Content, span.prefix);
 			}

@@ -313,6 +322,12 @@ export class ExcerptBuilder {
 					!startOrEndIndices.has(currentIndex)
 				) {
 					prevToken.text += currentToken.text;
+					// Remove BarTokens from excerpts if they immediately follow a LessThanToken, e.g. `Promise< | Something>`
+					// would become `Promise<Something>`
+					if (/<\s*\|/.test(prevToken.text)) {
+						prevToken.text = prevToken.text.replace(/<\s*\|\s*/, '<');
+					}
+
 					mergeCount = 1;
 				} else {
 					// Otherwise, no merging can occur here. Continue to the next index.
--- a/packages/discord.js/typings/index.d.ts
+++ b/packages/discord.js/typings/index.d.ts
@@ -991,7 +991,7 @@ export class Client<Ready extends boolean = boolean> extends BaseClient {
  public fetchVoiceRegions(): Promise<Collection<string, VoiceRegion>>;
  public fetchSticker(id: Snowflake): Promise<Sticker>;
  public fetchStickerPacks(): Promise<Collection<Snowflake, StickerPack>>;
-  /** @deprecated Use {@link fetchStickerPacks} instead. */
+  /** @deprecated Use {@link Client#fetchStickerPacks} instead. */
  public fetchPremiumStickerPacks(): ReturnType<Client['fetchStickerPacks']>;
  public fetchWebhook(id: Snowflake, token?: string): Promise<Webhook>;
  public fetchGuildWidget(guild: GuildResolvable): Promise<Widget>;
@@ -1870,7 +1870,7 @@ export class BaseInteraction<Cached extends CacheType = CacheType> extends Base
  public isMessageContextMenuCommand(): this is MessageContextMenuCommandInteraction<Cached>;
  public isModalSubmit(): this is ModalSubmitInteraction<Cached>;
  public isUserContextMenuCommand(): this is UserContextMenuCommandInteraction<Cached>;
-  /** @deprecated Use {@link isStringSelectMenu} instead. */
+  /** @deprecated Use {@link BaseInteraction#isStringSelectMenu} instead. */
  public isSelectMenu(): this is StringSelectMenuInteraction<Cached>;
  public isAnySelectMenu(): this is AnySelectMenuInteraction<Cached>;
  public isStringSelectMenu(): this is StringSelectMenuInteraction<Cached>;
@@ -1957,12 +1957,12 @@ export class Invite extends Base {
  public toJSON(): unknown;
  public toString(): string;
  public static InvitesPattern: RegExp;
-  /** @deprecated */
+  /** @deprecated Public Stage Instances don't exist anymore  */
  public stageInstance: InviteStageInstance | null;
  public guildScheduledEvent: GuildScheduledEvent | null;
 }

-/** @deprecated */
+/** @deprecated Public Stage Instances don't exist anymore */
 export class InviteStageInstance extends Base {
  private constructor(client: Client<true>, data: RawInviteStageInstance, channelId: Snowflake, guildId: Snowflake);
  public channelId: Snowflake;
@@ -3065,7 +3065,7 @@ export class TeamMember extends Base {
  private constructor(team: Team, data: RawTeamMemberData);
  public team: Team;
  public get id(): Snowflake;
-  /** @deprecated Use {@link role} instead. */
+  /** @deprecated Use {@link TeamMember#role} instead. */
  public permissions: string[];
  public membershipState: TeamMemberMembershipState;
  public user: User;
@@ -3632,24 +3632,24 @@ export enum DiscordjsErrorCodes {
  TokenMissing = 'TokenMissing',
  ApplicationCommandPermissionsTokenMissing = 'ApplicationCommandPermissionsTokenMissing',

-  /** @deprecated */
+  /** @deprecated WebSocket errors are now handled in `@discordjs/ws` */
  WSCloseRequested = 'WSCloseRequested',
-  /** @deprecated */
+  /** @deprecated WebSocket errors are now handled in `@discordjs/ws` */
  WSConnectionExists = 'WSConnectionExists',
-  /** @deprecated */
+  /** @deprecated WebSocket errors are now handled in `@discordjs/ws` */
  WSNotOpen = 'WSNotOpen',
-  /** @deprecated */
+  /** @deprecated No longer in use */
  ManagerDestroyed = 'ManagerDestroyed',

  BitFieldInvalid = 'BitFieldInvalid',

-  /** @deprecated */
+  /** @deprecated This error is now handled in `@discordjs/ws` */
  ShardingInvalid = 'ShardingInvalid',
-  /** @deprecated */
+  /** @deprecated This error is now handled in `@discordjs/ws` */
  ShardingRequired = 'ShardingRequired',
-  /** @deprecated */
+  /** @deprecated This error is now handled in `@discordjs/ws` */
  InvalidIntents = 'InvalidIntents',
-  /** @deprecated */
+  /** @deprecated This error is now handled in `@discordjs/ws` */
  DisallowedIntents = 'DisallowedIntents',
  ShardingNoShards = 'ShardingNoShards',
  ShardingInProcess = 'ShardingInProcess',
@@ -3669,29 +3669,29 @@ export enum DiscordjsErrorCodes {

  InviteOptionsMissingChannel = 'InviteOptionsMissingChannel',

-  /** @deprecated */
+  /** @deprecated Button validation errors are now handled in `@discordjs/builders` */
  ButtonLabel = 'ButtonLabel',
-  /** @deprecated */
+  /** @deprecated Button validation errors are now handled in `@discordjs/builders` */
  ButtonURL = 'ButtonURL',
-  /** @deprecated */
+  /** @deprecated Button validation errors are now handled in `@discordjs/builders` */
  ButtonCustomId = 'ButtonCustomId',

-  /** @deprecated */
+  /** @deprecated Select Menu validation errors are now handled in `@discordjs/builders` */
  SelectMenuCustomId = 'SelectMenuCustomId',
-  /** @deprecated */
+  /** @deprecated Select Menu validation errors are now handled in `@discordjs/builders` */
  SelectMenuPlaceholder = 'SelectMenuPlaceholder',
-  /** @deprecated */
+  /** @deprecated Select Menu validation errors are now handled in `@discordjs/builders` */
  SelectOptionLabel = 'SelectOptionLabel',
-  /** @deprecated */
+  /** @deprecated Select Menu validation errors are now handled in `@discordjs/builders` */
  SelectOptionValue = 'SelectOptionValue',
-  /** @deprecated */
+  /** @deprecated Select Menu validation errors are now handled in `@discordjs/builders` */
  SelectOptionDescription = 'SelectOptionDescription',

  InteractionCollectorError = 'InteractionCollectorError',

  FileNotFound = 'FileNotFound',

-  /** @deprecated */
+  /** @deprecated No longer in use */
  UserBannerNotFetched = 'UserBannerNotFetched',
  UserNoDMChannel = 'UserNoDMChannel',

@@ -3702,16 +3702,16 @@ export enum DiscordjsErrorCodes {

  ReqResourceType = 'ReqResourceType',

-  /** @deprecated */
+  /** @deprecated This error is now handled in `@discordjs/rest` */
  ImageFormat = 'ImageFormat',
-  /** @deprecated */
+  /** @deprecated This error is now handled in `@discordjs/rest` */
  ImageSize = 'ImageSize',

  MessageBulkDeleteType = 'MessageBulkDeleteType',
  MessageNonceType = 'MessageNonceType',
  MessageContentType = 'MessageContentType',

-  /** @deprecated */
+  /** @deprecated No longer in use */
  SplitMaxLen = 'SplitMaxLen',

  BanResolveId = 'BanResolveId',
@@ -3747,14 +3747,14 @@ export enum DiscordjsErrorCodes {
  EmojiType = 'EmojiType',
  EmojiManaged = 'EmojiManaged',
  MissingManageGuildExpressionsPermission = 'MissingManageGuildExpressionsPermission',
-  /** @deprecated Use {@link MissingManageGuildExpressionsPermission} instead. */
+  /** @deprecated Use {@link DiscordjsErrorCodes.MissingManageGuildExpressionsPermission} instead. */
  MissingManageEmojisAndStickersPermission = 'MissingManageEmojisAndStickersPermission',

  NotGuildSticker = 'NotGuildSticker',

  ReactionResolveUser = 'ReactionResolveUser',

-  /** @deprecated */
+  /** @deprecated Not used anymore since the introduction of `GUILD_WEB_PAGE_VANITY_URL` feature */
  VanityURL = 'VanityURL',

  InviteResolveCode = 'InviteResolveCode',
@@ -3771,7 +3771,7 @@ export enum DiscordjsErrorCodes {

  InteractionAlreadyReplied = 'InteractionAlreadyReplied',
  InteractionNotReplied = 'InteractionNotReplied',
-  /** @deprecated */
+  /** @deprecated Not used anymore since ephemeral replies can now be deleted */
  InteractionEphemeralReplied = 'InteractionEphemeralReplied',

  CommandInteractionOptionNotFound = 'CommandInteractionOptionNotFound',
@@ -4801,7 +4801,7 @@ export interface AwaitReactionsOptions extends ReactionCollectorOptions {
 }

 export interface BanOptions {
-  /** @deprecated Use {@link deleteMessageSeconds} instead. */
+  /** @deprecated Use {@link BanOptions#deleteMessageSeconds} instead. */
  deleteMessageDays?: number;
  deleteMessageSeconds?: number;
  reason?: string;
@@ -5001,7 +5001,7 @@ export interface ClientEvents {
  typingStart: [typing: Typing];
  userUpdate: [oldUser: User | PartialUser, newUser: User];
  voiceStateUpdate: [oldState: VoiceState, newState: VoiceState];
-  /** @deprecated Use {@link webhooksUpdate} instead. */
+  /** @deprecated Use {@link ClientEvents#webhooksUpdate} instead. */
  webhookUpdate: ClientEvents['webhooksUpdate'];
  webhooksUpdate: [channel: TextChannel | NewsChannel | VoiceChannel | ForumChannel | MediaChannel];
  interactionCreate: [interaction: Interaction];
@@ -5061,10 +5061,10 @@ export interface ClientUserEditOptions {
 }

 export interface CloseEvent {
-  /** @deprecated */
+  /** @deprecated Not used anymore since using {@link @discordjs/ws#WebSocketManager} internally */
  wasClean: boolean;
  code: number;
-  /** @deprecated */
+  /** @deprecated Not used anymore since using {@link @discordjs/ws#WebSocketManager} internally */
  reason: string;
 }

@@ -5390,11 +5390,11 @@ export interface FetchGuildScheduledEventSubscribersOptions {
  withMember?: boolean;
 }

-interface FetchInviteOptions extends BaseFetchOptions {
+export interface FetchInviteOptions extends BaseFetchOptions {
  code: string;
 }

-interface FetchInvitesOptions {
+export interface FetchInvitesOptions {
  channelId?: GuildInvitableChannelResolvable;
  cache?: boolean;
 }