feat(website): show parameter descriptions (#8519)

Co-authored-by: Noel <buechler.noel@outlook.com>

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

@@ -52,7 +52,29 @@ export class EmbedBuilder {
 	}
 
 	/**
-	 * Adds fields to the embed (max 25)
+	 * Appends fields to the embed
+	 *
+	 * @remarks
+	 * This method accepts either an array of fields or a variable number of field parameters.
+	 * The maximum amount of fields that can be added is 25.
+	 *
+	 * @example
+	 * Using an array
+	 * ```ts
+	 * const fields: APIEmbedField[] = ...;
+	 * const embed = new EmbedBuilder()
+	 * 	.addFields(fields);
+	 * ```
+	 *
+	 * @example
+	 * Using rest parameters (variadic)
+	 * ```ts
+	 * const embed = new EmbedBuilder()
+	 * 	.addFields(
+	 * 		{ name: 'Field 1', value: 'Value 1' },
+	 * 		{ name: 'Field 2', value: 'Value 2' },
+	 * 	);
+	 * ```
 	 *
 	 * @param fields The fields to add
 	 */
@@ -70,7 +92,33 @@ export class EmbedBuilder {
 	}
 
 	/**
-	 * Removes, replaces, or inserts fields in the embed (max 25)
+	 * Removes, replaces, or inserts fields in the embed.
+	 *
+	 * @remarks
+	 * This method behaves similarly
+	 * to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice | Array.prototype.splice}.
+	 * The maximum amount of fields that can be added is 25.
+	 *
+	 * It's useful for modifying and adjusting order of the already-existing fields of an embed.
+	 *
+	 * @example
+	 * Remove the first field
+	 * ```ts
+	 * embed.spliceFields(0, 1);
+	 * ```
+	 *
+	 * @example
+	 * Remove the first n fields
+	 * ```ts
+	 * const n = 4
+	 * embed.spliceFields(0, n);
+	 * ```
+	 *
+	 * @example
+	 * Remove the last field
+	 * ```ts
+	 * embed.spliceFields(-1, 1);
+	 * ```
 	 *
 	 * @param index The index to start at
 	 * @param deleteCount The number of fields to remove
@@ -88,7 +136,14 @@ export class EmbedBuilder {
 	}
 
 	/**
-	 * Sets the embed's fields (max 25).
+	 * Sets the embed's fields
+	 *
+	 * @remarks
+	 * This method is an alias for {@link EmbedBuilder.spliceFields}. More specifically,
+	 * it splices the entire array of fields, replacing them with the provided fields.
+	 *
+	 * You can set a maximum of 25 fields.
+	 *
 	 * @param fields The fields to set
 	 */
 	public setFields(...fields: RestOrArray<APIEmbedField>) {

packages/website/src/DocModel/comment/ParamBlock.ts

@@ -0,0 +1,14 @@
+import type { ApiItem, ApiModel } from '@microsoft/api-extractor-model';
+import type { DocParamBlock } from '@microsoft/tsdoc';
+import { block, DocBlockJSON } from './CommentBlock';
+
+export interface DocParamBlockJSON extends DocBlockJSON {
+	name: string;
+}
+
+export function paramBlock(paramBlock: DocParamBlock, model: ApiModel, parentItem?: ApiItem): DocParamBlockJSON {
+	return {
+		...block(paramBlock, model, parentItem),
+		name: paramBlock.parameterName,
+	};
+}

packages/website/src/DocModel/comment/index.ts

@@ -9,6 +9,7 @@ import {
 	type DocBlock,
 	DocComment,
 	DocCodeSpan,
+	DocParamBlock,
 } from '@microsoft/tsdoc';
 import { block } from './CommentBlock';
 import { codeSpan } from './CommentCodeSpan';
@@ -17,6 +18,7 @@ import { node as _node } from './CommentNode';
 import { nodeContainer } from './CommentNodeContainer';
 import { fencedCode } from './FencedCodeCommentNode';
 import { linkTagNode } from './LinkTagCommentNode';
+import { paramBlock } from './ParamBlock';
 import { plainTextNode } from './PlainTextCommentNode';
 import { comment } from './RootComment';
 
@@ -35,6 +37,8 @@ export function createCommentNode(node: DocNode, model: ApiModel, parentItem?: A
 			return codeSpan(node as DocCodeSpan);
 		case DocNodeKind.Block:
 			return block(node as DocBlock, model, parentItem);
+		case DocNodeKind.ParamBlock:
+			return paramBlock(node as DocParamBlock, model, parentItem);
 		case DocNodeKind.Comment:
 			return comment(node as DocComment, model, parentItem);
 		default:

packages/website/src/components/DocContainer.tsx

@@ -43,7 +43,7 @@ export function DocContainer({
 
 	return (
 		<Group>
-			<Stack sx={{ flexGrow: 1 }}>
+			<Stack sx={{ flexGrow: 1, maxWidth: '100%' }}>
 				<Title sx={{ wordBreak: 'break-all' }} order={2} ml="xs">
 					<Group>
 						{generateIcon(kind)}

packages/website/src/components/ParameterTable.tsx

@@ -1,6 +1,7 @@
-import { Box } from '@mantine/core';
+import { Box, ScrollArea } from '@mantine/core';
 import { HyperlinkedText } from './HyperlinkedText';
 import { Table } from './Table';
+import { TSDoc } from './tsdoc/TSDoc';
 import type { ParameterDocumentation } from '~/util/parse.server';
 
 export function ParameterTable({ data }: { data: ParameterDocumentation[] }) {
@@ -8,17 +9,19 @@ export function ParameterTable({ data }: { data: ParameterDocumentation[] }) {
 		Name: param.name,
 		Type: <HyperlinkedText tokens={param.tokens} />,
 		Optional: param.isOptional ? 'Yes' : 'No',
-		Description: 'None',
+		Description: param.paramCommentBlock ? <TSDoc node={param.paramCommentBlock} /> : 'None',
 	}));
 
 	const columnStyles = {
-		Name: 'font-mono',
+		Name: 'font-mono whitespace-nowrap',
-		Type: 'font-mono',
+		Type: 'font-mono whitespace-pre-wrap break-normal',
 	};
 
 	return (
-		<Box sx={{ overflowX: 'auto' }}>
+		<Box>
-			<Table columns={['Name', 'Type', 'Optional', 'Description']} rows={rows} columnStyles={columnStyles} />
+			<ScrollArea type="auto">
+				<Table columns={['Name', 'Type', 'Optional', 'Description']} rows={rows} columnStyles={columnStyles} />
+			</ScrollArea>
 		</Box>
 	);
 }

packages/website/src/components/tsdoc/BlockComment.tsx

@@ -1,4 +1,4 @@
-import { Alert, Box, Title } from '@mantine/core';
+import { Alert, Box, Title, Text } from '@mantine/core';
 import { StandardTags } from '@microsoft/tsdoc';
 import type { ReactNode } from 'react';
 import { VscWarning } from 'react-icons/vsc';
@@ -11,7 +11,7 @@ export interface BlockProps {
 export function Block({ children, title }: BlockProps) {
 	return (
 		<Box>
-			<Title order={3}>{title}</Title>
+			<Title order={5}>{title}</Title>
 			{children}
 		</Box>
 	);
@@ -52,7 +52,9 @@ export function BlockComment({ children, tagName, index }: BlockCommentProps): J
 			return <DeprecatedBlock>{children}</DeprecatedBlock>;
 		case StandardTags.remarks.tagNameWithUpperCase:
 			return <RemarksBlock>{children}</RemarksBlock>;
+		case StandardTags.param.tagNameWithUpperCase:
+			return <Text>{children}</Text>;
 		default: // TODO: Support more blocks in the future.
-			return <></>;
+			return <>{children}</>;
 	}
 }

packages/website/src/components/tsdoc/TSDoc.tsx

@@ -81,6 +81,7 @@ export function TSDoc({ node }: { node: AnyDocNodeJSON }): JSX.Element {
 					</SyntaxHighlighter>
 				);
 			}
+			case DocNodeKind.ParamBlock:
 			case DocNodeKind.Block: {
 				const { tag } = node as DocBlockJSON;
 
@@ -103,9 +104,10 @@ export function TSDoc({ node }: { node: AnyDocNodeJSON }): JSX.Element {
 					(block) => block.tag.tagName.toUpperCase() === StandardTags.example.tagNameWithUpperCase,
 				).length;
 
-				return <div>{comment.customBlocks.map((node, idx) => createNode(node, idx))}</div>;
+				return <div key={idx}>{comment.customBlocks.map((node, idx) => createNode(node, idx))}</div>;
 			}
 			default:
+				console.log(`Captured unknown node kind: ${node.kind}`);
 				break;
 		}
 

packages/website/src/util/parse.server.ts

@@ -15,6 +15,8 @@ import {
 } from '@microsoft/api-extractor-model';
 import type { DocNode, DocParagraph, DocPlainText } from '@microsoft/tsdoc';
 import { Meaning, ModuleSource } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';
+import { createCommentNode } from '~/DocModel/comment';
+import type { DocBlockJSON } from '~/DocModel/comment/CommentBlock';
 
 export function findPackage(model: ApiModel, name: string): ApiPackage | undefined {
 	return (model.findMembersByName(name)[0] ?? model.findMembersByName(`@discordjs/${name}`)[0]) as
@@ -142,6 +144,7 @@ export interface ParameterDocumentation {
 	name: string;
 	isOptional: boolean;
 	tokens: TokenDocumentation[];
+	paramCommentBlock: DocBlockJSON | null;
 }
 
 function createDapiTypesURL(meaning: Meaning, name: string) {
@@ -197,6 +200,7 @@ export function genParameter(model: ApiModel, param: Parameter): ParameterDocume
 		name: param.name,
 		isOptional: param.isOptional,
 		tokens: param.parameterTypeExcerpt.spannedTokens.map((token) => genToken(model, token)),
+		paramCommentBlock: param.tsdocParamBlock ? (createCommentNode(param.tsdocParamBlock, model) as DocBlockJSON) : null,
 	};
 }