From 977dd1974e1fcfde3d74593a4b996bab0afe1577 Mon Sep 17 00:00:00 2001 From: Gerrit Birkeland Date: Sat, 13 Jul 2024 12:58:07 -0600 Subject: [PATCH] Expose OptionDefaults variable Resolves #2640 --- CHANGELOG.md | 4 + src/index.ts | 1 + src/lib/utils/index.ts | 1 + src/lib/utils/options/defaults.ts | 111 +++++++++++++++++++++++ src/lib/utils/options/index.ts | 2 + src/lib/utils/options/sources/typedoc.ts | 81 +++-------------- src/lib/utils/sort.ts | 36 +------- 7 files changed, 136 insertions(+), 100 deletions(-) create mode 100644 src/lib/utils/options/defaults.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index b437870b4..2113ba77f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Unreleased +### Features + +- TypeDoc now exposes array option defaults under `OptionDefaults`, #2640. + ### Bug Fixes - Constructor parameters which share a name with a property on a parent class will no longer inherit the comment on the parent class, #2636. diff --git a/src/index.ts b/src/index.ts index 9a20cec8f..8b4fcb35d 100644 --- a/src/index.ts +++ b/src/index.ts @@ -60,6 +60,7 @@ export { LogLevel, Logger, Options, + OptionDefaults, PackageJsonReader, ParameterHint, ParameterType, diff --git a/src/lib/utils/index.ts b/src/lib/utils/index.ts index 318b68f7c..9dbb4cfb4 100644 --- a/src/lib/utils/index.ts +++ b/src/lib/utils/index.ts @@ -35,6 +35,7 @@ export { ParameterType, TSConfigReader, TypeDocReader, + OptionDefaults, } from "./options"; export type { ArrayDeclarationOption, diff --git a/src/lib/utils/options/defaults.ts b/src/lib/utils/options/defaults.ts new file mode 100644 index 000000000..ae816fa20 --- /dev/null +++ b/src/lib/utils/options/defaults.ts @@ -0,0 +1,111 @@ +import type { BundledLanguage } from "shiki" with { "resolution-mode": "import" }; +import * as TagDefaults from "./tsdoc-defaults"; +import type { EnumKeys } from "../enum"; +import type { ReflectionKind } from "../../models/index"; + +/** + * 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}`[]; + 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", + ], + blockTags: TagDefaults.blockTags, + inlineTags: TagDefaults.inlineTags, + modifierTags: TagDefaults.modifierTags, + cascadedModifierTags: ["@alpha", "@beta", "@experimental"], + highlightLanguages: [ + "bash", + "console", + "css", + "html", + "javascript", + "json", + "jsonc", + "json5", + "tsx", + "typescript", + ], + sort: ["kind", "instance-first", "alphabetical"], + kindSortOrder: [ + "Document", + "Reference", + "Project", + "Module", + "Namespace", + "Enum", + "EnumMember", + "Class", + "Interface", + "TypeAlias", + + "Constructor", + "Property", + "Variable", + "Function", + "Accessor", + "Method", + + "Parameter", + "TypeParameter", + "TypeLiteral", + "CallSignature", + "ConstructorSignature", + "IndexSignature", + "GetSignature", + "SetSignature", + ], + requiredToBeDocumented: [ + "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 8f5308f5d..c906d025f 100644 --- a/src/lib/utils/options/index.ts +++ b/src/lib/utils/options/index.ts @@ -34,3 +34,5 @@ export type { ManuallyValidatedOption, JsDocCompatibility, } from "./declaration"; + +export { OptionDefaults } from "./defaults"; diff --git a/src/lib/utils/options/sources/typedoc.ts b/src/lib/utils/options/sources/typedoc.ts index 2f6d02e8f..8676ad79e 100644 --- a/src/lib/utils/options/sources/typedoc.ts +++ b/src/lib/utils/options/sources/typedoc.ts @@ -10,17 +10,14 @@ import { SORT_STRATEGIES } from "../../sort"; import { EntryPointStrategy } from "../../entry-point"; import { ReflectionKind } from "../../../models/reflections/kind"; import * as Validation from "../../validation"; -import { blockTags, inlineTags, modifierTags } from "../tsdoc-defaults"; import { getEnumKeys } from "../../enum"; -import type { - BundledLanguage, - BundledTheme, -} from "shiki" with { "resolution-mode": "import" }; +import type { BundledTheme } from "shiki" with { "resolution-mode": "import" }; import { getSupportedLanguagesWithoutAliases, getSupportedThemes, } from "../../highlighter"; import { setDifference } from "../../set"; +import { OptionDefaults } from "../defaults"; // For convenience, added in the same order as they are documented on the website. export function addTypeDocOptions(options: Pick) { @@ -176,27 +173,7 @@ export function addTypeDocOptions(options: Pick) { ); } }, - defaultValue: [ - ReflectionKind[ReflectionKind.Module], - ReflectionKind[ReflectionKind.Namespace], - ReflectionKind[ReflectionKind.Enum], - // Not including enum member here by default - ReflectionKind[ReflectionKind.Variable], - ReflectionKind[ReflectionKind.Function], - ReflectionKind[ReflectionKind.Class], - ReflectionKind[ReflectionKind.Interface], - ReflectionKind[ReflectionKind.Constructor], - ReflectionKind[ReflectionKind.Property], - ReflectionKind[ReflectionKind.Method], - ReflectionKind[ReflectionKind.CallSignature], - ReflectionKind[ReflectionKind.IndexSignature], - ReflectionKind[ReflectionKind.ConstructorSignature], - ReflectionKind[ReflectionKind.Accessor], - ReflectionKind[ReflectionKind.GetSignature], - ReflectionKind[ReflectionKind.SetSignature], - ReflectionKind[ReflectionKind.TypeAlias], - ReflectionKind[ReflectionKind.Reference], - ], + defaultValue: OptionDefaults.excludeNotDocumentedKinds, }); options.addDeclaration({ name: "excludeInternal", @@ -331,18 +308,7 @@ export function addTypeDocOptions(options: Pick) { name: "highlightLanguages", help: (i18n) => i18n.help_highlightLanguages(), type: ParameterType.Array, - defaultValue: [ - "bash", - "console", - "css", - "html", - "javascript", - "json", - "jsonc", - "json5", - "tsx", - "typescript", - ] satisfies BundledLanguage[], + defaultValue: OptionDefaults.highlightLanguages, validate(value, i18n) { const invalid = setDifference( value, @@ -441,13 +407,7 @@ export function addTypeDocOptions(options: Pick) { name: "excludeTags", help: (i18n) => i18n.help_excludeTags(), type: ParameterType.Array, - defaultValue: [ - "@override", - "@virtual", - "@privateRemarks", - "@satisfies", - "@overload", - ], + defaultValue: OptionDefaults.excludeTags, validate(value, i18n) { if (!Validation.validate([Array, Validation.isTagString], value)) { throw new Error( @@ -716,7 +676,7 @@ export function addTypeDocOptions(options: Pick) { name: "blockTags", help: (i18n) => i18n.help_blockTags(), type: ParameterType.Array, - defaultValue: blockTags, + defaultValue: OptionDefaults.blockTags, validate(value, i18n) { if (!Validation.validate([Array, Validation.isTagString], value)) { throw new Error( @@ -729,7 +689,7 @@ export function addTypeDocOptions(options: Pick) { name: "inlineTags", help: (i18n) => i18n.help_inlineTags(), type: ParameterType.Array, - defaultValue: inlineTags, + defaultValue: OptionDefaults.inlineTags, validate(value, i18n) { if (!Validation.validate([Array, Validation.isTagString], value)) { throw new Error( @@ -742,7 +702,7 @@ export function addTypeDocOptions(options: Pick) { name: "modifierTags", help: (i18n) => i18n.help_modifierTags(), type: ParameterType.Array, - defaultValue: modifierTags, + defaultValue: OptionDefaults.modifierTags, validate(value, i18n) { if (!Validation.validate([Array, Validation.isTagString], value)) { throw new Error( @@ -755,7 +715,7 @@ export function addTypeDocOptions(options: Pick) { name: "cascadedModifierTags", help: (i18n) => i18n.help_modifierTags(), type: ParameterType.Array, - defaultValue: ["@alpha", "@beta", "@experimental"], + defaultValue: OptionDefaults.cascadedModifierTags, validate(value, i18n) { if (!Validation.validate([Array, Validation.isTagString], value)) { throw new Error( @@ -797,7 +757,7 @@ export function addTypeDocOptions(options: Pick) { name: "sort", help: (i18n) => i18n.help_sort(), type: ParameterType.Array, - defaultValue: ["kind", "instance-first", "alphabetical"], + defaultValue: OptionDefaults.sort, validate(value, i18n) { const invalid = new Set(value); for (const v of SORT_STRATEGIES) { @@ -827,18 +787,14 @@ export function addTypeDocOptions(options: Pick) { type: ParameterType.Array, defaultValue: [], validate(value, i18n) { - const invalid = new Set(value); - const valid = getEnumKeys(ReflectionKind); - for (const v of valid) { - invalid.delete(v); - } + const invalid = setDifference(value, getEnumKeys(ReflectionKind)); if (invalid.size !== 0) { throw new Error( i18n.option_0_specified_1_but_only_2_is_valid( `kindSortOrder`, Array.from(invalid).join(", "), - valid.join(", "), + getEnumKeys(ReflectionKind).join(", "), ), ); } @@ -929,18 +885,7 @@ export function addTypeDocOptions(options: Pick) { } } }, - defaultValue: [ - ReflectionKind[ReflectionKind.Enum], - ReflectionKind[ReflectionKind.EnumMember], - ReflectionKind[ReflectionKind.Variable], - ReflectionKind[ReflectionKind.Function], - ReflectionKind[ReflectionKind.Class], - ReflectionKind[ReflectionKind.Interface], - ReflectionKind[ReflectionKind.Property], - ReflectionKind[ReflectionKind.Method], - ReflectionKind[ReflectionKind.Accessor], - ReflectionKind[ReflectionKind.TypeAlias], - ], + defaultValue: OptionDefaults.requiredToBeDocumented, }); options.addDeclaration({ diff --git a/src/lib/utils/sort.ts b/src/lib/utils/sort.ts index 4770d40ff..8fda9f003 100644 --- a/src/lib/utils/sort.ts +++ b/src/lib/utils/sort.ts @@ -7,6 +7,7 @@ import { ReflectionKind } from "../models/reflections/kind"; import type { DeclarationReflection } from "../models/reflections/declaration"; import type { Options } from "./options"; import type { DocumentReflection } from "../models"; +import { OptionDefaults } from "./options/defaults"; export const SORT_STRATEGIES = [ "source-order", @@ -27,35 +28,6 @@ export const SORT_STRATEGIES = [ export type SortStrategy = (typeof SORT_STRATEGIES)[number]; -const defaultKindSortOrder = [ - ReflectionKind.Document, - ReflectionKind.Reference, - ReflectionKind.Project, - ReflectionKind.Module, - ReflectionKind.Namespace, - ReflectionKind.Enum, - ReflectionKind.EnumMember, - ReflectionKind.Class, - ReflectionKind.Interface, - ReflectionKind.TypeAlias, - - ReflectionKind.Constructor, - ReflectionKind.Property, - ReflectionKind.Variable, - ReflectionKind.Function, - ReflectionKind.Accessor, - ReflectionKind.Method, - - ReflectionKind.Parameter, - ReflectionKind.TypeParameter, - ReflectionKind.TypeLiteral, - ReflectionKind.CallSignature, - ReflectionKind.ConstructorSignature, - ReflectionKind.IndexSignature, - ReflectionKind.GetSignature, - ReflectionKind.SetSignature, -] as const; - // Return true if a < b const sorts: Record< SortStrategy, @@ -193,9 +165,9 @@ export function getSortFunction(opts: Options) { .getValue("kindSortOrder") .map((k) => ReflectionKind[k]); - for (const kind of defaultKindSortOrder) { - if (!kindSortOrder.includes(kind)) { - kindSortOrder.push(kind); + for (const kind of OptionDefaults.kindSortOrder) { + if (!kindSortOrder.includes(ReflectionKind[kind])) { + kindSortOrder.push(ReflectionKind[kind]); } }