Nomchy/discord.js
1
0
Fork 0
mirror of https://github.com/discordjs/discord.js.git synced 2026-03-11 00:53:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

feat(website): show descriptions for @typeParam blocks (#8523)

Browse Source
This commit is contained in:
Suneet Tipirneni
2022-08-19 04:55:43 -04:00
committed by GitHub
parent 673262d38c
commit e475b63f25
18 changed files with 126 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
packages/website/src/DocModel/TypeParameterMixin.ts
View File

@@ -1,6 +1,32 @@
import type { ApiItem, ApiModel, ApiTypeParameterListMixin } from '@microsoft/api-extractor-model';
import type { ApiItem, ApiModel, ApiTypeParameterListMixin, TypeParameter } from '@microsoft/api-extractor-model';
import type { DocItemConstructor } from './DocItem';
import { generateTypeParamData, TypeParameterData } from '~/util/parse.server';
import { block, DocBlockJSON } from './comment/CommentBlock';
import { genToken, TokenDocumentation } from '~/util/parse.server';
export interface TypeParameterData {
name: string;
constraintTokens: TokenDocumentation[];
defaultTokens: TokenDocumentation[];
optional: boolean;
commentBlock: DocBlockJSON | null;
}
export function generateTypeParamData(
model: ApiModel,
typeParam: TypeParameter,
parentItem?: ApiItem,
): TypeParameterData {
const constraintTokens = typeParam.constraintExcerpt.spannedTokens.map((token) => genToken(model, token));
const defaultTokens = typeParam.defaultTypeExcerpt.spannedTokens.map((token) => genToken(model, token));
return {
name: typeParam.name,
constraintTokens,
defaultTokens,
optional: typeParam.isOptional,
commentBlock: typeParam.tsdocTypeParamBlock ? block(typeParam.tsdocTypeParamBlock, model, parentItem) : null,
};
}
export function TypeParameterMixin<TBase extends DocItemConstructor>(Base: TBase) {
return class Mixed extends Base {
@@ -10,7 +36,7 @@ export function TypeParameterMixin<TBase extends DocItemConstructor>(Base: TBase
public constructor(model: ApiModel, item: ApiItem) {
super(model, item);
this.typeParameters = (item as ApiTypeParameterListMixin).typeParameters.map((typeParam) =>
generateTypeParamData(this.model, typeParam),
generateTypeParamData(this.model, typeParam, item.parent),
);
}

16
packages/website/src/DocModel/comment/LinkTagCommentNode.ts
View File

@@ -14,11 +14,7 @@ export function genToken(
ref: DocDeclarationReference,
context: ApiItem | null,
): LinkTagCodeLink | null {
if (!context) {
return null;
}
const item = model.resolveDeclarationReference(ref, context).resolvedApiItem ?? null;
const item = model.resolveDeclarationReference(ref, context ?? undefined).resolvedApiItem ?? null;
if (!item) {
return null;
@@ -38,8 +34,14 @@ export interface LinkTagCodeLink {
}
export function linkTagNode(linkNode: DocLinkTag, model: ApiModel, parentItem?: ApiItem): DocLinkTagJSON {
const codeDestination =
linkNode.codeDestination && parentItem ? genToken(model, linkNode.codeDestination, parentItem) : null;
// If we weren't provided a parent object, fallback to the package entrypoint.
const packageEntryPoint = linkNode.codeDestination?.importPath
? model.getAssociatedPackage()?.findEntryPointsByPath(linkNode.codeDestination.importPath)[0]
: null;
const codeDestination = linkNode.codeDestination
? genToken(model, linkNode.codeDestination, parentItem ?? packageEntryPoint ?? null)
: null;
const text = linkNode.linkText ?? null;
const urlDestination = linkNode.urlDestination ?? null;

9
packages/website/src/components/DocContainer.tsx
View File

@@ -1,6 +1,6 @@
import { Group, Stack, Title, Text, Box, MediaQuery, Aside, ScrollArea } from '@mantine/core';
import { useMediaQuery } from '@mantine/hooks';
import type { ReactNode } from 'react';
import { Fragment, ReactNode } from 'react';
import { VscListSelection, VscSymbolParameter } from 'react-icons/vsc';
import { PrismAsyncLight as SyntaxHighlighter } from 'react-syntax-highlighter';
import { vscDarkPlus } from 'react-syntax-highlighter/dist/cjs/styles/prism';
@@ -11,9 +11,10 @@ import { TypeParamTable } from './TypeParamTable';
import { TSDoc } from './tsdoc/TSDoc';
import type { DocClass } from '~/DocModel/DocClass';
import type { DocItem } from '~/DocModel/DocItem';
import type { TypeParameterData } from '~/DocModel/TypeParameterMixin';
import type { AnyDocNodeJSON } from '~/DocModel/comment/CommentNode';
import { generateIcon } from '~/util/icon';
import type { TokenDocumentation, TypeParameterData } from '~/util/parse.server';
import type { TokenDocumentation } from '~/util/parse.server';
export interface DocContainerProps {
name: string;
@@ -84,10 +85,10 @@ export function DocContainer({
</Title>
<Text sx={{ wordBreak: 'break-all' }} className="font-mono">
{implementsTokens.map((token, idx) => (
<>
<Fragment key={idx}>
<HyperlinkedText tokens={token} />
{idx < implementsTokens.length - 1 ? ', ' : ''}
</>
</Fragment>
))}
</Text>
</Group>

12
packages/website/src/components/MethodList.tsx
View File

@@ -1,4 +1,5 @@
import { Divider, Stack } from '@mantine/core';
import { Fragment } from 'react';
import { MethodItem } from './MethodItem';
import type { DocMethod } from '~/DocModel/DocMethod';
import type { DocMethodSignature } from '~/DocModel/DocMethodSignature';
@@ -11,13 +12,12 @@ export function MethodList({
return (
<Stack>
{data.map((method) => (
<>
<MethodItem
key={`${method.name}${method.overloadIndex && method.overloadIndex > 1 ? `:${method.overloadIndex}` : ''}`}
data={method}
/>
<Fragment
key={`${method.name}${method.overloadIndex && method.overloadIndex > 1 ? `:${method.overloadIndex}` : ''}`}
>
<MethodItem data={method} />
<Divider className="bg-gray-100" size="md" />
</>
</Fragment>
))}
</Stack>
);

25
packages/website/src/components/TypeParamTable.tsx
View File

@@ -1,7 +1,8 @@
import { Box } from '@mantine/core';
import { Box, ScrollArea } from '@mantine/core';
import { HyperlinkedText } from './HyperlinkedText';
import { Table } from './Table';
import type { TypeParameterData } from '~/util/parse.server';
import { TSDoc } from './tsdoc/TSDoc';
import type { TypeParameterData } from '~/DocModel/TypeParameterMixin';
export function TypeParamTable({ data }: { data: TypeParameterData[] }) {
const rows = data.map((typeParam) => ({
@@ -9,22 +10,24 @@ export function TypeParamTable({ data }: { data: TypeParameterData[] }) {
Constraints: <HyperlinkedText tokens={typeParam.constraintTokens} />,
Optional: typeParam.optional ? 'Yes' : 'No',
Default: <HyperlinkedText tokens={typeParam.defaultTokens} />,
Description: 'None',
Description: typeParam.commentBlock ? <TSDoc node={typeParam.commentBlock} /> : 'None',
}));
const rowElements = {
Name: 'font-mono',
Constraints: 'font-mono',
Default: 'font-mono',
Name: 'font-mono whitespace-nowrap',
Constraints: 'font-mono whitespace-pre break-normal',
Default: 'font-mono whitespace-pre break-normal',
};
return (
<Box sx={{ overflowX: 'auto' }}>
<Table
columns={['Name', 'Constraints', 'Optional', 'Default', 'Description']}
rows={rows}
columnStyles={rowElements}
/>
<ScrollArea type="auto">
<Table
columns={['Name', 'Constraints', 'Optional', 'Default', 'Description']}
rows={rows}
columnStyles={rowElements}
/>
</ScrollArea>
</Box>
);
}

1
packages/website/src/components/tsdoc/BlockComment.tsx
View File

@@ -52,6 +52,7 @@ export function BlockComment({ children, tagName, index }: BlockCommentProps): J
return <DeprecatedBlock>{children}</DeprecatedBlock>;
case StandardTags.remarks.tagNameWithUpperCase:
return <RemarksBlock>{children}</RemarksBlock>;
case StandardTags.typeParam.tagNameWithUpperCase:
case StandardTags.param.tagNameWithUpperCase:
return <Text>{children}</Text>;
default: // TODO: Support more blocks in the future.

4
packages/website/src/components/tsdoc/TSDoc.tsx
View File

@@ -1,7 +1,7 @@
import { Anchor, Box, Code, Text } from '@mantine/core';
import { DocNodeKind, StandardTags } from '@microsoft/tsdoc';
import Link from 'next/link';
import type { ReactNode } from 'react';
import { Fragment, ReactNode } from 'react';
import { PrismAsyncLight as SyntaxHighlighter } from 'react-syntax-highlighter';
import { vscDarkPlus } from 'react-syntax-highlighter/dist/cjs/styles/prism';
import { BlockComment } from './BlockComment';
@@ -32,7 +32,7 @@ export function TSDoc({ node }: { node: AnyDocNodeJSON }): JSX.Element {
</Text>
);
case DocNodeKind.SoftBreak:
return <></>;
return <Fragment key={idx} />;
case DocNodeKind.LinkTag: {
const { codeDestination, urlDestination, text } = node as DocLinkTagJSON;

37
packages/website/src/util/parse.server.ts
View File

@@ -10,7 +10,6 @@ import {
type ApiPropertyItem,
type ExcerptToken,
type Parameter,
type TypeParameter,
ApiFunction,
} from '@microsoft/api-extractor-model';
import type { DocNode, DocParagraph, DocPlainText } from '@microsoft/tsdoc';
@@ -25,7 +24,7 @@ export function findPackage(model: ApiModel, name: string): ApiPackage | undefin
}
export function generatePath(items: readonly ApiItem[]) {
let path = '/docs/main/packages/';
let path = '/docs/main/packages';
for (const item of items) {
switch (item.kind) {
case ApiItemKind.Model:
@@ -33,17 +32,24 @@ export function generatePath(items: readonly ApiItem[]) {
case ApiItemKind.EnumMember:
break;
case ApiItemKind.Package:
path += `${item.displayName}/`;
path += `/${item.displayName}`;
break;
case ApiItemKind.Function:
// eslint-disable-next-line no-case-declarations
const functionItem = item as ApiFunction;
path += `${functionItem.displayName}${
path += `/${functionItem.displayName}${
functionItem.overloadIndex && functionItem.overloadIndex > 1 ? `:${functionItem.overloadIndex}` : ''
}/`;
}`;
break;
case ApiItemKind.Property:
case ApiItemKind.Method:
case ApiItemKind.MethodSignature:
case ApiItemKind.PropertySignature:
// TODO: Take overloads into account
path += `#${item.displayName}`;
break;
default:
path += `${item.displayName}/`;
path += `/${item.displayName}`;
}
}
@@ -213,22 +219,3 @@ export function getMembers(pkg: ApiPackage) {
overloadIndex: member.kind === 'Function' ? (member as ApiFunction).overloadIndex : null,
}));
}
export interface TypeParameterData {
name: string;
constraintTokens: TokenDocumentation[];
defaultTokens: TokenDocumentation[];
optional: boolean;
}
export function generateTypeParamData(model: ApiModel, typeParam: TypeParameter): TypeParameterData {
const constraintTokens = typeParam.constraintExcerpt.spannedTokens.map((token) => genToken(model, token));
const defaultTokens = typeParam.defaultTypeExcerpt.spannedTokens.map((token) => genToken(model, token));
return {
name: typeParam.name,
constraintTokens,
defaultTokens,
optional: typeParam.isOptional,
};
}