1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
import type {
Context,
DeclarationReflection,
EventCallback,
JSONOutput,
ProjectReflection,
SerializerComponent,
SignatureReflection,
} from 'typedoc';
import { Reflection, ReflectionKind, TypeScript } from 'typedoc';
const reflectionKindFunctionOrMethod =
ReflectionKind.Function | ReflectionKind.Method;
interface ParameterDefaultsAware extends Reflection {
implementationDefaultParameters: Array<string | undefined>;
}
/**
* TypeDoc EventCallback for EVENT_CREATE_DECLARATION events that reads the default parameters from the implementation.
*/
export const parameterDefaultReader: EventCallback = (
context: Context,
reflection: Reflection
): void => {
const symbol = context.project.getSymbolFromReflection(reflection);
if (!symbol) return;
if (
reflection.kindOf(reflectionKindFunctionOrMethod) &&
symbol.declarations?.length
) {
const lastDeclaration = symbol.declarations[symbol.declarations.length - 1];
if (TypeScript.isFunctionLike(lastDeclaration)) {
(reflection as ParameterDefaultsAware).implementationDefaultParameters =
lastDeclaration.parameters.map((param) =>
cleanParameterDefault(param.initializer?.getText())
);
}
}
};
/**
* Removes compile expressions that don't add any value for readers.
*
* @param value The default value to clean.
* @returns The cleaned default value.
*/
function cleanParameterDefault(value: string): string;
function cleanParameterDefault(value?: string): string | undefined;
function cleanParameterDefault(value?: string): string | undefined {
if (value == null) {
return undefined;
}
// Strip type casts: "'foobar' as unknown as T" => "'foobar'"
return value.replace(/ as unknown as [A-Za-z<>]+/, '');
}
/**
* Serializer that adds the `implementationDefaultParameters` to the JSON output.
*/
export class DefaultParameterAwareSerializer
implements SerializerComponent<Reflection>
{
readonly priority = 0;
supports(item: unknown): item is Reflection {
return item instanceof Reflection;
}
toObject(
item: Reflection,
obj: Partial<JSONOutput.Reflection>
): Partial<JSONOutput.Reflection> {
(obj as unknown as ParameterDefaultsAware).implementationDefaultParameters =
(item as ParameterDefaultsAware).implementationDefaultParameters;
return obj;
}
}
/**
* Replaces all methods' last signature's parameter's default value with the default value read from the implementation.
*
* @param project The project to patch.
*/
export function patchProjectParameterDefaults(
project: ProjectReflection
): void {
const functionOrMethods = project.getReflectionsByKind(
reflectionKindFunctionOrMethod
) as DeclarationReflection[];
for (const functionOrMethod of functionOrMethods) {
patchMethodParameterDefaults(functionOrMethod);
}
}
/**
* Replaces the last signature's parameter's default value with the default value read from the implementation.
*
* @param method The method to patch.
*/
function patchMethodParameterDefaults(method: DeclarationReflection): void {
const signatures = method.signatures;
const signature = signatures?.[signatures.length - 1];
const parameterDefaults = (method as unknown as ParameterDefaultsAware)
.implementationDefaultParameters;
if (signature && parameterDefaults) {
patchSignatureParameterDefaults(signature, parameterDefaults);
}
}
/**
* Replaces the given signature's parameter's default value with the given default values.
*
* @param signature The signature to patch.
* @param parameterDefaults The defaults to add.
*/
function patchSignatureParameterDefaults(
signature: SignatureReflection,
parameterDefaults: Array<string | undefined>
): void {
const signatureParameters =
signature.parameters ?? Array.from({ length: parameterDefaults.length });
if (signatureParameters.length !== parameterDefaults.length) {
throw new Error('Unexpected parameter length mismatch');
}
signatureParameters.forEach(
(param, index) =>
(param.defaultValue = parameterDefaults[index] || param.defaultValue)
);
}
|
