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): type parameters links, builtin doc links, default values (#10515)

Browse Source 
* 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
2024-10-19 02:04:01 +02:00
committed by Jiralite
parent 31df3d21cd
commit 43235d43fe
11 changed files with 219 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
packages/scripts/src/generateSplitDocumentation.ts
View File

@@ -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,
};
}
@@ -589,6 +621,7 @@ function resolveParameters(item: ApiDocumentedItem & ApiParameterListMixin) {
isOptional: param.isOptional,
isRest: param.isRest,
parameterTypeExcerpt: param.parameterTypeExcerpt,
defaultValue: param.defaultValue,
};
});
}
@@ -608,9 +641,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,
}));
}
@@ -627,9 +660,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,
}));
}
@@ -677,7 +715,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,
};
});
@@ -713,7 +755,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),
@@ -809,7 +855,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),
),
};
});
}
@@ -903,7 +953,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),
),
),
};
}