build: package api-extractor and -model (#9920)

* fix(ExceptText): don't display import("d..-types/v10"). in return type

* Squashed 'packages/api-extractor-model/' content from commit 39ecb196c

git-subtree-dir: packages/api-extractor-model
git-subtree-split: 39ecb196ca210bdf84ba6c9cadb1bb93571849d7

* Squashed 'packages/api-extractor/' content from commit 341ad6c51

git-subtree-dir: packages/api-extractor
git-subtree-split: 341ad6c51b01656d4f73b74ad4bdb3095f9262c4

* feat(api-extractor): add api-extractor and -model

* fix: package.json docs script

* fix(SourcLink): use <> instead of function syntax

* fix: make packages private

* fix: rest params showing in docs, added labels

* fix: missed two files

* fix: cpy-cli & pnpm-lock

* fix: increase icon size

* fix: icon size again
This commit is contained in:
Qjuh
2023-11-07 21:53:36 +01:00
committed by GitHub
parent 95c0b1a59f
commit 5c0fad3b2d
251 changed files with 36017 additions and 296 deletions

View File

@@ -1,5 +1,5 @@
import type { ApiDocumentedItem } from '@microsoft/api-extractor-model';
import { ApiAbstractMixin, ApiProtectedMixin, ApiReadonlyMixin, ApiStaticMixin } from '@microsoft/api-extractor-model';
import type { ApiDocumentedItem } from '@discordjs/api-extractor-model';
import { ApiAbstractMixin, ApiProtectedMixin, ApiReadonlyMixin, ApiStaticMixin } from '@discordjs/api-extractor-model';
import type { PropsWithChildren } from 'react';
export enum BadgeColor {

View File

@@ -1,6 +1,6 @@
'use client';
import type { ApiItemKind } from '@microsoft/api-extractor-model';
import type { ApiItemKind } from '@discordjs/api-extractor-model';
import { VscArrowRight } from '@react-icons/all-files/vsc/VscArrowRight';
import { VscSymbolClass } from '@react-icons/all-files/vsc/VscSymbolClass';
import { VscSymbolEnum } from '@react-icons/all-files/vsc/VscSymbolEnum';

View File

@@ -1,5 +1,6 @@
import type { ReactNode } from 'react';
import { Anchor } from './Anchor';
import { SourceLink } from './documentation/SourceLink';
export interface CodeListingProps {
/**
@@ -14,15 +15,26 @@ export interface CodeListingProps {
* The href of this heading.
*/
readonly href?: string | undefined;
/**
* The line in the source code where this part is declared
*/
readonly sourceLine?: number | undefined;
/**
* The URL of the source code of this code part
*/
readonly sourceURL?: string | undefined;
}
export function CodeHeading({ href, className, children }: CodeListingProps) {
export function CodeHeading({ href, className, children, sourceURL, sourceLine }: CodeListingProps) {
return (
<div
className={`flex flex-row flex-wrap place-items-center gap-1 break-all font-mono text-lg font-bold ${className}`}
>
{href ? <Anchor href={href} /> : null}
{children}
<div className="flex flex-row place-items-center justify-between gap-1">
<div
className={`flex flex-row flex-wrap place-items-center gap-1 break-all font-mono text-lg font-bold ${className}`}
>
{href ? <Anchor href={href} /> : null}
{children}
</div>
{sourceURL ? <SourceLink className="text-2xl" sourceLine={sourceLine} sourceURL={sourceURL} /> : null}
</div>
);
}

View File

@@ -1,5 +1,5 @@
import type { ApiModel, Excerpt } from '@microsoft/api-extractor-model';
import { ExcerptTokenKind } from '@microsoft/api-extractor-model';
import type { ApiModel, Excerpt } from '@discordjs/api-extractor-model';
import { ExcerptTokenKind } from '@discordjs/api-extractor-model';
import { DISCORD_API_TYPES_DOCS_URL } from '~/util/constants';
import { ItemLink } from './ItemLink';
import { resolveItemURI } from './documentation/util';
@@ -60,7 +60,7 @@ export function ExcerptText({ model, excerpt }: ExcerptTextProps) {
);
}
return token.text;
return token.text.replace(/import\("discord-api-types(?:\/v\d+)?"\)\./, '');
})}
</span>
);

View File

@@ -1,4 +1,4 @@
import type { ApiDeclaredItem } from '@microsoft/api-extractor-model';
import type { ApiDeclaredItem } from '@discordjs/api-extractor-model';
import { ItemLink } from './ItemLink';
import { resolveItemURI } from './documentation/util';

View File

@@ -1,4 +1,4 @@
import type { ApiDocumentedItem, ApiParameterListMixin } from '@microsoft/api-extractor-model';
import type { ApiDocumentedItem, ApiParameterListMixin } from '@discordjs/api-extractor-model';
import { useMemo } from 'react';
import { resolveParameters } from '~/util/model';
import { ExcerptText } from './ExcerptText';
@@ -16,7 +16,7 @@ export function ParameterTable({ item }: { readonly item: ApiDocumentedItem & Ap
const rows = useMemo(
() =>
params.map((param) => ({
Name: param.name,
Name: param.isRest ? `...${param.name}` : param.name,
Type: <ExcerptText excerpt={param.parameterTypeExcerpt} model={item.getAssociatedModel()!} />,
Optional: param.isOptional ? 'Yes' : 'No',
Description: param.description ? <TSDoc item={item} tsdoc={param.description} /> : 'None',

View File

@@ -3,7 +3,7 @@ import type {
ApiItemContainerMixin,
ApiProperty,
ApiPropertySignature,
} from '@microsoft/api-extractor-model';
} from '@discordjs/api-extractor-model';
import type { PropsWithChildren } from 'react';
import { Badges } from './Badges';
import { CodeHeading } from './CodeHeading';
@@ -25,7 +25,11 @@ export function Property({
<div className="flex flex-col scroll-mt-30 gap-4" id={item.displayName}>
<div className="flex flex-col gap-2 md:-ml-9">
<Badges item={item} />
<CodeHeading href={`#${item.displayName}`}>
<CodeHeading
href={`#${item.displayName}`}
sourceURL={item.sourceLocation.fileUrl}
sourceLine={item.sourceLocation.fileLine}
>
{`${item.displayName}${item.isOptional ? '?' : ''}`}
<span>:</span>
{item.propertyTypeExcerpt.text ? (

View File

@@ -4,8 +4,8 @@ import type {
ApiItemContainerMixin,
ApiProperty,
ApiPropertySignature,
} from '@microsoft/api-extractor-model';
import { ApiItemKind } from '@microsoft/api-extractor-model';
} from '@discordjs/api-extractor-model';
import { ApiItemKind } from '@discordjs/api-extractor-model';
import { Fragment, useMemo } from 'react';
import { resolveMembers } from '~/util/members';
import { Property } from './Property';

View File

@@ -1,6 +1,6 @@
'use client';
import type { ApiItemKind } from '@microsoft/api-extractor-model';
import type { ApiItemKind } from '@discordjs/api-extractor-model';
import { VscSymbolClass } from '@react-icons/all-files/vsc/VscSymbolClass';
import { VscSymbolEnum } from '@react-icons/all-files/vsc/VscSymbolEnum';
import { VscSymbolInterface } from '@react-icons/all-files/vsc/VscSymbolInterface';

View File

@@ -1,4 +1,4 @@
import type { ApiModel, Excerpt } from '@microsoft/api-extractor-model';
import type { ApiModel, Excerpt } from '@discordjs/api-extractor-model';
import { ExcerptText } from './ExcerptText';
export function SignatureText({ excerpt, model }: { readonly excerpt: Excerpt; readonly model: ApiModel }) {

View File

@@ -1,4 +1,4 @@
import type { ApiTypeParameterListMixin } from '@microsoft/api-extractor-model';
import type { ApiTypeParameterListMixin } from '@discordjs/api-extractor-model';
import { useMemo } from 'react';
import { ExcerptText } from './ExcerptText';
import { Table } from './Table';

View File

@@ -1,11 +1,11 @@
import { ApiItemKind } from '@microsoft/api-extractor-model';
import { VscFileCode } from '@react-icons/all-files/vsc/VscFileCode';
import { ApiItemKind } from '@discordjs/api-extractor-model';
import { VscSymbolClass } from '@react-icons/all-files/vsc/VscSymbolClass';
import { VscSymbolEnum } from '@react-icons/all-files/vsc/VscSymbolEnum';
import { VscSymbolInterface } from '@react-icons/all-files/vsc/VscSymbolInterface';
import { VscSymbolMethod } from '@react-icons/all-files/vsc/VscSymbolMethod';
import { VscSymbolVariable } from '@react-icons/all-files/vsc/VscSymbolVariable';
import type { PropsWithChildren } from 'react';
import { SourceLink } from './SourceLink';
function generateIcon(kind: ApiItemKind) {
switch (kind) {
@@ -30,7 +30,13 @@ export function Header({
kind,
name,
sourceURL,
}: PropsWithChildren<{ readonly kind: ApiItemKind; readonly name: string; readonly sourceURL?: string | undefined }>) {
sourceLine,
}: PropsWithChildren<{
readonly kind: ApiItemKind;
readonly name: string;
readonly sourceLine?: number | undefined;
readonly sourceURL?: string | undefined;
}>) {
return (
<div className="flex flex-col">
<h2 className="flex flex-row place-items-center justify-between gap-2 break-all text-2xl font-bold">
@@ -38,11 +44,7 @@ export function Header({
<span>{generateIcon(kind)}</span>
{name}
</span>
{sourceURL ? (
<a className="text-blurple" href={sourceURL} rel="external noopener noreferrer" target="_blank">
<VscFileCode />
</a>
) : null}
{sourceURL ? <SourceLink sourceLine={sourceLine} sourceURL={sourceURL} /> : null}
</h2>
</div>
);

View File

@@ -1,5 +1,5 @@
import type { ApiClass, ApiInterface, Excerpt } from '@microsoft/api-extractor-model';
import { ApiItemKind } from '@microsoft/api-extractor-model';
import type { ApiClass, ApiInterface, Excerpt } from '@discordjs/api-extractor-model';
import { ApiItemKind } from '@discordjs/api-extractor-model';
import { ExcerptText } from '../ExcerptText';
export function HierarchyText({

View File

@@ -1,4 +1,4 @@
import type { ApiDeclaredItem, ApiItemContainerMixin } from '@microsoft/api-extractor-model';
import type { ApiDeclaredItem, ApiItemContainerMixin } from '@discordjs/api-extractor-model';
import { MethodsSection } from './section/MethodsSection';
import { PropertiesSection } from './section/PropertiesSection';
import { hasProperties, hasMethods } from './util';

View File

@@ -1,4 +1,4 @@
import type { ApiDeclaredItem } from '@microsoft/api-extractor-model';
import type { ApiDeclaredItem } from '@discordjs/api-extractor-model';
import { SyntaxHighlighter } from '../SyntaxHighlighter';
import { Header } from './Header';
import { SummarySection } from './section/SummarySection';
@@ -10,7 +10,12 @@ export interface ObjectHeaderProps {
export function ObjectHeader({ item }: ObjectHeaderProps) {
return (
<>
<Header kind={item.kind} name={item.displayName} sourceURL={item.sourceLocation.fileUrl} />
<Header
kind={item.kind}
name={item.displayName}
sourceURL={item.sourceLocation.fileUrl}
sourceLine={item.sourceLocation.fileLine}
/>
{/* @ts-expect-error async component */}
<SyntaxHighlighter code={item.excerpt.text} />
<SummarySection item={item} />

View File

@@ -0,0 +1,22 @@
import { VscFileCode } from '@react-icons/all-files/vsc/VscFileCode';
export function SourceLink({
className,
sourceURL,
sourceLine,
}: {
readonly className?: string | undefined;
readonly sourceLine?: number | undefined;
readonly sourceURL?: string | undefined;
}) {
return (
<a
className={` text-blurple ${className}`}
href={sourceLine ? `${sourceURL}#L${sourceLine}` : sourceURL}
rel="external noopener noreferrer"
target="_blank"
>
<VscFileCode />
</a>
);
}

View File

@@ -1,4 +1,4 @@
import type { ApiConstructor } from '@microsoft/api-extractor-model';
import type { ApiConstructor } from '@discordjs/api-extractor-model';
import { VscSymbolMethod } from '@react-icons/all-files/vsc/VscSymbolMethod';
import { CodeHeading } from '~/components/CodeHeading';
import { ParameterTable } from '../../ParameterTable';
@@ -10,7 +10,10 @@ export function ConstructorSection({ item }: { readonly item: ApiConstructor })
return (
<DocumentationSection icon={<VscSymbolMethod size={20} />} padded title="Constructor">
<div className="flex flex-col gap-2">
<CodeHeading>{`constructor(${parametersString(item)})`}</CodeHeading>
<CodeHeading
sourceURL={item.sourceLocation.fileUrl}
sourceLine={item.sourceLocation.fileLine}
>{`constructor(${parametersString(item)})`}</CodeHeading>
{item.tsdocComment ? <TSDoc item={item} tsdoc={item.tsdocComment} /> : null}
<ParameterTable item={item} />
</div>

View File

@@ -4,8 +4,8 @@ import type {
ApiItemContainerMixin,
ApiMethod,
ApiMethodSignature,
} from '@microsoft/api-extractor-model';
import { ApiItemKind } from '@microsoft/api-extractor-model';
} from '@discordjs/api-extractor-model';
import { ApiItemKind } from '@discordjs/api-extractor-model';
import { VscSymbolMethod } from '@react-icons/all-files/vsc/VscSymbolMethod';
import { useMemo, Fragment } from 'react';
import { resolveMembers } from '~/util/members';

View File

@@ -1,4 +1,4 @@
import type { ApiDocumentedItem, ApiParameterListMixin } from '@microsoft/api-extractor-model';
import type { ApiDocumentedItem, ApiParameterListMixin } from '@discordjs/api-extractor-model';
import { VscSymbolParameter } from '@react-icons/all-files/vsc/VscSymbolParameter';
import { ParameterTable } from '../../ParameterTable';
import { DocumentationSection } from './DocumentationSection';

View File

@@ -1,4 +1,4 @@
import type { ApiItemContainerMixin } from '@microsoft/api-extractor-model';
import type { ApiItemContainerMixin } from '@discordjs/api-extractor-model';
import { VscSymbolProperty } from '@react-icons/all-files/vsc/VscSymbolProperty';
import { PropertyList } from '../../PropertyList';
import { DocumentationSection } from './DocumentationSection';

View File

@@ -1,4 +1,4 @@
import type { ApiDeclaredItem } from '@microsoft/api-extractor-model';
import type { ApiDeclaredItem } from '@discordjs/api-extractor-model';
import { VscListSelection } from '@react-icons/all-files/vsc/VscListSelection';
import { TSDoc } from '../tsdoc/TSDoc';
import { DocumentationSection } from './DocumentationSection';

View File

@@ -1,4 +1,4 @@
import type { ApiTypeParameterListMixin } from '@microsoft/api-extractor-model';
import type { ApiTypeParameterListMixin } from '@discordjs/api-extractor-model';
import { VscSymbolParameter } from '@react-icons/all-files/vsc/VscSymbolParameter';
import { TypeParamTable } from '../../TypeParamTable';
import { DocumentationSection } from './DocumentationSection';

View File

@@ -1,4 +1,4 @@
import type { ApiItem } from '@microsoft/api-extractor-model';
import type { ApiItem } from '@discordjs/api-extractor-model';
import type { DocComment, DocFencedCode, DocLinkTag, DocNode, DocNodeContainer, DocPlainText } from '@microsoft/tsdoc';
import { DocNodeKind, StandardTags } from '@microsoft/tsdoc';
import type { Route } from 'next';

View File

@@ -1,4 +1,4 @@
import { ApiItemKind } from '@microsoft/api-extractor-model';
import { ApiItemKind } from '@discordjs/api-extractor-model';
import type {
ApiItem,
ApiItemContainerMixin,
@@ -8,7 +8,7 @@ import type {
ApiPropertySignature,
ApiDocumentedItem,
ApiParameterListMixin,
} from '@microsoft/api-extractor-model';
} from '@discordjs/api-extractor-model';
import { METHOD_SEPARATOR, OVERLOAD_SEPARATOR } from '~/util/constants';
import { resolveMembers } from '~/util/members';
import { resolveParameters } from '~/util/model';
@@ -63,9 +63,9 @@ export function serializeMembers(clazz: ApiItemContainerMixin): TableOfContentsS
export function parametersString(item: ApiDocumentedItem & ApiParameterListMixin) {
return resolveParameters(item).reduce((prev, cur, index) => {
if (index === 0) {
return `${prev}${cur.isOptional ? `${cur.name}?` : cur.name}`;
return `${prev}${cur.isRest ? '...' : ''}${cur.isOptional ? `${cur.name}?` : cur.name}`;
}
return `${prev}, ${cur.isOptional ? `${cur.name}?` : cur.name}`;
return `${prev}, ${cur.isRest ? '...' : ''}${cur.isOptional ? `${cur.name}?` : cur.name}`;
}, '');
}

View File

@@ -1,5 +1,5 @@
import type { ApiClass, ApiConstructor } from '@microsoft/api-extractor-model';
import { ApiItemKind } from '@microsoft/api-extractor-model';
import type { ApiClass, ApiConstructor } from '@discordjs/api-extractor-model';
import { ApiItemKind } from '@discordjs/api-extractor-model';
// import { Outline } from '../Outline';
import { Badges } from '../Badges';
import { Documentation } from '../documentation/Documentation';

View File

@@ -1,4 +1,4 @@
import type { ApiInterface } from '@microsoft/api-extractor-model';
import type { ApiInterface } from '@discordjs/api-extractor-model';
// import { Outline } from '../Outline';
import { Documentation } from '../documentation/Documentation';
import { HierarchyText } from '../documentation/HierarchyText';

View File

@@ -1,4 +1,4 @@
import type { ApiTypeAlias } from '@microsoft/api-extractor-model';
import type { ApiTypeAlias } from '@discordjs/api-extractor-model';
import { SyntaxHighlighter } from '../SyntaxHighlighter';
import { Documentation } from '../documentation/Documentation';
import { Header } from '../documentation/Header';
@@ -7,7 +7,12 @@ import { SummarySection } from '../documentation/section/SummarySection';
export function TypeAlias({ item }: { readonly item: ApiTypeAlias }) {
return (
<Documentation>
<Header kind={item.kind} name={item.displayName} sourceURL={item.sourceLocation.fileUrl} />
<Header
kind={item.kind}
name={item.displayName}
sourceURL={item.sourceLocation.fileUrl}
sourceLine={item.sourceLocation.fileLine}
/>
{/* @ts-expect-error async component */}
<SyntaxHighlighter code={item.excerpt.text} />
<SummarySection item={item} />

View File

@@ -1,4 +1,4 @@
import type { ApiVariable } from '@microsoft/api-extractor-model';
import type { ApiVariable } from '@discordjs/api-extractor-model';
import { Documentation } from '../documentation/Documentation';
import { ObjectHeader } from '../documentation/ObjectHeader';

View File

@@ -1,4 +1,4 @@
import type { ApiEnum } from '@microsoft/api-extractor-model';
import type { ApiEnum } from '@discordjs/api-extractor-model';
import { VscSymbolEnum } from '@react-icons/all-files/vsc/VscSymbolEnum';
import { Panel } from '../../Panel';
import { Documentation } from '../../documentation/Documentation';

View File

@@ -1,4 +1,4 @@
import type { ApiEnumMember } from '@microsoft/api-extractor-model';
import type { ApiEnumMember } from '@discordjs/api-extractor-model';
import { CodeHeading } from '~/components/CodeHeading';
import { SignatureText } from '../../SignatureText';
import { TSDoc } from '../../documentation/tsdoc/TSDoc';
@@ -6,7 +6,12 @@ import { TSDoc } from '../../documentation/tsdoc/TSDoc';
export function EnumMember({ member }: { readonly member: ApiEnumMember }) {
return (
<div className="flex flex-col scroll-mt-30" id={member.displayName}>
<CodeHeading className="md:-ml-8.5" href={`#${member.displayName}`}>
<CodeHeading
className="md:-ml-8.5"
href={`#${member.displayName}`}
sourceURL={member.sourceLocation.fileUrl}
sourceLine={member.sourceLocation.fileLine}
>
{member.name}
<span>=</span>
{member.initializerExcerpt ? (

View File

@@ -1,4 +1,4 @@
import type { ApiFunction } from '@microsoft/api-extractor-model';
import type { ApiFunction } from '@discordjs/api-extractor-model';
import dynamic from 'next/dynamic';
import { Header } from '../../documentation/Header';
import { FunctionBody } from './FunctionBody';
@@ -6,7 +6,14 @@ import { FunctionBody } from './FunctionBody';
const OverloadSwitcher = dynamic(async () => import('../../OverloadSwitcher'));
export function Function({ item }: { readonly item: ApiFunction }) {
const header = <Header kind={item.kind} name={item.name} sourceURL={item.sourceLocation.fileUrl} />;
const header = (
<Header
kind={item.kind}
name={item.name}
sourceURL={item.sourceLocation.fileUrl}
sourceLine={item.sourceLocation.fileLine}
/>
);
if (item.getMergedSiblings().length > 1) {
const overloads = item

View File

@@ -1,4 +1,4 @@
import type { ApiFunction } from '@microsoft/api-extractor-model';
import type { ApiFunction } from '@discordjs/api-extractor-model';
import { SyntaxHighlighter } from '../../SyntaxHighlighter';
import { Documentation } from '../../documentation/Documentation';
import { ParameterSection } from '../../documentation/section/ParametersSection';

View File

@@ -3,7 +3,7 @@ import type {
ApiItemContainerMixin,
ApiMethod,
ApiMethodSignature,
} from '@microsoft/api-extractor-model';
} from '@discordjs/api-extractor-model';
import dynamic from 'next/dynamic';
import { Fragment } from 'react';
import { MethodDocumentation } from './MethodDocumentation';

View File

@@ -3,7 +3,7 @@ import type {
ApiItemContainerMixin,
ApiMethod,
ApiMethodSignature,
} from '@microsoft/api-extractor-model';
} from '@discordjs/api-extractor-model';
import { InheritanceText } from '../../InheritanceText';
import { ParameterTable } from '../../ParameterTable';
import { TSDoc } from '../../documentation/tsdoc/TSDoc';

View File

@@ -1,4 +1,4 @@
import type { ApiMethod, ApiMethodSignature } from '@microsoft/api-extractor-model';
import type { ApiMethod, ApiMethodSignature } from '@discordjs/api-extractor-model';
import { useMemo } from 'react';
import { Badges } from '~/components/Badges';
import { CodeHeading } from '~/components/CodeHeading';
@@ -15,7 +15,11 @@ export function MethodHeader({ method }: { readonly method: ApiMethod | ApiMetho
<div className="flex flex-col scroll-mt-30" id={key}>
<div className="flex flex-col gap-2 md:-ml-9">
<Badges item={method} />
<CodeHeading href={`#${key}`}>
<CodeHeading
href={`#${key}`}
sourceLine={method.sourceLocation.fileLine}
sourceURL={method.sourceLocation.fileUrl}
>
{`${method.name}(${parametersString(method)})`}
<span>:</span>
<ExcerptText excerpt={method.returnTypeExcerpt} model={method.getAssociatedModel()!} />