From d0484e8c021badadd4087432d491aa51badfdc95 Mon Sep 17 00:00:00 2001 From: Charis <26616127+charislam@users.noreply.github.com> Date: Tue, 30 Sep 2025 07:54:07 -0400 Subject: [PATCH] fix: prepare docs for typedoc update (#39084) We're dropping some information from newer versions of Typedoc spec (compared to older ones). Fixed this. --- apps/docs/features/docs/Reference.typeSpec.ts | 34 ++- .../Reference.typeSpec.test.ts.snap | 254 +++++++++++++++++- 2 files changed, 273 insertions(+), 15 deletions(-) diff --git a/apps/docs/features/docs/Reference.typeSpec.ts b/apps/docs/features/docs/Reference.typeSpec.ts index c076ff43ca2..98298bcf2b9 100644 --- a/apps/docs/features/docs/Reference.typeSpec.ts +++ b/apps/docs/features/docs/Reference.typeSpec.ts @@ -156,6 +156,15 @@ export interface CustomTypePropertyType { type: TypeDetails | undefined } +// The meaning of kind flags from `typedoc`: +// https://github.com/TypeStrong/typedoc/blob/2953b0148253589448176881a7acb46090f941bd/src/lib/output/themes/default/assets/typedoc/Application.ts#L36 +const KIND_MODULE = 2 +const KIND_CLASS = 128 +const KIND_INTERFACE = 256 +const KIND_CONSTRUCTOR = 512 +const KIND_METHOD = 2048 +const KIND_TYPE_LITERAL = 65536 + /** * * New versions of `typedoc` added the variant property, so this is a quick and @@ -205,7 +214,7 @@ function normalizeComment(original: TypedocComment | Comment | undefined): Comme return original } - let comment: Comment = {} + const comment: Comment = {} if ('summary' in original) { comment.shortText = original.summary.map((part) => part.text).join('') @@ -218,13 +227,6 @@ function normalizeComment(original: TypedocComment | Comment | undefined): Comme return comment } -// The meaning of kind flags from `typedoc`: -// https://github.com/TypeStrong/typedoc/blob/2953b0148253589448176881a7acb46090f941bd/src/lib/output/themes/default/assets/typedoc/Application.ts#L36 -const KIND_CLASS = 128 -const KIND_CONSTRUCTOR = 512 -const KIND_METHOD = 2048 -const KIND_TYPE_LITERAL = 65536 - export function parseTypeSpec() { const modules = (typeSpec.children ?? []).map(parseMod) return modules as Array @@ -294,7 +296,7 @@ function parseModInternal( node.children?.forEach((child: any) => parseModInternal(child, map, updatedPath, res)) return case 'declaration': - if (node.kind === KIND_CLASS) { + if (node.kind === KIND_CLASS || node.kind === KIND_MODULE) { updatedPath = [...currentPath, node.name] node.children?.forEach((child: any) => parseModInternal(child, map, updatedPath, res)) } else if (node.kind === KIND_CONSTRUCTOR) { @@ -540,6 +542,8 @@ function parseReferenceType(type: any, map: Map) { if (maybeType) { return maybeType + } else if (isNewTypedoc(referenced) && referenced.kind === KIND_INTERFACE) { + return parseInterface(referenced, map) } else if (isNewTypedoc(referenced) && referenced.kind === KIND_CLASS) { // Class is too complicated to display here, just return its name return { @@ -673,7 +677,9 @@ function parseTypeLiteral(type: any, map: Map): TypeDetails | undef const name = nameOrAnonymous(type) if ('children' in type.declaration) { - const properties = type.declaration.children.map((child: any) => parseTypeInternals(child, map)) + const properties = type.declaration.children + .map((child: any) => parseTypeInternals(child, map)) + .filter(Boolean) return { name, type: 'object', @@ -725,7 +731,9 @@ function parseTypeOperatorType(type: any, map: Map) { } function parseInterface(type: any, map: Map): CustomObjectType { - const properties = (type.children ?? []).map((child) => parseTypeInternals(child, map)) + const properties = (type.children ?? []) + .map((child) => parseTypeInternals(child, map)) + .filter(Boolean) return { type: 'object', @@ -766,6 +774,10 @@ function parseTypeInternals(elem: any, map: Map) { function parseInternalProperty(elem: any, map: Map) { const name = nameOrAnonymous(elem) + if (!elem.type) { + return undefined + } + const type = parseType(elem.type, map) const res = { diff --git a/apps/docs/features/docs/__snapshots__/Reference.typeSpec.test.ts.snap b/apps/docs/features/docs/__snapshots__/Reference.typeSpec.test.ts.snap index 534f8f547c7..0eeee322f79 100644 --- a/apps/docs/features/docs/__snapshots__/Reference.typeSpec.test.ts.snap +++ b/apps/docs/features/docs/__snapshots__/Reference.typeSpec.test.ts.snap @@ -29616,8 +29616,9 @@ exports[`TS type spec parsing > matches snapshot 1`] = ` { "name": "transport", "type": { - "type": "nameOnly", - "name": "WebSocketLikeConstructor" + "type": "object", + "name": "WebSocketLikeConstructor", + "properties": [] }, "isOptional": true }, @@ -30241,8 +30242,253 @@ exports[`TS type spec parsing > matches snapshot 1`] = ` ], "ret": { "type": { - "type": "nameOnly", - "name": "WebSocketLike" + "type": "object", + "name": "WebSocketLike", + "properties": [ + { + "name": "binaryType", + "type": { + "type": "intrinsic", + "name": "string" + }, + "isOptional": true + }, + { + "name": "bufferedAmount", + "type": { + "type": "intrinsic", + "name": "number" + }, + "isOptional": true + }, + { + "name": "CLOSED", + "type": { + "type": "intrinsic", + "name": "number" + } + }, + { + "name": "CLOSING", + "type": { + "type": "intrinsic", + "name": "number" + } + }, + { + "name": "CONNECTING", + "type": { + "type": "intrinsic", + "name": "number" + } + }, + { + "name": "dispatchEvent", + "type": { + "type": "function", + "params": [ + { + "name": "event", + "type": { + "type": "nameOnly", + "name": "Event" + } + } + ], + "ret": { + "type": { + "type": "intrinsic", + "name": "boolean" + } + } + }, + "isOptional": true + }, + { + "name": "extensions", + "type": { + "type": "intrinsic", + "name": "string" + }, + "isOptional": true + }, + { + "name": "onclose", + "type": { + "type": "union", + "subTypes": [ + { + "type": "literal", + "value": null + }, + { + "type": "function", + "params": [ + { + "name": "this", + "type": { + "type": "intrinsic", + "name": "any" + } + }, + { + "name": "ev", + "type": { + "type": "nameOnly", + "name": "CloseEvent" + } + } + ], + "ret": { + "type": { + "type": "intrinsic", + "name": "any" + } + } + } + ] + } + }, + { + "name": "onerror", + "type": { + "type": "union", + "subTypes": [ + { + "type": "literal", + "value": null + }, + { + "type": "function", + "params": [ + { + "name": "this", + "type": { + "type": "intrinsic", + "name": "any" + } + }, + { + "name": "ev", + "type": { + "type": "nameOnly", + "name": "Event" + } + } + ], + "ret": { + "type": { + "type": "intrinsic", + "name": "any" + } + } + } + ] + } + }, + { + "name": "onmessage", + "type": { + "type": "union", + "subTypes": [ + { + "type": "literal", + "value": null + }, + { + "type": "function", + "params": [ + { + "name": "this", + "type": { + "type": "intrinsic", + "name": "any" + } + }, + { + "name": "ev", + "type": { + "type": "nameOnly", + "name": "MessageEvent" + } + } + ], + "ret": { + "type": { + "type": "intrinsic", + "name": "any" + } + } + } + ] + } + }, + { + "name": "onopen", + "type": { + "type": "union", + "subTypes": [ + { + "type": "literal", + "value": null + }, + { + "type": "function", + "params": [ + { + "name": "this", + "type": { + "type": "intrinsic", + "name": "any" + } + }, + { + "name": "ev", + "type": { + "type": "nameOnly", + "name": "Event" + } + } + ], + "ret": { + "type": { + "type": "intrinsic", + "name": "any" + } + } + } + ] + } + }, + { + "name": "OPEN", + "type": { + "type": "intrinsic", + "name": "number" + } + }, + { + "name": "protocol", + "type": { + "type": "intrinsic", + "name": "string" + } + }, + { + "name": "readyState", + "type": { + "type": "intrinsic", + "name": "number" + } + }, + { + "name": "url", + "type": { + "type": "intrinsic", + "name": "string" + } + } + ] } } },