From c3842c1d8336d65199161904498d58cc446eb74c Mon Sep 17 00:00:00 2001 From: Gerrit Birkeland Date: Fri, 29 Nov 2024 07:58:24 -0700 Subject: [PATCH] Minor improvements to API docs --- .config/typedoc.json | 2 +- src/lib/utils/options/defaults.ts | 224 ++++++++++++----------- src/lib/utils/options/index.ts | 2 +- src/lib/utils/options/sources/typedoc.ts | 2 +- src/lib/utils/sort.ts | 2 +- 5 files changed, 117 insertions(+), 115 deletions(-) diff --git a/.config/typedoc.json b/.config/typedoc.json index 2b04211ce..bff3e89f3 100644 --- a/.config/typedoc.json +++ b/.config/typedoc.json @@ -35,7 +35,7 @@ "treatWarningsAsErrors": false, "categorizeByGroup": false, "categoryOrder": ["Reflections", "Types", "Comments", "*"], - "groupOrder": ["Common", "*"], + "groupOrder": ["Common", "Namespaces", "*"], "navigationLinks": { "Docs": "https://typedoc.org", "Example": "https://typedoc.org/example/index.html", diff --git a/src/lib/utils/options/defaults.ts b/src/lib/utils/options/defaults.ts index ec3dd2cc4..e5c269f47 100644 --- a/src/lib/utils/options/defaults.ts +++ b/src/lib/utils/options/defaults.ts @@ -1,118 +1,120 @@ +/** + * Defaults values for TypeDoc options + * @module + */ import type { BundledLanguage } from "@gerrit0/mini-shiki"; import * as TagDefaults from "./tsdoc-defaults.js"; import type { EnumKeys } from "../enum.js"; import type { ReflectionKind } from "../../models/index.js"; -/** - * Default values for TypeDoc options. This object should not be modified. - * - * @privateRemarks - * These are declared here, rather than within the option declaration, so that - * they can be exposed as a part of the public API. The unfortunate type declaration - * is to control the type which appears in the generated documentation. - */ -export const OptionDefaults: { - excludeNotDocumentedKinds: readonly EnumKeys[]; - excludeTags: readonly `@${string}`[]; - blockTags: readonly `@${string}`[]; - inlineTags: readonly `@${string}`[]; - modifierTags: readonly `@${string}`[]; - cascadedModifierTags: readonly `@${string}`[]; - notRenderedTags: readonly `@${string}`[]; - highlightLanguages: readonly BundledLanguage[]; - sort: readonly string[]; - kindSortOrder: readonly EnumKeys[]; - requiredToBeDocumented: readonly EnumKeys[]; -} = { - excludeNotDocumentedKinds: [ - "Module", - "Namespace", - "Enum", - // Not including enum member here by default - "Variable", - "Function", - "Class", - "Interface", - "Constructor", - "Property", - "Method", - "CallSignature", - "IndexSignature", - "ConstructorSignature", - "Accessor", - "GetSignature", - "SetSignature", - "TypeAlias", - "Reference", - ], - excludeTags: [ - "@override", - "@virtual", - "@privateRemarks", - "@satisfies", - "@overload", - "@inline", - ], - blockTags: TagDefaults.blockTags, - inlineTags: TagDefaults.inlineTags, - modifierTags: TagDefaults.modifierTags, - cascadedModifierTags: ["@alpha", "@beta", "@experimental"], - notRenderedTags: [ - "@showCategories", - "@showGroups", - "@hideCategories", - "@hideGroups", - "@expand", - "@summary", - "@group", - "@groupDescription", - "@category", - "@categoryDescription", - ], - highlightLanguages: [ - "bash", - "console", - "css", - "html", - "javascript", - "json", - "jsonc", - "json5", - "yaml", - "tsx", - "typescript", - ], - sort: ["kind", "instance-first", "alphabetical-ignoring-documents"], - kindSortOrder: [ - "Document", - "Project", - "Module", - "Namespace", - "Enum", - "EnumMember", - "Class", - "Interface", - "TypeAlias", +export const excludeNotDocumentedKinds: readonly EnumKeys< + typeof ReflectionKind +>[] = [ + "Module", + "Namespace", + "Enum", + // Not including enum member here by default + "Variable", + "Function", + "Class", + "Interface", + "Constructor", + "Property", + "Method", + "CallSignature", + "IndexSignature", + "ConstructorSignature", + "Accessor", + "GetSignature", + "SetSignature", + "TypeAlias", + "Reference", +]; + +export const excludeTags: readonly `@${string}`[] = [ + "@override", + "@virtual", + "@privateRemarks", + "@satisfies", + "@overload", + "@inline", +]; + +export const blockTags: readonly `@${string}`[] = TagDefaults.blockTags; +export const inlineTags: readonly `@${string}`[] = TagDefaults.inlineTags; +export const modifierTags: readonly `@${string}`[] = TagDefaults.modifierTags; + +export const cascadedModifierTags: readonly `@${string}`[] = [ + "@alpha", + "@beta", + "@experimental", +]; + +export const notRenderedTags: readonly `@${string}`[] = [ + "@showCategories", + "@showGroups", + "@hideCategories", + "@hideGroups", + "@expand", + "@summary", + "@group", + "@groupDescription", + "@category", + "@categoryDescription", +]; + +export const highlightLanguages: readonly BundledLanguage[] = [ + "bash", + "console", + "css", + "html", + "javascript", + "json", + "jsonc", + "json5", + "yaml", + "tsx", + "typescript", +]; + +export const sort: readonly string[] = [ + "kind", + "instance-first", + "alphabetical-ignoring-documents", +]; + +export const kindSortOrder: readonly EnumKeys[] = [ + "Document", + "Project", + "Module", + "Namespace", + "Enum", + "EnumMember", + "Class", + "Interface", + "TypeAlias", + + "Constructor", + "Property", + "Variable", + "Function", + "Accessor", + "Method", - "Constructor", - "Property", - "Variable", - "Function", - "Accessor", - "Method", + "Reference", +]; - "Reference", - ], - requiredToBeDocumented: [ - "Enum", - "EnumMember", - "Variable", - "Function", - "Class", - "Interface", - "Property", - "Method", - "Accessor", - "TypeAlias", - ], -}; +export const requiredToBeDocumented: readonly EnumKeys< + typeof ReflectionKind +>[] = [ + "Enum", + "EnumMember", + "Variable", + "Function", + "Class", + "Interface", + "Property", + "Method", + "Accessor", + "TypeAlias", +]; diff --git a/src/lib/utils/options/index.ts b/src/lib/utils/options/index.ts index 85ce582e5..3774aee71 100644 --- a/src/lib/utils/options/index.ts +++ b/src/lib/utils/options/index.ts @@ -36,4 +36,4 @@ export type { OutputSpecification, } from "./declaration.js"; -export { OptionDefaults } from "./defaults.js"; +export * as OptionDefaults from "./defaults.js"; diff --git a/src/lib/utils/options/sources/typedoc.ts b/src/lib/utils/options/sources/typedoc.ts index 3a7d06dc1..df2cb9a75 100644 --- a/src/lib/utils/options/sources/typedoc.ts +++ b/src/lib/utils/options/sources/typedoc.ts @@ -6,7 +6,7 @@ import { CommentStyle, type TypeDocOptionMap, } from "../declaration.js"; -import { OptionDefaults } from "../defaults.js"; +import * as OptionDefaults from "../defaults.js"; import { SORT_STRATEGIES } from "../../sort.js"; import { EntryPointStrategy } from "../../entry-point.js"; import { ReflectionKind } from "../../../models/reflections/kind.js"; diff --git a/src/lib/utils/sort.ts b/src/lib/utils/sort.ts index b918ff242..2f5180e9c 100644 --- a/src/lib/utils/sort.ts +++ b/src/lib/utils/sort.ts @@ -7,7 +7,7 @@ import { ReflectionKind } from "../models/reflections/kind.js"; import type { DeclarationReflection } from "../models/reflections/declaration.js"; import type { Options } from "./options/index.js"; import type { DocumentReflection } from "../models/index.js"; -import { OptionDefaults } from "./options/defaults.js"; +import * as OptionDefaults from "./options/defaults.js"; export const SORT_STRATEGIES = [ "source-order",