Skip to content

Commit 977dd19

Browse files
Gerrit0Gerrit0
committed
Expose OptionDefaults variable
Resolves #2640
1 parent c1fb5bd commit 977dd19

File tree

7 files changed

+136
-100
lines changed

7 files changed

+136
-100
lines changed

‎CHANGELOG.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Unreleased
22

3+
### Features
4+
5+
- TypeDoc now exposes array option defaults under `OptionDefaults`, #2640.
6+
37
### Bug Fixes
48

59
- Constructor parameters which share a name with a property on a parent class will no longer inherit the comment on the parent class, #2636.

‎src/index.ts

+1
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ export {
6060
LogLevel,
6161
Logger,
6262
Options,
63+
OptionDefaults,
6364
PackageJsonReader,
6465
ParameterHint,
6566
ParameterType,

‎src/lib/utils/index.ts

+1
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ export {
3535
ParameterType,
3636
TSConfigReader,
3737
TypeDocReader,
38+
OptionDefaults,
3839
} from "./options";
3940
export type {
4041
ArrayDeclarationOption,

‎src/lib/utils/options/defaults.ts

+111
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
import type { BundledLanguage } from "shiki" with { "resolution-mode": "import" };
2+
import * as TagDefaults from "./tsdoc-defaults";
3+
import type { EnumKeys } from "../enum";
4+
import type { ReflectionKind } from "../../models/index";
5+
6+
/**
7+
* Default values for TypeDoc options. This object should not be modified.
8+
*
9+
* @privateRemarks
10+
* These are declared here, rather than within the option declaration, so that
11+
* they can be exposed as a part of the public API. The unfortunate type declaration
12+
* is to control the type which appears in the generated documentation.
13+
*/
14+
export const OptionDefaults: {
15+
excludeNotDocumentedKinds: readonly EnumKeys<typeof ReflectionKind>[];
16+
excludeTags: readonly `@${string}`[];
17+
blockTags: readonly `@${string}`[];
18+
inlineTags: readonly `@${string}`[];
19+
modifierTags: readonly `@${string}`[];
20+
cascadedModifierTags: readonly `@${string}`[];
21+
highlightLanguages: readonly BundledLanguage[];
22+
sort: readonly string[];
23+
kindSortOrder: readonly EnumKeys<typeof ReflectionKind>[];
24+
requiredToBeDocumented: readonly EnumKeys<typeof ReflectionKind>[];
25+
} = {
26+
excludeNotDocumentedKinds: [
27+
"Module",
28+
"Namespace",
29+
"Enum",
30+
// Not including enum member here by default
31+
"Variable",
32+
"Function",
33+
"Class",
34+
"Interface",
35+
"Constructor",
36+
"Property",
37+
"Method",
38+
"CallSignature",
39+
"IndexSignature",
40+
"ConstructorSignature",
41+
"Accessor",
42+
"GetSignature",
43+
"SetSignature",
44+
"TypeAlias",
45+
"Reference",
46+
],
47+
excludeTags: [
48+
"@override",
49+
"@virtual",
50+
"@privateRemarks",
51+
"@satisfies",
52+
"@overload",
53+
],
54+
blockTags: TagDefaults.blockTags,
55+
inlineTags: TagDefaults.inlineTags,
56+
modifierTags: TagDefaults.modifierTags,
57+
cascadedModifierTags: ["@alpha", "@beta", "@experimental"],
58+
highlightLanguages: [
59+
"bash",
60+
"console",
61+
"css",
62+
"html",
63+
"javascript",
64+
"json",
65+
"jsonc",
66+
"json5",
67+
"tsx",
68+
"typescript",
69+
],
70+
sort: ["kind", "instance-first", "alphabetical"],
71+
kindSortOrder: [
72+
"Document",
73+
"Reference",
74+
"Project",
75+
"Module",
76+
"Namespace",
77+
"Enum",
78+
"EnumMember",
79+
"Class",
80+
"Interface",
81+
"TypeAlias",
82+
83+
"Constructor",
84+
"Property",
85+
"Variable",
86+
"Function",
87+
"Accessor",
88+
"Method",
89+
90+
"Parameter",
91+
"TypeParameter",
92+
"TypeLiteral",
93+
"CallSignature",
94+
"ConstructorSignature",
95+
"IndexSignature",
96+
"GetSignature",
97+
"SetSignature",
98+
],
99+
requiredToBeDocumented: [
100+
"Enum",
101+
"EnumMember",
102+
"Variable",
103+
"Function",
104+
"Class",
105+
"Interface",
106+
"Property",
107+
"Method",
108+
"Accessor",
109+
"TypeAlias",
110+
],
111+
};

‎src/lib/utils/options/index.ts

+2
Original file line numberDiff line numberDiff line change
@@ -34,3 +34,5 @@ export type {
3434
ManuallyValidatedOption,
3535
JsDocCompatibility,
3636
} from "./declaration";
37+
38+
export { OptionDefaults } from "./defaults";

‎src/lib/utils/options/sources/typedoc.ts

+13-68
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,14 @@ import { SORT_STRATEGIES } from "../../sort";
1010
import { EntryPointStrategy } from "../../entry-point";
1111
import { ReflectionKind } from "../../../models/reflections/kind";
1212
import * as Validation from "../../validation";
13-
import { blockTags, inlineTags, modifierTags } from "../tsdoc-defaults";
1413
import { getEnumKeys } from "../../enum";
15-
import type {
16-
BundledLanguage,
17-
BundledTheme,
18-
} from "shiki" with { "resolution-mode": "import" };
14+
import type { BundledTheme } from "shiki" with { "resolution-mode": "import" };
1915
import {
2016
getSupportedLanguagesWithoutAliases,
2117
getSupportedThemes,
2218
} from "../../highlighter";
2319
import { setDifference } from "../../set";
20+
import { OptionDefaults } from "../defaults";
2421

2522
// For convenience, added in the same order as they are documented on the website.
2623
export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
@@ -176,27 +173,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
176173
);
177174
}
178175
},
179-
defaultValue: [
180-
ReflectionKind[ReflectionKind.Module],
181-
ReflectionKind[ReflectionKind.Namespace],
182-
ReflectionKind[ReflectionKind.Enum],
183-
// Not including enum member here by default
184-
ReflectionKind[ReflectionKind.Variable],
185-
ReflectionKind[ReflectionKind.Function],
186-
ReflectionKind[ReflectionKind.Class],
187-
ReflectionKind[ReflectionKind.Interface],
188-
ReflectionKind[ReflectionKind.Constructor],
189-
ReflectionKind[ReflectionKind.Property],
190-
ReflectionKind[ReflectionKind.Method],
191-
ReflectionKind[ReflectionKind.CallSignature],
192-
ReflectionKind[ReflectionKind.IndexSignature],
193-
ReflectionKind[ReflectionKind.ConstructorSignature],
194-
ReflectionKind[ReflectionKind.Accessor],
195-
ReflectionKind[ReflectionKind.GetSignature],
196-
ReflectionKind[ReflectionKind.SetSignature],
197-
ReflectionKind[ReflectionKind.TypeAlias],
198-
ReflectionKind[ReflectionKind.Reference],
199-
],
176+
defaultValue: OptionDefaults.excludeNotDocumentedKinds,
200177
});
201178
options.addDeclaration({
202179
name: "excludeInternal",
@@ -331,18 +308,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
331308
name: "highlightLanguages",
332309
help: (i18n) => i18n.help_highlightLanguages(),
333310
type: ParameterType.Array,
334-
defaultValue: [
335-
"bash",
336-
"console",
337-
"css",
338-
"html",
339-
"javascript",
340-
"json",
341-
"jsonc",
342-
"json5",
343-
"tsx",
344-
"typescript",
345-
] satisfies BundledLanguage[],
311+
defaultValue: OptionDefaults.highlightLanguages,
346312
validate(value, i18n) {
347313
const invalid = setDifference(
348314
value,
@@ -441,13 +407,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
441407
name: "excludeTags",
442408
help: (i18n) => i18n.help_excludeTags(),
443409
type: ParameterType.Array,
444-
defaultValue: [
445-
"@override",
446-
"@virtual",
447-
"@privateRemarks",
448-
"@satisfies",
449-
"@overload",
450-
],
410+
defaultValue: OptionDefaults.excludeTags,
451411
validate(value, i18n) {
452412
if (!Validation.validate([Array, Validation.isTagString], value)) {
453413
throw new Error(
@@ -716,7 +676,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
716676
name: "blockTags",
717677
help: (i18n) => i18n.help_blockTags(),
718678
type: ParameterType.Array,
719-
defaultValue: blockTags,
679+
defaultValue: OptionDefaults.blockTags,
720680
validate(value, i18n) {
721681
if (!Validation.validate([Array, Validation.isTagString], value)) {
722682
throw new Error(
@@ -729,7 +689,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
729689
name: "inlineTags",
730690
help: (i18n) => i18n.help_inlineTags(),
731691
type: ParameterType.Array,
732-
defaultValue: inlineTags,
692+
defaultValue: OptionDefaults.inlineTags,
733693
validate(value, i18n) {
734694
if (!Validation.validate([Array, Validation.isTagString], value)) {
735695
throw new Error(
@@ -742,7 +702,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
742702
name: "modifierTags",
743703
help: (i18n) => i18n.help_modifierTags(),
744704
type: ParameterType.Array,
745-
defaultValue: modifierTags,
705+
defaultValue: OptionDefaults.modifierTags,
746706
validate(value, i18n) {
747707
if (!Validation.validate([Array, Validation.isTagString], value)) {
748708
throw new Error(
@@ -755,7 +715,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
755715
name: "cascadedModifierTags",
756716
help: (i18n) => i18n.help_modifierTags(),
757717
type: ParameterType.Array,
758-
defaultValue: ["@alpha", "@beta", "@experimental"],
718+
defaultValue: OptionDefaults.cascadedModifierTags,
759719
validate(value, i18n) {
760720
if (!Validation.validate([Array, Validation.isTagString], value)) {
761721
throw new Error(
@@ -797,7 +757,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
797757
name: "sort",
798758
help: (i18n) => i18n.help_sort(),
799759
type: ParameterType.Array,
800-
defaultValue: ["kind", "instance-first", "alphabetical"],
760+
defaultValue: OptionDefaults.sort,
801761
validate(value, i18n) {
802762
const invalid = new Set(value);
803763
for (const v of SORT_STRATEGIES) {
@@ -827,18 +787,14 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
827787
type: ParameterType.Array,
828788
defaultValue: [],
829789
validate(value, i18n) {
830-
const invalid = new Set(value);
831-
const valid = getEnumKeys(ReflectionKind);
832-
for (const v of valid) {
833-
invalid.delete(v);
834-
}
790+
const invalid = setDifference(value, getEnumKeys(ReflectionKind));
835791

836792
if (invalid.size !== 0) {
837793
throw new Error(
838794
i18n.option_0_specified_1_but_only_2_is_valid(
839795
`kindSortOrder`,
840796
Array.from(invalid).join(", "),
841-
valid.join(", "),
797+
getEnumKeys(ReflectionKind).join(", "),
842798
),
843799
);
844800
}
@@ -929,18 +885,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
929885
}
930886
}
931887
},
932-
defaultValue: [
933-
ReflectionKind[ReflectionKind.Enum],
934-
ReflectionKind[ReflectionKind.EnumMember],
935-
ReflectionKind[ReflectionKind.Variable],
936-
ReflectionKind[ReflectionKind.Function],
937-
ReflectionKind[ReflectionKind.Class],
938-
ReflectionKind[ReflectionKind.Interface],
939-
ReflectionKind[ReflectionKind.Property],
940-
ReflectionKind[ReflectionKind.Method],
941-
ReflectionKind[ReflectionKind.Accessor],
942-
ReflectionKind[ReflectionKind.TypeAlias],
943-
],
888+
defaultValue: OptionDefaults.requiredToBeDocumented,
944889
});
945890

946891
options.addDeclaration({

‎src/lib/utils/sort.ts

+4-32
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import { ReflectionKind } from "../models/reflections/kind";
77
import type { DeclarationReflection } from "../models/reflections/declaration";
88
import type { Options } from "./options";
99
import type { DocumentReflection } from "../models";
10+
import { OptionDefaults } from "./options/defaults";
1011

1112
export const SORT_STRATEGIES = [
1213
"source-order",
@@ -27,35 +28,6 @@ export const SORT_STRATEGIES = [
2728

2829
export type SortStrategy = (typeof SORT_STRATEGIES)[number];
2930

30-
const defaultKindSortOrder = [
31-
ReflectionKind.Document,
32-
ReflectionKind.Reference,
33-
ReflectionKind.Project,
34-
ReflectionKind.Module,
35-
ReflectionKind.Namespace,
36-
ReflectionKind.Enum,
37-
ReflectionKind.EnumMember,
38-
ReflectionKind.Class,
39-
ReflectionKind.Interface,
40-
ReflectionKind.TypeAlias,
41-
42-
ReflectionKind.Constructor,
43-
ReflectionKind.Property,
44-
ReflectionKind.Variable,
45-
ReflectionKind.Function,
46-
ReflectionKind.Accessor,
47-
ReflectionKind.Method,
48-
49-
ReflectionKind.Parameter,
50-
ReflectionKind.TypeParameter,
51-
ReflectionKind.TypeLiteral,
52-
ReflectionKind.CallSignature,
53-
ReflectionKind.ConstructorSignature,
54-
ReflectionKind.IndexSignature,
55-
ReflectionKind.GetSignature,
56-
ReflectionKind.SetSignature,
57-
] as const;
58-
5931
// Return true if a < b
6032
const sorts: Record<
6133
SortStrategy,
@@ -193,9 +165,9 @@ export function getSortFunction(opts: Options) {
193165
.getValue("kindSortOrder")
194166
.map((k) => ReflectionKind[k]);
195167

196-
for (const kind of defaultKindSortOrder) {
197-
if (!kindSortOrder.includes(kind)) {
198-
kindSortOrder.push(kind);
168+
for (const kind of OptionDefaults.kindSortOrder) {
169+
if (!kindSortOrder.includes(ReflectionKind[kind])) {
170+
kindSortOrder.push(ReflectionKind[kind]);
199171
}
200172
}
201173

0 commit comments

Comments
 (0)