From 7f415a2502bf7ce2025dbcfed9017b0635a19966 Mon Sep 17 00:00:00 2001 From: Suneet Tipirneni <77477100+suneettipirneni@users.noreply.github.com> Date: Thu, 18 Aug 2022 12:38:27 -0400 Subject: [PATCH] feat(website): show parameter descriptions (#8519) Co-authored-by: Noel --- packages/builders/src/messages/embed/Embed.ts | 61 ++++++++++++++++++- .../src/DocModel/comment/ParamBlock.ts | 14 +++++ .../website/src/DocModel/comment/index.ts | 4 ++ .../website/src/components/DocContainer.tsx | 2 +- .../website/src/components/ParameterTable.tsx | 15 +++-- .../src/components/tsdoc/BlockComment.tsx | 8 ++- .../website/src/components/tsdoc/TSDoc.tsx | 4 +- packages/website/src/util/parse.server.ts | 4 ++ 8 files changed, 98 insertions(+), 14 deletions(-) create mode 100644 packages/website/src/DocModel/comment/ParamBlock.ts diff --git a/packages/builders/src/messages/embed/Embed.ts b/packages/builders/src/messages/embed/Embed.ts index d3221f9201c8..5907d68f69d6 100644 --- a/packages/builders/src/messages/embed/Embed.ts +++ b/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) { diff --git a/packages/website/src/DocModel/comment/ParamBlock.ts b/packages/website/src/DocModel/comment/ParamBlock.ts new file mode 100644 index 000000000000..e54ba882704f --- /dev/null +++ b/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, + }; +} diff --git a/packages/website/src/DocModel/comment/index.ts b/packages/website/src/DocModel/comment/index.ts index a60a46cafb6d..a151f0f7a1ea 100644 --- a/packages/website/src/DocModel/comment/index.ts +++ b/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: diff --git a/packages/website/src/components/DocContainer.tsx b/packages/website/src/components/DocContainer.tsx index 5b42864176a3..e20af04ab094 100644 --- a/packages/website/src/components/DocContainer.tsx +++ b/packages/website/src/components/DocContainer.tsx @@ -43,7 +43,7 @@ export function DocContainer({ return ( - + <Group> {generateIcon(kind)} diff --git a/packages/website/src/components/ParameterTable.tsx b/packages/website/src/components/ParameterTable.tsx index 859396ffcce4..a8718b0b2d8a 100644 --- a/packages/website/src/components/ParameterTable.tsx +++ b/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', - Type: 'font-mono', + Name: 'font-mono whitespace-nowrap', + Type: 'font-mono whitespace-pre-wrap break-normal', }; return ( - <Box sx={{ overflowX: 'auto' }}> - <Table columns={['Name', 'Type', 'Optional', 'Description']} rows={rows} columnStyles={columnStyles} /> + <Box> + <ScrollArea type="auto"> + <Table columns={['Name', 'Type', 'Optional', 'Description']} rows={rows} columnStyles={columnStyles} /> + </ScrollArea> </Box> ); } diff --git a/packages/website/src/components/tsdoc/BlockComment.tsx b/packages/website/src/components/tsdoc/BlockComment.tsx index 467405445dc8..a89a3bf3bafa 100644 --- a/packages/website/src/components/tsdoc/BlockComment.tsx +++ b/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} {children} ); @@ -52,7 +52,9 @@ export function BlockComment({ children, tagName, index }: BlockCommentProps): J return {children}; case StandardTags.remarks.tagNameWithUpperCase: return {children}; + case StandardTags.param.tagNameWithUpperCase: + return {children}; default: // TODO: Support more blocks in the future. - return <>; + return <>{children}; } } diff --git a/packages/website/src/components/tsdoc/TSDoc.tsx b/packages/website/src/components/tsdoc/TSDoc.tsx index 692bea4cff49..4df2beba7af1 100644 --- a/packages/website/src/components/tsdoc/TSDoc.tsx +++ b/packages/website/src/components/tsdoc/TSDoc.tsx @@ -81,6 +81,7 @@ export function TSDoc({ node }: { node: AnyDocNodeJSON }): JSX.Element { ); } + 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
{comment.customBlocks.map((node, idx) => createNode(node, idx))}
; + return
{comment.customBlocks.map((node, idx) => createNode(node, idx))}
; } default: + console.log(`Captured unknown node kind: ${node.kind}`); break; } diff --git a/packages/website/src/util/parse.server.ts b/packages/website/src/util/parse.server.ts index 67f2b7dc658f..8b39289ba90d 100644 --- a/packages/website/src/util/parse.server.ts +++ b/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, }; }