Expose OptionDefaults variable

Resolves #2640
TypeStrong · Jul 13, 2024 · 977dd19 · 977dd19
1 parent c1fb5bd
commit 977dd19
Show file tree

Hide file tree

Showing 7 changed files with 136 additions and 100 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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<typeof ReflectionKind>[];
+    excludeTags: readonly `@${string}`[];
+    blockTags: readonly `@${string}`[];
+    inlineTags: readonly `@${string}`[];
+    modifierTags: readonly `@${string}`[];
+    cascadedModifierTags: readonly `@${string}`[];
+    highlightLanguages: readonly BundledLanguage[];
+    sort: readonly string[];
+    kindSortOrder: readonly EnumKeys<typeof ReflectionKind>[];
+    requiredToBeDocumented: readonly EnumKeys<typeof ReflectionKind>[];
+} = {
+    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
@@ -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
@@ -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<Options, "addDeclaration">) {
@@ -176,27 +173,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
                 );
             }
         },
-        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<Options, "addDeclaration">) {
         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<Options, "addDeclaration">) {
         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<Options, "addDeclaration">) {
         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<Options, "addDeclaration">) {
         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<Options, "addDeclaration">) {
         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<Options, "addDeclaration">) {
         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<Options, "addDeclaration">) {
         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<Options, "addDeclaration">) {
         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<Options, "addDeclaration">) {
                 }
             }
         },
-        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
@@ -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]);
         }
     }