mirror of
https://github.com/discordjs/discord.js.git
synced 2026-03-09 16:13:31 +01:00
feat(website): type parameters links, builtin doc links, default values (#10515)
* feat(website): links to type parameters, builtin doc links in api.json * feat(website): show default values for params and props in excerpt * fix: link in jsdoc --------- Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com> Co-authored-by: Jiralite <33201955+Jiralite@users.noreply.github.com>
This commit is contained in:
Qjuh
109
packages/scripts/src/builtinDocumentationLinks.ts
Normal file
109
packages/scripts/src/builtinDocumentationLinks.ts
Normal file
@@ -0,0 +1,109 @@
|
||||
export const BuiltinDocumentationLinks = {
|
||||
// Built-in types
|
||||
bigint: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/BigInt',
|
||||
boolean: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean',
|
||||
null: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/null',
|
||||
number: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number',
|
||||
string: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String',
|
||||
symbol: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol',
|
||||
undefined: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined',
|
||||
|
||||
// Built-in classes
|
||||
AbortSignal: 'https://developer.mozilla.org/docs/Web/API/AbortSignal',
|
||||
Agent: 'https://undici.nodejs.org/#/docs/api/Agent',
|
||||
Array: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array',
|
||||
ArrayBuffer: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer',
|
||||
AsyncGenerator: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator',
|
||||
AsyncIterable: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols',
|
||||
AsyncIterableIterator: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols',
|
||||
Buffer: 'https://nodejs.org/api/buffer.html#class-buffer',
|
||||
ChildProcess: 'https://nodejs.org/api/child_process.html#class-childprocess',
|
||||
Date: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date',
|
||||
Dispatcher: 'https://undici.nodejs.org/#/docs/api/Dispatcher',
|
||||
Error: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error',
|
||||
Function: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function',
|
||||
Generator: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Generator',
|
||||
IncomingMessage: 'https://nodejs.org/api/http.html#class-httpincomingmessage',
|
||||
Iterable: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols',
|
||||
IterableIterator: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols',
|
||||
Iterator: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Iterator',
|
||||
Map: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map',
|
||||
MessagePort: 'https://nodejs.org/api/worker_threads.html#class-messageport',
|
||||
Promise: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise',
|
||||
RangeError: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RangeError',
|
||||
Readable: 'https://nodejs.org/api/stream.html#class-streamreadable',
|
||||
ReadableStream: 'https://developer.mozilla.org/docs/Web/API/ReadableStream',
|
||||
RegExp: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp',
|
||||
Response: 'https://developer.mozilla.org/docs/Web/API/Response',
|
||||
ServerResponse: 'https://nodejs.org/api/http.html#class-httpserverresponse',
|
||||
Set: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set',
|
||||
Stream: 'https://nodejs.org/api/stream.html#stream',
|
||||
SymbolConstructor: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol',
|
||||
TypeError: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError',
|
||||
URL: 'https://developer.mozilla.org/docs/Web/API/URL',
|
||||
URLSearchParams: 'https://developer.mozilla.org/docs/Web/API/URLSearchParams',
|
||||
WeakMap: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakMap',
|
||||
WeakRef: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakRef',
|
||||
WeakSet: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakSet',
|
||||
WebSocket: 'https://developer.mozilla.org/docs/Web/API/WebSocket',
|
||||
Worker: 'https://nodejs.org/api/worker_threads.html#class-worker',
|
||||
'NodeJS.Timeout': 'https://nodejs.org/api/timers.html#class-timeout',
|
||||
|
||||
// Typed arrays
|
||||
BigInt64Array: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array',
|
||||
BigUint64Array: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/BigUint64Array',
|
||||
Float32Array: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Float32Array',
|
||||
Float64Array: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Float64Array',
|
||||
Int16Array: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int16Array',
|
||||
Int32Array: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int32Array',
|
||||
Int8Array: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int8Array',
|
||||
Uint16Array: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint16Array',
|
||||
Uint32Array: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint32Array',
|
||||
Uint8Array: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array',
|
||||
Uint8ClampedArray: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8ClampedArray',
|
||||
|
||||
// TypeScript types
|
||||
any: 'https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any',
|
||||
keyof: 'https://www.typescriptlang.org/docs/handbook/2/keyof-types.html',
|
||||
never: 'https://www.typescriptlang.org/docs/handbook/2/functions.html#never',
|
||||
object: 'https://www.typescriptlang.org/docs/handbook/2/functions.html#object',
|
||||
ReadonlyArray: 'https://www.typescriptlang.org/docs/handbook/2/objects.html#the-readonlyarray-type',
|
||||
ReadonlyMap:
|
||||
'https://github.com/microsoft/TypeScript/blob/1416053b9e85ca2344a7a6aa10456d633ea1cd65/src/lib/es2015.collection.d.ts#L38-L43',
|
||||
ReadonlySet:
|
||||
'https://github.com/microsoft/TypeScript/blob/1416053b9e85ca2344a7a6aa10456d633ea1cd65/src/lib/es2015.collection.d.ts#L104-L108',
|
||||
unknown: 'https://www.typescriptlang.org/docs/handbook/2/functions.html#unknown',
|
||||
this: 'https://www.typescriptlang.org/docs/handbook/2/classes.html#this-types',
|
||||
typeof: 'https://www.typescriptlang.org/docs/handbook/2/typeof-types.html',
|
||||
void: 'https://www.typescriptlang.org/docs/handbook/2/functions.html#void',
|
||||
|
||||
// TypeScript utility types
|
||||
Awaited: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#awaitedtype',
|
||||
Partial: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype',
|
||||
Required: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#requiredtype',
|
||||
Readonly: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype',
|
||||
Record: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type',
|
||||
Pick: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#picktype-keys',
|
||||
Omit: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys',
|
||||
Exclude: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#excludeuniontype-excludedmembers',
|
||||
Extract: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#extracttype-union',
|
||||
NonNullable: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#nonnullabletype',
|
||||
Parameters: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#parameterstype',
|
||||
ConstructorParameters: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#constructorparameterstype',
|
||||
ReturnType: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#returntypetype',
|
||||
InstanceType: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#instancetypetype',
|
||||
ThisParameterType: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#thisparametertypetype',
|
||||
OmitThisParameter: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#omitthisparametertype',
|
||||
ThisType: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#thistypetype',
|
||||
Uppercase: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#uppercasestringtype',
|
||||
Lowercase: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#lowercasestringtype',
|
||||
Capitalize: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#capitalizestringtype',
|
||||
Uncapitalize: 'https://www.typescriptlang.org/docs/handbook/utility-types.html#uncapitalizestringtype',
|
||||
|
||||
// External Libraries
|
||||
AsyncEventEmitter: 'https://github.com/vladfrangu/async_event_emitter',
|
||||
AsyncQueue: 'https://www.sapphirejs.dev/docs/Documentation/api-utilities/classes/sapphire_async_queue.AsyncQueue',
|
||||
Redis: 'https://redis.github.io/ioredis/classes/Redis.html',
|
||||
'prism.opus.Encoder': 'https://amishshah.github.io/prism-media/opus.Encoder.html',
|
||||
'prism.VolumeTransformer': 'https://amishshah.github.io/prism-media/core.VolumeTransformer.html',
|
||||
} as const;
|
||||
@@ -18,10 +18,10 @@ import type {
|
||||
ApiProperty,
|
||||
ApiPropertySignature,
|
||||
ApiTypeAlias,
|
||||
ApiTypeParameterListMixin,
|
||||
ApiVariable,
|
||||
} from '@discordjs/api-extractor-model';
|
||||
import {
|
||||
ApiTypeParameterListMixin,
|
||||
Excerpt,
|
||||
Meaning,
|
||||
ApiAbstractMixin,
|
||||
@@ -49,6 +49,7 @@ import type {
|
||||
DocComment,
|
||||
} from '@microsoft/tsdoc';
|
||||
import type { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference.js';
|
||||
import { BuiltinDocumentationLinks } from './builtinDocumentationLinks.js';
|
||||
import { PACKAGES, fetchVersionDocs, fetchVersions } from './shared.js';
|
||||
|
||||
function resolvePackageName(packageName: string) {
|
||||
@@ -225,7 +226,7 @@ function resolveItemURI(item: ApiItemLike): string {
|
||||
: `${item.parent.displayName}:${item.parent.kind}#${item.displayName}`;
|
||||
}
|
||||
|
||||
function itemExcerptText(excerpt: Excerpt, apiPackage: ApiPackage) {
|
||||
function itemExcerptText(excerpt: Excerpt, apiPackage: ApiPackage, parent?: ApiTypeParameterListMixin) {
|
||||
const DISCORD_API_TYPES_VERSION = 'v10';
|
||||
const DISCORD_API_TYPES_DOCS_URL = `https://discord-api-types.dev/api/discord-api-types-${DISCORD_API_TYPES_VERSION}`;
|
||||
|
||||
@@ -286,6 +287,27 @@ function itemExcerptText(excerpt: Excerpt, apiPackage: ApiPackage) {
|
||||
};
|
||||
}
|
||||
|
||||
if (token.text in BuiltinDocumentationLinks) {
|
||||
return {
|
||||
text: token.text,
|
||||
href: BuiltinDocumentationLinks[token.text as keyof typeof BuiltinDocumentationLinks],
|
||||
};
|
||||
}
|
||||
|
||||
if (parent?.typeParameters.some((type) => type.name === token.text)) {
|
||||
const [packageName, parentItem] = parent.canonicalReference.toString().split('!');
|
||||
return {
|
||||
text: token.text,
|
||||
resolvedItem: {
|
||||
kind: 'TypeParameter',
|
||||
displayName: token.text,
|
||||
containerKey: `${parent.containerKey}|${token.text}`,
|
||||
uri: `${parentItem}#${token.text}`,
|
||||
packageName: packageName?.replace('@discordjs/', ''),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
text: token.text,
|
||||
};
|
||||
@@ -346,9 +368,19 @@ function itemTsDoc(item: DocNode, apiItem: ApiItem) {
|
||||
const resolved = resolveCanonicalReference(codeDestination, apiItem.getAssociatedPackage());
|
||||
|
||||
if (!foundItem && !resolved) {
|
||||
const itemName = codeDestination.memberReferences[0]?.memberIdentifier?.identifier;
|
||||
|
||||
if (itemName && itemName in BuiltinDocumentationLinks) {
|
||||
return {
|
||||
kind: DocNodeKind.LinkTag,
|
||||
text: itemName,
|
||||
uri: BuiltinDocumentationLinks[itemName as keyof typeof BuiltinDocumentationLinks],
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
kind: DocNodeKind.LinkTag,
|
||||
text: codeDestination.memberReferences[0]?.memberIdentifier?.identifier ?? null,
|
||||
text: itemName ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -534,6 +566,7 @@ function resolveParameters(item: ApiDocumentedItem & ApiParameterListMixin) {
|
||||
isOptional: param.isOptional,
|
||||
isRest: param.isRest,
|
||||
parameterTypeExcerpt: param.parameterTypeExcerpt,
|
||||
defaultValue: param.defaultValue,
|
||||
};
|
||||
});
|
||||
}
|
||||
@@ -553,9 +586,9 @@ function itemTypeParameters(item: ApiTypeParameterListMixin) {
|
||||
|
||||
return item.typeParameters.map((typeParam) => ({
|
||||
name: typeParam.name,
|
||||
constraintsExcerpt: itemExcerptText(typeParam.constraintExcerpt, item.getAssociatedPackage()!),
|
||||
constraintsExcerpt: itemExcerptText(typeParam.constraintExcerpt, item.getAssociatedPackage()!, item),
|
||||
isOptional: typeParam.isOptional,
|
||||
defaultExcerpt: itemExcerptText(typeParam.defaultTypeExcerpt, item.getAssociatedPackage()!),
|
||||
defaultExcerpt: itemExcerptText(typeParam.defaultTypeExcerpt, item.getAssociatedPackage()!, item),
|
||||
description: typeParam.tsdocTypeParamBlock ? itemTsDoc(typeParam.tsdocTypeParamBlock.content, item) : null,
|
||||
}));
|
||||
}
|
||||
@@ -572,9 +605,14 @@ function itemParameters(item: ApiDocumentedItem & ApiParameterListMixin) {
|
||||
|
||||
return params.map((param) => ({
|
||||
name: param.isRest ? `...${param.name}` : param.name,
|
||||
typeExcerpt: itemExcerptText(param.parameterTypeExcerpt, item.getAssociatedPackage()!),
|
||||
typeExcerpt: itemExcerptText(
|
||||
param.parameterTypeExcerpt,
|
||||
item.getAssociatedPackage()!,
|
||||
item.getHierarchy().find(ApiTypeParameterListMixin.isBaseClassOf),
|
||||
),
|
||||
isOptional: param.isOptional,
|
||||
description: param.description ? itemTsDoc(param.description, item) : null,
|
||||
defaultValue: param.defaultValue,
|
||||
}));
|
||||
}
|
||||
|
||||
@@ -622,7 +660,11 @@ function itemProperty(item: ApiItemContainerMixin) {
|
||||
return {
|
||||
...itemInfo(property.item),
|
||||
inheritedFrom: property.inherited ? resolveItemURI(property.inherited) : null,
|
||||
typeExcerpt: itemExcerptText(property.item.propertyTypeExcerpt, property.item.getAssociatedPackage()!),
|
||||
typeExcerpt: itemExcerptText(
|
||||
property.item.propertyTypeExcerpt,
|
||||
property.item.getAssociatedPackage()!,
|
||||
property.item.getHierarchy().find(ApiTypeParameterListMixin.isBaseClassOf),
|
||||
),
|
||||
summary: hasSummary ? itemTsDoc(property.item.tsdocComment!, property.item) : null,
|
||||
};
|
||||
});
|
||||
@@ -658,7 +700,11 @@ function itemMethod(item: ApiItemContainerMixin) {
|
||||
...itemInfo(method.item),
|
||||
overloadIndex: method.item.overloadIndex,
|
||||
parametersString: parametersString(method.item),
|
||||
returnTypeExcerpt: itemExcerptText(method.item.returnTypeExcerpt, method.item.getAssociatedPackage()!),
|
||||
returnTypeExcerpt: itemExcerptText(
|
||||
method.item.returnTypeExcerpt,
|
||||
method.item.getAssociatedPackage()!,
|
||||
method.item.getHierarchy().find(ApiTypeParameterListMixin.isBaseClassOf),
|
||||
),
|
||||
inheritedFrom: method.inherited ? resolveItemURI(method.inherited) : null,
|
||||
typeParameters: itemTypeParameters(method.item),
|
||||
parameters: itemParameters(method.item),
|
||||
@@ -754,7 +800,11 @@ export function itemHierarchyText({
|
||||
return excerpts.map((excerpt) => {
|
||||
return {
|
||||
type,
|
||||
excerpts: itemExcerptText(excerpt, item.getAssociatedPackage()!),
|
||||
excerpts: itemExcerptText(
|
||||
excerpt,
|
||||
item.getAssociatedPackage()!,
|
||||
item.getHierarchy().find(ApiTypeParameterListMixin.isBaseClassOf),
|
||||
),
|
||||
};
|
||||
});
|
||||
}
|
||||
@@ -848,7 +898,11 @@ function itemTypeAlias(item: ApiTypeAlias) {
|
||||
...itemInfo(item),
|
||||
typeParameters: itemTypeParameters(item),
|
||||
unionMembers: itemUnion(item).map((member) =>
|
||||
itemExcerptText(new Excerpt(member, { startIndex: 0, endIndex: member.length }), item.getAssociatedPackage()!),
|
||||
itemExcerptText(
|
||||
new Excerpt(member, { startIndex: 0, endIndex: member.length }),
|
||||
item.getAssociatedPackage()!,
|
||||
item.getHierarchy().find(ApiTypeParameterListMixin.isBaseClassOf),
|
||||
),
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user