diff --git a/apps/website/src/components/ParameterTable.tsx b/apps/website/src/components/ParameterTable.tsx index e3ed95115..50cc9eb4c 100644 --- a/apps/website/src/components/ParameterTable.tsx +++ b/apps/website/src/components/ParameterTable.tsx @@ -1,24 +1,27 @@ -import type { ApiParameterListMixin } from '@microsoft/api-extractor-model'; +import type { ApiDocumentedItem, ApiParameterListMixin } from '@microsoft/api-extractor-model'; import { useMemo } from 'react'; import { ExcerptText } from './ExcerptText'; import { Table } from './Table'; import { TSDoc } from './documentation/tsdoc/TSDoc'; +import { resolveParameters } from '~/util/model'; const columnStyles = { Name: 'font-mono whitespace-nowrap', Type: 'font-mono whitespace-pre-wrap break-normal', }; -export function ParameterTable({ item }: { item: ApiParameterListMixin }) { +export function ParameterTable({ item }: { item: ApiDocumentedItem & ApiParameterListMixin }) { + const params = resolveParameters(item); + const rows = useMemo( () => - item.parameters.map((param) => ({ + params.map((param) => ({ Name: param.name, Type: , Optional: param.isOptional ? 'Yes' : 'No', - Description: param.tsdocParamBlock ? : 'None', + Description: param.description ? : 'None', })), - [item], + [item, params], ); return ( diff --git a/apps/website/src/components/documentation/section/ParametersSection.tsx b/apps/website/src/components/documentation/section/ParametersSection.tsx index 183fe8c71..a34d98705 100644 --- a/apps/website/src/components/documentation/section/ParametersSection.tsx +++ b/apps/website/src/components/documentation/section/ParametersSection.tsx @@ -1,9 +1,9 @@ -import type { ApiParameterListMixin } from '@microsoft/api-extractor-model'; +import type { ApiDocumentedItem, ApiParameterListMixin } from '@microsoft/api-extractor-model'; import { VscSymbolParameter } from '@react-icons/all-files/vsc/VscSymbolParameter'; import { ParameterTable } from '../../ParameterTable'; import { DocumentationSection } from './DocumentationSection'; -export function ParameterSection({ item }: { item: ApiParameterListMixin }) { +export function ParameterSection({ item }: { item: ApiDocumentedItem & ApiParameterListMixin }) { return ( } padded title="Parameters"> diff --git a/apps/website/src/components/model/method/MethodHeader.tsx b/apps/website/src/components/model/method/MethodHeader.tsx index ec549476b..f6531b5fb 100644 --- a/apps/website/src/components/model/method/MethodHeader.tsx +++ b/apps/website/src/components/model/method/MethodHeader.tsx @@ -3,9 +3,12 @@ import { ApiItemKind } from '@microsoft/api-extractor-model'; import { useMemo } from 'react'; import { Anchor } from '~/components/Anchor'; import { ExcerptText } from '~/components/ExcerptText'; +import { resolveParameters } from '~/util/model'; function getShorthandName(method: ApiMethod | ApiMethodSignature) { - return `${method.name}${method.isOptional ? '?' : ''}(${method.parameters.reduce((prev, cur, index) => { + const params = resolveParameters(method); + + return `${method.name}${method.isOptional ? '?' : ''}(${params.reduce((prev, cur, index) => { if (index === 0) { return `${prev}${cur.isOptional ? `${cur.name}?` : cur.name}`; } diff --git a/apps/website/src/util/model.ts b/apps/website/src/util/model.ts index 0fcdcf479..abf82196c 100644 --- a/apps/website/src/util/model.ts +++ b/apps/website/src/util/model.ts @@ -1,4 +1,11 @@ -import type { ApiEntryPoint, ApiModel } from '@microsoft/api-extractor-model'; +import type { + ApiDocumentedItem, + ApiEntryPoint, + ApiModel, + ApiParameterListMixin, + Excerpt, +} from '@microsoft/api-extractor-model'; +import type { DocSection } from '@microsoft/tsdoc'; export function findMemberByKey(model: ApiModel, packageName: string, containerKey: string) { const pkg = model.tryGetPackageByName(`@discordjs/${packageName}`)!; @@ -13,3 +20,32 @@ export function findMember(model: ApiModel, packageName: string, memberName: str const pkg = model.tryGetPackageByName(`@discordjs/${packageName}`)!; return pkg.entryPoints[0]?.findMembersByName(memberName)[0]; } + +interface ResolvedParameter { + description?: DocSection | undefined; + isOptional: boolean; + name: string; + parameterTypeExcerpt: Excerpt; +} + +/** + * This takes an api item with a parameter list and resolves the names and descriptions of all the parameters. + * + * @remarks + * This is different from accessing `Parameter#name` or `Parameter.tsdocBlockComment` as this method cross-references the associated tsdoc + * parameter names and descriptions and uses them as a higher precedence to the source code. + * @param item - The api item to resolve parameter data for + * @returns An array of parameters + */ +export function resolveParameters(item: ApiDocumentedItem & ApiParameterListMixin): ResolvedParameter[] { + return item.parameters.map((param, idx) => { + const tsdocAnalog = item.tsdocComment?.params.blocks[idx]; + + return { + name: param.tsdocParamBlock?.parameterName ?? tsdocAnalog?.parameterName ?? param.name, + description: param.tsdocParamBlock?.content ?? tsdocAnalog?.content, + isOptional: param.isOptional, + parameterTypeExcerpt: param.parameterTypeExcerpt, + }; + }); +}