mirror of
https://github.com/discordjs/discord.js.git
synced 2024-08-21 03:54:41 +12:00
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>
This commit is contained in:
parent
7d7972d239
commit
516c46117c
4 changed files with 51 additions and 9 deletions
|
@ -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 (
|
||||
|
|
|
@ -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} />
|
||||
|
|
|
@ -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}`;
|
||||
}
|
||||
|
|
|
@ -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,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
|
Loading…
Reference in a new issue