discordjs/discord.js
2
0
Fork 0
mirror of https://github.com/discordjs/discord.js.git synced 2024-08-21 03:54:41 +12:00
Code Issues Projects Releases Packages Wiki Activity

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

Browse source 
Co-authored-by: Noel <buechler.noel@outlook.com>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
This commit is contained in:
Suneet Tipirneni 2023-04-17 12:44:17 -04:00 committed by GitHub
parent 7d7972d239
commit 516c46117c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 51 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
apps/website/src/components/ParameterTable.tsx
View file

@ -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 (

4
apps/website/src/components/documentation/section/ParametersSection.tsx
View file

@ -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} />

5
apps/website/src/components/model/method/MethodHeader.tsx
View file

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

38
apps/website/src/util/model.ts
View file

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