Minor improvements to API docs

TypeStrong · Nov 29, 2024 · c3842c1 · c3842c1
1 parent 663ce54
commit c3842c1
Show file tree

Hide file tree

Showing 5 changed files with 117 additions and 115 deletions.
diff --git 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
@@ -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<typeof ReflectionKind>[];
-    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<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",
-        "@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<typeof ReflectionKind>[] = [
+    "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
@@ -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
@@ -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
@@ -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",