feat(website): show descriptions for @typeParam blocks (#8523)

suneettipirneni · web-flow · commit e475b63f257f · 2022-08-19T10:55:43.000+02:00
diff --git a/packages/builders/src/components/ActionRow.ts b/packages/builders/src/components/ActionRow.ts
@@ -22,6 +22,8 @@ export type AnyComponentBuilder = MessageActionRowComponentBuilder | ModalAction
 
 /**
  * Represents an action row component
+ *
+ * @typeParam T - The types of components this action row holds
  */
 export class ActionRowBuilder<T extends AnyComponentBuilder> extends ComponentBuilder<
 	APIActionRowComponent<APIMessageActionRowComponent | APIModalActionRowComponent>
@@ -56,6 +58,9 @@ export class ActionRowBuilder<T extends AnyComponentBuilder> extends ComponentBu
 		return this;
 	}
 
+	/**
+	 * {@inheritDoc JSONEncodable.toJSON}
+	 */
 	public toJSON(): APIActionRowComponent<ReturnType<T['toJSON']>> {
 		// eslint-disable-next-line @typescript-eslint/consistent-type-assertions
 		return {
diff --git a/packages/builders/src/components/Component.ts b/packages/builders/src/components/Component.ts
@@ -10,6 +10,8 @@ export type AnyAPIActionRowComponent = APIActionRowComponentTypes | APIActionRow
 
 /**
  * Represents a discord component
+ *
+ * @typeParam DataType - The type of internal API data that is stored within the component
  */
 export abstract class ComponentBuilder<
 	DataType extends Partial<APIBaseComponent<ComponentType>> = APIBaseComponent<ComponentType>,
@@ -20,6 +22,9 @@ export abstract class ComponentBuilder<
 	 */
 	public readonly data: Partial<DataType>;
 
+	/**
+	 * {@inheritDoc JSONEncodable.toJSON}
+	 */
 	public abstract toJSON(): AnyAPIActionRowComponent;
 
 	public constructor(data: Partial<DataType>) {
diff --git a/packages/builders/src/components/button/Button.ts b/packages/builders/src/components/button/Button.ts
@@ -85,6 +85,9 @@ export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {
 		return this;
 	}
 
+	/**
+	 * {@inheritDoc JSONEncodable.toJSON}
+	 */
 	public toJSON(): APIButtonComponent {
 		validateRequiredButtonParameters(
 			this.data.style,
diff --git a/packages/builders/src/components/selectMenu/SelectMenu.ts b/packages/builders/src/components/selectMenu/SelectMenu.ts
@@ -116,6 +116,9 @@ export class SelectMenuBuilder extends ComponentBuilder<APISelectMenuComponent>
 		return this;
 	}
 
+	/**
+	 * {@inheritDoc JSONEncodable.toJSON}
+	 */
 	public toJSON(): APISelectMenuComponent {
 		validateRequiredSelectMenuParameters(this.options, this.data.custom_id);
 		// eslint-disable-next-line @typescript-eslint/consistent-type-assertions
diff --git a/packages/builders/src/components/selectMenu/SelectMenuOption.ts b/packages/builders/src/components/selectMenu/SelectMenuOption.ts
@@ -1,4 +1,5 @@
 import type { APIMessageComponentEmoji, APISelectMenuOption } from 'discord-api-types/v10';
+import type { JSONEncodable } from '../../util/jsonEncodable';
 
 import {
 	defaultValidator,
@@ -10,7 +11,7 @@ import {
 /**
  * Represents a option within a select menu component
  */
-export class SelectMenuOptionBuilder {
+export class SelectMenuOptionBuilder implements JSONEncodable<APISelectMenuOption> {
 	public constructor(public data: Partial<APISelectMenuOption> = {}) {}
 
 	/**
@@ -63,6 +64,9 @@ export class SelectMenuOptionBuilder {
 		return this;
 	}
 
+	/**
+	 * {@inheritDoc JSONEncodable.toJSON}
+	 */
 	public toJSON(): APISelectMenuOption {
 		validateRequiredSelectMenuOptionParameters(this.data.label, this.data.value);
 		// eslint-disable-next-line @typescript-eslint/consistent-type-assertions
diff --git a/packages/builders/src/components/textInput/TextInput.ts b/packages/builders/src/components/textInput/TextInput.ts
@@ -10,11 +10,15 @@ import {
 	labelValidator,
 	textInputStyleValidator,
 } from './Assertions';
+import type { Equatable } from '../../util/equatable';
 import { isJSONEncodable, type JSONEncodable } from '../../util/jsonEncodable';
 import { customIdValidator } from '../Assertions';
 import { ComponentBuilder } from '../Component';
 
-export class TextInputBuilder extends ComponentBuilder<APITextInputComponent> {
+export class TextInputBuilder
+	extends ComponentBuilder<APITextInputComponent>
+	implements Equatable<JSONEncodable<APITextInputComponent> | APITextInputComponent>
+{
 	public constructor(data?: APITextInputComponent & { type?: ComponentType.TextInput }) {
 		super({ type: ComponentType.TextInput, ...data });
 	}
@@ -99,6 +103,9 @@ export class TextInputBuilder extends ComponentBuilder<APITextInputComponent> {
 		return this;
 	}
 
+	/**
+	 * {@inheritDoc JSONEncodable.toJSON}
+	 */
 	public toJSON(): APITextInputComponent {
 		validateRequiredParameters(this.data.custom_id, this.data.style, this.data.label);
 		// eslint-disable-next-line @typescript-eslint/consistent-type-assertions
@@ -107,6 +114,9 @@ export class TextInputBuilder extends ComponentBuilder<APITextInputComponent> {
 		} as APITextInputComponent;
 	}
 
+	/**
+	 * {@inheritDoc Equatable.equals}
+	 */
 	public equals(other: JSONEncodable<APITextInputComponent> | APITextInputComponent): boolean {
 		if (isJSONEncodable(other)) {
 			return isEqual(other.toJSON(), this.data);
diff --git a/packages/builders/src/interactions/slashCommands/SlashCommandBuilder.ts b/packages/builders/src/interactions/slashCommands/SlashCommandBuilder.ts
@@ -49,7 +49,7 @@ export class SlashCommandBuilder {
 	 * 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 (SlashCommandBuilder:class).setDefaultMemberPermissions} or {@link (SlashCommandBuilder:class).setDMPermission} instead.
 	 */
 	public readonly default_permission: boolean | undefined = undefined;
 
@@ -89,7 +89,7 @@ export class SlashCommandBuilder {
 	 * @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 (SlashCommandBuilder:class).setDefaultMemberPermissions} or {@link (SlashCommandBuilder:class).setDMPermission} instead.
 	 */
 	public setDefaultPermission(value: boolean) {
 		// Assert the value matches the conditions
diff --git a/packages/builders/src/util/equatable.ts b/packages/builders/src/util/equatable.ts
@@ -1,3 +1,9 @@
+/**
+ * Represents a structure that can be checked against another
+ * given structure for equality
+ *
+ * @typeParam T - The type of object to compare the current object to
+ */
 export interface Equatable<T> {
 	/**
 	 * Whether or not this is equal to another structure
diff --git a/packages/builders/src/util/jsonEncodable.ts b/packages/builders/src/util/jsonEncodable.ts
@@ -1,3 +1,8 @@
+/**
+ * Represents an object capable of representing itself as a JSON object
+ *
+ * @typeParam T - The JSON type corresponding to {@link JSONEncodable.toJSON} outputs.
+ */
 export interface JSONEncodable<T> {
 	/**
 	 * Transforms this object to its JSON format
diff --git a/packages/collection/src/collection.ts b/packages/collection/src/collection.ts
@@ -28,6 +28,9 @@ export interface Collection<K, V> extends Map<K, V> {
 /**
  * A Map with additional utility methods. This is used throughout discord.js rather than Arrays for anything that has
  * an ID, for significantly improved performance and ease-of-use.
+ *
+ * @typeParam K - The key type this collection holds
+ * @typeParam V - The value type this collection holds
  */
 export class Collection<K, V> extends Map<K, V> {
 	/**
diff --git a/packages/website/src/DocModel/TypeParameterMixin.ts b/packages/website/src/DocModel/TypeParameterMixin.ts
@@ -1,6 +1,32 @@
-import type { ApiItem, ApiModel, ApiTypeParameterListMixin } from '@microsoft/api-extractor-model';
+import type { ApiItem, ApiModel, ApiTypeParameterListMixin, TypeParameter } from '@microsoft/api-extractor-model';
 import type { DocItemConstructor } from './DocItem';
-import { generateTypeParamData, TypeParameterData } from '~/util/parse.server';
+import { block, DocBlockJSON } from './comment/CommentBlock';
+import { genToken, TokenDocumentation } from '~/util/parse.server';
+
+export interface TypeParameterData {
+	name: string;
+	constraintTokens: TokenDocumentation[];
+	defaultTokens: TokenDocumentation[];
+	optional: boolean;
+	commentBlock: DocBlockJSON | null;
+}
+
+export function generateTypeParamData(
+	model: ApiModel,
+	typeParam: TypeParameter,
+	parentItem?: ApiItem,
+): TypeParameterData {
+	const constraintTokens = typeParam.constraintExcerpt.spannedTokens.map((token) => genToken(model, token));
+	const defaultTokens = typeParam.defaultTypeExcerpt.spannedTokens.map((token) => genToken(model, token));
+
+	return {
+		name: typeParam.name,
+		constraintTokens,
+		defaultTokens,
+		optional: typeParam.isOptional,
+		commentBlock: typeParam.tsdocTypeParamBlock ? block(typeParam.tsdocTypeParamBlock, model, parentItem) : null,
+	};
+}
 
 export function TypeParameterMixin<TBase extends DocItemConstructor>(Base: TBase) {
 	return class Mixed extends Base {
@@ -10,7 +36,7 @@ export function TypeParameterMixin<TBase extends DocItemConstructor>(Base: TBase
 		public constructor(model: ApiModel, item: ApiItem) {
 			super(model, item);
 			this.typeParameters = (item as ApiTypeParameterListMixin).typeParameters.map((typeParam) =>
-				generateTypeParamData(this.model, typeParam),
+				generateTypeParamData(this.model, typeParam, item.parent),
 			);
 		}
 
diff --git a/packages/website/src/DocModel/comment/LinkTagCommentNode.ts b/packages/website/src/DocModel/comment/LinkTagCommentNode.ts
@@ -14,11 +14,7 @@ export function genToken(
 	ref: DocDeclarationReference,
 	context: ApiItem | null,
 ): LinkTagCodeLink | null {
-	if (!context) {
-		return null;
-	}
-
-	const item = model.resolveDeclarationReference(ref, context).resolvedApiItem ?? null;
+	const item = model.resolveDeclarationReference(ref, context ?? undefined).resolvedApiItem ?? null;
 
 	if (!item) {
 		return null;
@@ -38,8 +34,14 @@ export interface LinkTagCodeLink {
 }
 
 export function linkTagNode(linkNode: DocLinkTag, model: ApiModel, parentItem?: ApiItem): DocLinkTagJSON {
-	const codeDestination =
-		linkNode.codeDestination && parentItem ? genToken(model, linkNode.codeDestination, parentItem) : null;
+	// If we weren't provided a parent object, fallback to the package entrypoint.
+	const packageEntryPoint = linkNode.codeDestination?.importPath
+		? model.getAssociatedPackage()?.findEntryPointsByPath(linkNode.codeDestination.importPath)[0]
+		: null;
+
+	const codeDestination = linkNode.codeDestination
+		? genToken(model, linkNode.codeDestination, parentItem ?? packageEntryPoint ?? null)
+		: null;
 	const text = linkNode.linkText ?? null;
 	const urlDestination = linkNode.urlDestination ?? null;
 
diff --git a/packages/website/src/components/DocContainer.tsx b/packages/website/src/components/DocContainer.tsx
@@ -1,6 +1,6 @@
 import { Group, Stack, Title, Text, Box, MediaQuery, Aside, ScrollArea } from '@mantine/core';
 import { useMediaQuery } from '@mantine/hooks';
-import type { ReactNode } from 'react';
+import { Fragment, ReactNode } from 'react';
 import { VscListSelection, VscSymbolParameter } from 'react-icons/vsc';
 import { PrismAsyncLight as SyntaxHighlighter } from 'react-syntax-highlighter';
 import { vscDarkPlus } from 'react-syntax-highlighter/dist/cjs/styles/prism';
@@ -11,9 +11,10 @@ import { TypeParamTable } from './TypeParamTable';
 import { TSDoc } from './tsdoc/TSDoc';
 import type { DocClass } from '~/DocModel/DocClass';
 import type { DocItem } from '~/DocModel/DocItem';
+import type { TypeParameterData } from '~/DocModel/TypeParameterMixin';
 import type { AnyDocNodeJSON } from '~/DocModel/comment/CommentNode';
 import { generateIcon } from '~/util/icon';
-import type { TokenDocumentation, TypeParameterData } from '~/util/parse.server';
+import type { TokenDocumentation } from '~/util/parse.server';
 
 export interface DocContainerProps {
 	name: string;
@@ -84,10 +85,10 @@ export function DocContainer({
 						</Title>
 						<Text sx={{ wordBreak: 'break-all' }} className="font-mono">
 							{implementsTokens.map((token, idx) => (
-								<>
+								<Fragment key={idx}>
 									<HyperlinkedText tokens={token} />
 									{idx < implementsTokens.length - 1 ? ', ' : ''}
-								</>
+								</Fragment>
 							))}
 						</Text>
 					</Group>
diff --git a/packages/website/src/components/MethodList.tsx b/packages/website/src/components/MethodList.tsx
@@ -1,4 +1,5 @@
 import { Divider, Stack } from '@mantine/core';
+import { Fragment } from 'react';
 import { MethodItem } from './MethodItem';
 import type { DocMethod } from '~/DocModel/DocMethod';
 import type { DocMethodSignature } from '~/DocModel/DocMethodSignature';
@@ -11,13 +12,12 @@ export function MethodList({
 	return (
 		<Stack>
 			{data.map((method) => (
-				<>
-					<MethodItem
-						key={`${method.name}${method.overloadIndex && method.overloadIndex > 1 ? `:${method.overloadIndex}` : ''}`}
-						data={method}
-					/>
+				<Fragment
+					key={`${method.name}${method.overloadIndex && method.overloadIndex > 1 ? `:${method.overloadIndex}` : ''}`}
+				>
+					<MethodItem data={method} />
 					<Divider className="bg-gray-100" size="md" />
-				</>
+				</Fragment>
 			))}
 		</Stack>
 	);
diff --git a/packages/website/src/components/TypeParamTable.tsx b/packages/website/src/components/TypeParamTable.tsx
@@ -1,30 +1,33 @@
-import { Box } from '@mantine/core';
+import { Box, ScrollArea } from '@mantine/core';
 import { HyperlinkedText } from './HyperlinkedText';
 import { Table } from './Table';
-import type { TypeParameterData } from '~/util/parse.server';
+import { TSDoc } from './tsdoc/TSDoc';
+import type { TypeParameterData } from '~/DocModel/TypeParameterMixin';
 
 export function TypeParamTable({ data }: { data: TypeParameterData[] }) {
 	const rows = data.map((typeParam) => ({
 		Name: typeParam.name,
 		Constraints: <HyperlinkedText tokens={typeParam.constraintTokens} />,
 		Optional: typeParam.optional ? 'Yes' : 'No',
 		Default: <HyperlinkedText tokens={typeParam.defaultTokens} />,
-		Description: 'None',
+		Description: typeParam.commentBlock ? <TSDoc node={typeParam.commentBlock} /> : 'None',
 	}));
 
 	const rowElements = {
-		Name: 'font-mono',
-		Constraints: 'font-mono',
-		Default: 'font-mono',
+		Name: 'font-mono whitespace-nowrap',
+		Constraints: 'font-mono whitespace-pre break-normal',
+		Default: 'font-mono whitespace-pre break-normal',
 	};
 
 	return (
 		<Box sx={{ overflowX: 'auto' }}>
-			<Table
-				columns={['Name', 'Constraints', 'Optional', 'Default', 'Description']}
-				rows={rows}
-				columnStyles={rowElements}
-			/>
+			<ScrollArea type="auto">
+				<Table
+					columns={['Name', 'Constraints', 'Optional', 'Default', 'Description']}
+					rows={rows}
+					columnStyles={rowElements}
+				/>
+			</ScrollArea>
 		</Box>
 	);
 }
diff --git a/packages/website/src/components/tsdoc/BlockComment.tsx b/packages/website/src/components/tsdoc/BlockComment.tsx
@@ -52,6 +52,7 @@ export function BlockComment({ children, tagName, index }: BlockCommentProps): J
 			return <DeprecatedBlock>{children}</DeprecatedBlock>;
 		case StandardTags.remarks.tagNameWithUpperCase:
 			return <RemarksBlock>{children}</RemarksBlock>;
+		case StandardTags.typeParam.tagNameWithUpperCase:
 		case StandardTags.param.tagNameWithUpperCase:
 			return <Text>{children}</Text>;
 		default: // TODO: Support more blocks in the future.
diff --git a/packages/website/src/components/tsdoc/TSDoc.tsx b/packages/website/src/components/tsdoc/TSDoc.tsx
@@ -1,7 +1,7 @@
 import { Anchor, Box, Code, Text } from '@mantine/core';
 import { DocNodeKind, StandardTags } from '@microsoft/tsdoc';
 import Link from 'next/link';
-import type { ReactNode } from 'react';
+import { Fragment, ReactNode } from 'react';
 import { PrismAsyncLight as SyntaxHighlighter } from 'react-syntax-highlighter';
 import { vscDarkPlus } from 'react-syntax-highlighter/dist/cjs/styles/prism';
 import { BlockComment } from './BlockComment';
@@ -32,7 +32,7 @@ export function TSDoc({ node }: { node: AnyDocNodeJSON }): JSX.Element {
 					</Text>
 				);
 			case DocNodeKind.SoftBreak:
-				return <></>;
+				return <Fragment key={idx} />;
 			case DocNodeKind.LinkTag: {
 				const { codeDestination, urlDestination, text } = node as DocLinkTagJSON;
 
diff --git a/packages/website/src/util/parse.server.ts b/packages/website/src/util/parse.server.ts

Original file line number	Diff line number	Diff line change
`@@ -85,6 +85,9 @@ export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {`
`85`	`85`	`return this;`
`86`	`86`	`}`
`87`	`87`
	`88`	`+ /**`
	`89`	`+ * {@inheritDoc JSONEncodable.toJSON}`
	`90`	`+ */`
`88`	`91`	`public toJSON(): APIButtonComponent {`
`89`	`92`	`validateRequiredButtonParameters(`
`90`	`93`	`this.data.style,`
Original file line number	Diff line number	Diff line change
`@@ -116,6 +116,9 @@ export class SelectMenuBuilder extends ComponentBuilder<APISelectMenuComponent>`
`116`	`116`	`return this;`
`117`	`117`	`}`
`118`	`118`
	`119`	`+ /**`
	`120`	`+ * {@inheritDoc JSONEncodable.toJSON}`
	`121`	`+ */`
`119`	`122`	`public toJSON(): APISelectMenuComponent {`
`120`	`123`	`validateRequiredSelectMenuParameters(this.options, this.data.custom_id);`
`121`	`124`	`// eslint-disable-next-line @typescript-eslint/consistent-type-assertions`