feat(website): use tsdoc parameter names wherever possible (#9413)

Co-authored-by: Noel <buechler.noel@outlook.com>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

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: <ExcerptText excerpt={param.parameterTypeExcerpt} model={item.getAssociatedModel()!} />,
 				Optional: param.isOptional ? 'Yes' : 'No',
-				Description: param.tsdocParamBlock ? <TSDoc item={item} tsdoc={param.tsdocParamBlock.content} /> : 'None',
+				Description: param.description ? <TSDoc item={item} tsdoc={param.description} /> : 'None',
 			})),
-		[item],
+		[item, params],
 	);
 
 	return (

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 (
 		<DocumentationSection icon={<VscSymbolParameter size={20} />} padded title="Parameters">
 			<ParameterTable item={item} />

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}`;
 		}

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,
+		};
+	});
+}