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

fix(website): misc improvements (#9940)

Browse Source 
* refactor: use tokenRange for typeParams in heritage

* fix: correct type param replacement

* fix: ae config, link builtin in summary, `: | T` => `: T`, mainlib tsdoc

* fix: requested changes and tests

* chore: better deprecation messages and code cleanup

* fix: cleanup optional chainings

---------

Co-authored-by: Almeida <almeidx@pm.me>
This commit is contained in:
Qjuh
2023-11-13 09:55:23 +01:00
committed by GitHub
parent 2d63d93558
commit b79351ba99
7 changed files with 134 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
packages/api-extractor/src/generators/ApiModelGenerator.ts
View File

@@ -36,7 +36,6 @@ import {
Navigation,
} from '@discordjs/api-extractor-model';
import type * as tsdoc from '@microsoft/tsdoc';
import { TSDocParser } from '@microsoft/tsdoc';
import { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference.js';
import { JsonFile, Path } from '@rushstack/node-core-library';
import * as ts from 'typescript';
@@ -220,12 +219,16 @@ export class ApiModelGenerator {
private readonly _apiModel: ApiModel;
private readonly _tsDocParser: tsdoc.TSDocParser;
private readonly _referenceGenerator: DeclarationReferenceGenerator;
public constructor(collector: Collector) {
this._collector = collector;
this._apiModel = new ApiModel();
this._referenceGenerator = new DeclarationReferenceGenerator(collector);
// @ts-expect-error we reuse the private tsdocParser from collector here
this._tsDocParser = collector._tsdocParser;
}
public get apiModel(): ApiModel {
@@ -500,7 +503,7 @@ export class ApiModelGenerator {
const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
const docComment: tsdoc.DocComment | undefined = parent?.construct
? new TSDocParser().parseString(
? this._tsDocParser.parseString(
`/*+\n * ${fixLinkTags(parent.construct.description)}\n${
parent.construct.params
?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`)
@@ -586,7 +589,7 @@ export class ApiModelGenerator {
const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
const docComment: tsdoc.DocComment | undefined = jsDoc
? new TSDocParser().parseString(
? this._tsDocParser.parseString(
`/**\n * ${fixLinkTags(jsDoc.description)}\n${jsDoc.see?.map((see) => ` * @see ${see}\n`).join('') ?? ''}${
jsDoc.deprecated
? ` * @deprecated ${
@@ -658,7 +661,7 @@ export class ApiModelGenerator {
const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
const docComment: tsdoc.DocComment | undefined = parent?.construct
? new TSDocParser().parseString(
? this._tsDocParser.parseString(
`/*+\n * ${fixLinkTags(parent.construct.description)}\n${
parent.construct.params
?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`)
@@ -789,7 +792,7 @@ export class ApiModelGenerator {
const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
const docComment: tsdoc.DocComment | undefined = jsDoc
? new TSDocParser().parseString(
? this._tsDocParser.parseString(
`/**\n * ${fixLinkTags(jsDoc.description)}\n${
jsDoc.params?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('') ??
''
@@ -916,7 +919,7 @@ export class ApiModelGenerator {
const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
const docComment: tsdoc.DocComment | undefined = jsDoc
? new TSDocParser().parseString(
? this._tsDocParser.parseString(
`/**\n * ${fixLinkTags(jsDoc.description)}\n${jsDoc.see?.map((see) => ` * @see ${see}\n`).join('') ?? ''}${
jsDoc.deprecated
? ` * @deprecated ${
@@ -980,7 +983,7 @@ export class ApiModelGenerator {
const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
const docComment: tsdoc.DocComment | undefined = jsDoc
? new TSDocParser().parseString(
? this._tsDocParser.parseString(
`/**\n * ${fixLinkTags(jsDoc.description)}\n${
jsDoc.params?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('') ??
''
@@ -1058,7 +1061,7 @@ export class ApiModelGenerator {
const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
const docComment: tsdoc.DocComment | undefined = jsDoc
? new TSDocParser().parseString(
? this._tsDocParser.parseString(
`/**\n * ${fixLinkTags(jsDoc.description)}\n${
jsDoc.params?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('') ??
''
@@ -1166,7 +1169,7 @@ export class ApiModelGenerator {
const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
const docComment: tsdoc.DocComment | undefined = jsDoc
? new TSDocParser().parseString(
? this._tsDocParser.parseString(
`/**\n * ${fixLinkTags(jsDoc.description)}\n${
'see' in jsDoc ? jsDoc.see.map((see) => ` * @see ${see}\n`).join('') : ''
}${'readonly' in jsDoc && jsDoc.readonly ? ' * @readonly\n' : ''}${
@@ -1229,7 +1232,7 @@ export class ApiModelGenerator {
const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
const docComment: tsdoc.DocComment | undefined = jsDoc
? new TSDocParser().parseString(
? this._tsDocParser.parseString(
`/**\n * ${fixLinkTags(jsDoc.description)}\n${
'see' in jsDoc ? jsDoc.see.map((see) => ` * @see ${see}\n`).join('') : ''
}${'readonly' in jsDoc && jsDoc.readonly ? ' * @readonly\n' : ''}${
@@ -1290,7 +1293,7 @@ export class ApiModelGenerator {
const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
const docComment: tsdoc.DocComment | undefined = jsDoc
? new TSDocParser().parseString(
? this._tsDocParser.parseString(
`/**\n * ${fixLinkTags(jsDoc.description) ?? ''}\n${
'params' in jsDoc
? jsDoc.params.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('')
@@ -1425,7 +1428,7 @@ export class ApiModelGenerator {
});
}
const docComment: tsdoc.DocComment | undefined = new TSDocParser().parseString(
const docComment: tsdoc.DocComment | undefined = this._tsDocParser.parseString(
`/**\n * ${fixLinkTags(jsDoc.description)}\n${
jsDoc.params?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('') ?? ''
}${'see' in jsDoc ? jsDoc.see.map((see) => ` * @see ${see}\n`).join('') : ''}${

27
packages/api-extractor/src/generators/ExcerptBuilder.ts
View File

@@ -135,7 +135,7 @@ export class ExcerptBuilder {
return { startIndex: 0, endIndex: 0, typeParameters: [] };
}
public static isPrimitiveKeyword(node: ts.Node): boolean {
private static _isPrimitiveKeyword(node: ts.Node): boolean {
switch (node.kind) {
case ts.SyntaxKind.AnyKeyword:
case ts.SyntaxKind.BigIntKeyword:
@@ -156,6 +156,15 @@ export class ExcerptBuilder {
}
}
private static _isRedundantBarAfterColon(span: Span) {
return (
span.kind === ts.SyntaxKind.BarToken &&
span.previousSibling === undefined &&
(span.parent?.parent?.previousSibling?.kind === ts.SyntaxKind.LessThanToken ||
span.parent?.parent?.previousSibling?.kind === ts.SyntaxKind.ColonToken)
);
}
private static _buildSpan(excerptTokens: IExcerptToken[], span: Span, state: IBuildSpanState): boolean {
if (span.kind === ts.SyntaxKind.JSDocComment) {
// Discard any comments
@@ -174,21 +183,21 @@ export class ExcerptBuilder {
if (span.prefix) {
let canonicalReference: DeclarationReference | undefined;
if (span.kind === ts.SyntaxKind.Identifier) {
const name: ts.Identifier = span.node as ts.Identifier;
if (ts.isIdentifier(span.node)) {
const name: ts.Identifier = span.node;
canonicalReference = state.referenceGenerator.getDeclarationReferenceForIdentifier(name);
}
if (canonicalReference) {
ExcerptBuilder._appendToken(excerptTokens, ExcerptTokenKind.Reference, span.prefix, canonicalReference);
} else if (
ExcerptBuilder.isPrimitiveKeyword(span.node) ||
(span.node.kind === ts.SyntaxKind.Identifier &&
ExcerptBuilder._isPrimitiveKeyword(span.node) ||
(ts.isIdentifier(span.node) &&
((ts.isTypeReferenceNode(span.node.parent) && span.node.parent.typeName === span.node) ||
(ts.isTypeParameterDeclaration(span.node.parent) && span.node.parent.name === span.node)))
) {
ExcerptBuilder._appendToken(excerptTokens, ExcerptTokenKind.Reference, span.prefix);
} else {
} else if (!ExcerptBuilder._isRedundantBarAfterColon(span)) {
ExcerptBuilder._appendToken(excerptTokens, ExcerptTokenKind.Content, span.prefix);
}
@@ -313,6 +322,12 @@ export class ExcerptBuilder {
!startOrEndIndices.has(currentIndex)
) {
prevToken.text += currentToken.text;
// Remove BarTokens from excerpts if they immediately follow a LessThanToken, e.g. `Promise< | Something>`
// would become `Promise<Something>`
if (/<\s*\|/.test(prevToken.text)) {
prevToken.text = prevToken.text.replace(/<\s*\|\s*/, '<');
}
mergeCount = 1;
} else {
// Otherwise, no merging can occur here. Continue to the next index.