Skip to content

Commit 0b8cac0

Browse files
Shinigami92Shinigami92
authored
Merge branch 'main' into refactor-datatype-number
2 parents dae5260 + 5aa8eeb commit 0b8cac0

File tree

5 files changed

+267
-31
lines changed

5 files changed

+267
-31
lines changed

‎scripts/apidoc.ts

Lines changed: 3 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,14 @@
11
import { resolve } from 'path';
2-
import * as TypeDoc from 'typedoc';
32
import { writeApiPagesIndex } from './apidoc/apiDocsWriter';
43
import { processDirectMethods } from './apidoc/directMethods';
54
import { processModuleMethods } from './apidoc/moduleMethods';
6-
import {
7-
DefaultParameterAwareSerializer,
8-
parameterDefaultReader,
9-
patchProjectParameterDefaults,
10-
} from './apidoc/parameterDefaults';
115
import type { PageIndex } from './apidoc/utils';
12-
import { pathOutputDir } from './apidoc/utils';
6+
import { newTypeDocApp, patchProject, pathOutputDir } from './apidoc/utils';
137

148
const pathOutputJson = resolve(pathOutputDir, 'typedoc.json');
159

1610
async function build(): Promise<void> {
17-
const app = new TypeDoc.Application();
18-
19-
app.options.addReader(new TypeDoc.TSConfigReader());
20-
// If you want TypeDoc to load typedoc.json files
21-
//app.options.addReader(new TypeDoc.TypeDocReader());
22-
23-
// Read parameter defaults
24-
app.converter.on(
25-
TypeDoc.Converter.EVENT_CREATE_DECLARATION,
26-
parameterDefaultReader
27-
);
28-
// Add to debug json output
29-
app.serializer.addSerializer(new DefaultParameterAwareSerializer(undefined));
11+
const app = newTypeDocApp();
3012

3113
app.bootstrap({
3214
entryPoints: ['src/index.ts'],
@@ -36,15 +18,10 @@ async function build(): Promise<void> {
3618

3719
const project = app.convert();
3820

39-
if (!project) {
40-
// Project may not have converted correctly
41-
return;
42-
}
4321
// Useful for manually analyzing the content
4422
await app.generateJson(project, pathOutputJson);
45-
console.log(pathOutputDir);
4623

47-
patchProjectParameterDefaults(project);
24+
patchProject(project);
4825

4926
const modulesPages: PageIndex = [];
5027
modulesPages.push({ text: 'Localization', link: '/api/localization.html' });

‎scripts/apidoc/utils.ts

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,46 @@
11
import { resolve } from 'node:path';
2+
import * as TypeDoc from 'typedoc';
3+
import {
4+
DefaultParameterAwareSerializer,
5+
parameterDefaultReader,
6+
patchProjectParameterDefaults,
7+
} from './parameterDefaults';
28

39
export type Page = { text: string; link: string };
410
export type PageIndex = Array<Page>;
511

612
const pathRoot = resolve(__dirname, '..', '..');
713
export const pathDocsDir = resolve(pathRoot, 'docs');
814
export const pathOutputDir = resolve(pathDocsDir, 'api');
15+
16+
/**
17+
* Creates and configures a new typedoc application.
18+
*/
19+
export function newTypeDocApp(): TypeDoc.Application {
20+
const app = new TypeDoc.Application();
21+
22+
app.options.addReader(new TypeDoc.TSConfigReader());
23+
// If you want TypeDoc to load typedoc.json files
24+
//app.options.addReader(new TypeDoc.TypeDocReader());
25+
26+
// Read parameter defaults
27+
app.converter.on(
28+
TypeDoc.Converter.EVENT_CREATE_DECLARATION,
29+
parameterDefaultReader
30+
);
31+
// Add to debug json output
32+
app.serializer.addSerializer(new DefaultParameterAwareSerializer(undefined));
33+
34+
return app;
35+
}
36+
37+
/**
38+
* Apply our patches to the generated typedoc data.
39+
*
40+
* This is moved to a separate method to allow printing/saving the original content before patching it.
41+
*
42+
* @param project The project to patch.
43+
*/
44+
export function patchProject(project: TypeDoc.ProjectReflection): void {
45+
patchProjectParameterDefaults(project);
46+
}

‎test/scripts/apidoc/signature.example.ts

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,63 @@
1+
/**
2+
* Parameter options type with default from signature.
3+
*/
4+
export type ParameterOptionsTypeA = {
5+
/**
6+
* Options value.
7+
*/
8+
value?: number;
9+
};
10+
11+
/**
12+
* Parameter options type with default from jsdocs. Defaults to `{value: 0}`.
13+
*/
14+
export type ParameterOptionsTypeB = {
15+
/**
16+
* Options value.
17+
*/
18+
value?: number;
19+
};
20+
21+
/**
22+
* Parameter options type with default from inner jsdocs.
23+
*/
24+
export type ParameterOptionsTypeC = {
25+
/**
26+
* Options value. Defaults to `0`.
27+
*/
28+
value?: number;
29+
};
30+
31+
/**
32+
* Parameter options type with default from signature.
33+
*/
34+
export interface ParameterOptionsInterfaceA {
35+
/**
36+
* Options value.
37+
*/
38+
value?: number;
39+
}
40+
41+
/**
42+
* Parameter options type with default from jsdocs.
43+
*/
44+
export interface ParameterOptionsInterfaceB {
45+
/**
46+
* Options value.
47+
*/
48+
value?: number;
49+
}
50+
51+
/**
52+
* Parameter options type with default from inner jsdocs.
53+
*/
54+
export interface ParameterOptionsInterfaceC {
55+
/**
56+
* Options value. Defaults to `0`.
57+
*/
58+
value?: number;
59+
}
60+
161
export class SignatureTest {
262
/**
363
* Test with no parameters.
@@ -71,6 +131,60 @@ export class SignatureTest {
71131
return options.c ? options.a : +options.b;
72132
}
73133

134+
/**
135+
* Test with a function parameters (inline types) with defaults.
136+
*
137+
* @param a Parameter with signature default.
138+
* @param a.value The number parameter.
139+
* @param b Parameter with jsdocs default. Defaults to `{ value: 1 }`.
140+
* @param b.value The boolean parameter.
141+
* @param c Parameter with inner jsdocs default.
142+
* @param c.value The boolean parameter. Defaults to `2`.
143+
*/
144+
optionsInlineParamMethodWithDefaults(
145+
a: { value?: number } = { value: 1 },
146+
b: { value?: number },
147+
c: { value?: number }
148+
): number {
149+
return a.value ?? b.value ?? c.value ?? -1;
150+
}
151+
152+
/**
153+
* Test with a function parameters with defaults.
154+
*
155+
* @param a Parameter with signature default.
156+
* @param a.value The number parameter.
157+
* @param b Parameter with jsdocs default. Defaults to `{ value: 1 }`.
158+
* @param b.value The boolean parameter.
159+
* @param c Parameter with inner jsdocs default.
160+
* @param c.value The boolean parameter. Defaults to `2`.
161+
*/
162+
optionsTypeParamMethodWithDefaults(
163+
a: ParameterOptionsTypeA = { value: 1 },
164+
b: ParameterOptionsTypeB,
165+
c: ParameterOptionsTypeC
166+
): number {
167+
return a.value ?? b.value ?? c.value ?? -1;
168+
}
169+
170+
/**
171+
* Test with a function parameters with defaults.
172+
*
173+
* @param a Parameter with signature default.
174+
* @param a.value The number parameter.
175+
* @param b Parameter with jsdocs default. Defaults to `{ value: 1 }`.
176+
* @param b.value The boolean parameter.
177+
* @param c Parameter with inner jsdocs default.
178+
* @param c.value The boolean parameter. Defaults to `2`.
179+
*/
180+
optionsInterfaceParamMethodWithDefaults(
181+
a: ParameterOptionsInterfaceA = { value: 1 },
182+
b: ParameterOptionsInterfaceB,
183+
c: ParameterOptionsInterfaceC
184+
): number {
185+
return a.value ?? b.value ?? c.value ?? -1;
186+
}
187+
74188
/**
75189
* Test with example marker.
76190
*

‎test/scripts/apidoc/signature.expected.json

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,106 @@
8989
"deprecated": false,
9090
"seeAlsos": []
9191
},
92+
"optionsInlineParamMethodWithDefaults": {
93+
"name": "optionsInlineParamMethodWithDefaults",
94+
"title": "Options Inline Param Method With Defaults",
95+
"description": "<p>Test with a function parameters (inline types) with defaults.</p>\n",
96+
"parameters": [
97+
{
98+
"name": "a",
99+
"type": "{ ... }",
100+
"default": "{ value: 1 }",
101+
"description": "<p>Parameter with signature default.</p>\n"
102+
},
103+
{
104+
"name": "a.value?",
105+
"type": "number",
106+
"description": "<p>The number parameter.</p>\n"
107+
},
108+
{
109+
"name": "b",
110+
"type": "{ ... }",
111+
"default": "{ value: 1 }",
112+
"description": "<p>Parameter with jsdocs default.</p>\n"
113+
},
114+
{
115+
"name": "b.value?",
116+
"type": "number",
117+
"description": "<p>The boolean parameter.</p>\n"
118+
},
119+
{
120+
"name": "c",
121+
"type": "{ ... }",
122+
"description": "<p>Parameter with inner jsdocs default.</p>\n"
123+
},
124+
{
125+
"name": "c.value?",
126+
"type": "number",
127+
"default": "2",
128+
"description": "<p>The boolean parameter.</p>\n"
129+
}
130+
],
131+
"returns": "number",
132+
"examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">optionsInlineParamMethodWithDefaults</span><span class=\"token punctuation\">(</span>a<span class=\"token operator\">:</span> <span class=\"token punctuation\">{</span>\n value<span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n<span class=\"token punctuation\">}</span> <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> b<span class=\"token operator\">:</span> <span class=\"token punctuation\">{</span>\n value<span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n<span class=\"token punctuation\">}</span> <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> c<span class=\"token operator\">:</span> <span class=\"token punctuation\">{</span>\n value<span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n<span class=\"token punctuation\">}</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
133+
"deprecated": false,
134+
"seeAlsos": []
135+
},
136+
"optionsInterfaceParamMethodWithDefaults": {
137+
"name": "optionsInterfaceParamMethodWithDefaults",
138+
"title": "Options Interface Param Method With Defaults",
139+
"description": "<p>Test with a function parameters with defaults.</p>\n",
140+
"parameters": [
141+
{
142+
"name": "a",
143+
"type": "ParameterOptionsInterfaceA",
144+
"default": "{ value: 1 }",
145+
"description": "<p>Parameter with signature default.</p>\n"
146+
},
147+
{
148+
"name": "b",
149+
"type": "ParameterOptionsInterfaceB",
150+
"default": "{ value: 1 }",
151+
"description": "<p>Parameter with jsdocs default.</p>\n"
152+
},
153+
{
154+
"name": "c",
155+
"type": "ParameterOptionsInterfaceC",
156+
"description": "<p>Parameter with inner jsdocs default.</p>\n"
157+
}
158+
],
159+
"returns": "number",
160+
"examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">optionsInterfaceParamMethodWithDefaults</span><span class=\"token punctuation\">(</span>a<span class=\"token operator\">:</span> ParameterOptionsInterfaceA <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> b<span class=\"token operator\">:</span> ParameterOptionsInterfaceB <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> c<span class=\"token operator\">:</span> ParameterOptionsInterfaceC<span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
161+
"deprecated": false,
162+
"seeAlsos": []
163+
},
164+
"optionsTypeParamMethodWithDefaults": {
165+
"name": "optionsTypeParamMethodWithDefaults",
166+
"title": "Options Type Param Method With Defaults",
167+
"description": "<p>Test with a function parameters with defaults.</p>\n",
168+
"parameters": [
169+
{
170+
"name": "a",
171+
"type": "ParameterOptionsTypeA",
172+
"default": "{ value: 1 }",
173+
"description": "<p>Parameter with signature default.</p>\n"
174+
},
175+
{
176+
"name": "b",
177+
"type": "ParameterOptionsTypeB",
178+
"default": "{ value: 1 }",
179+
"description": "<p>Parameter with jsdocs default.</p>\n"
180+
},
181+
{
182+
"name": "c",
183+
"type": "ParameterOptionsTypeC",
184+
"description": "<p>Parameter with inner jsdocs default.</p>\n"
185+
}
186+
],
187+
"returns": "number",
188+
"examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">optionsTypeParamMethodWithDefaults</span><span class=\"token punctuation\">(</span>a<span class=\"token operator\">:</span> ParameterOptionsTypeA <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> b<span class=\"token operator\">:</span> ParameterOptionsTypeB <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> c<span class=\"token operator\">:</span> ParameterOptionsTypeC<span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
189+
"deprecated": false,
190+
"seeAlsos": []
191+
},
92192
"optionalStringParamMethod": {
93193
"name": "optionalStringParamMethod",
94194
"title": "Optional String Param Method",

‎test/scripts/apidoc/signature.spec.ts

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ import * as TypeDoc from 'typedoc';
44
import { afterAll, describe, expect, it } from 'vitest';
55
import type { Method } from '../../../docs/.vitepress/components/api-docs/method';
66
import { analyzeSignature } from '../../../scripts/apidoc/signature';
7+
import { newTypeDocApp, patchProject } from '../../../scripts/apidoc/utils';
8+
import { SignatureTest } from './signature.example';
79
import expected_ from './signature.expected.json';
810
const expected: Record<string, Method> = expected_;
911

@@ -12,24 +14,29 @@ function prettyJson(object): string {
1214
}
1315

1416
describe('signature', () => {
15-
const app = new TypeDoc.Application();
16-
17-
app.options.addReader(new TypeDoc.TSConfigReader());
17+
const app = newTypeDocApp();
1818

1919
app.bootstrap({
2020
entryPoints: ['test/scripts/apidoc/signature.example.ts'],
2121
tsconfig: 'test/scripts/apidoc/tsconfig.json',
2222
});
2323

24-
const methods: Record<string, TypeDoc.DeclarationReflection> = app
25-
.convert()
24+
const project = app.convert();
25+
26+
patchProject(project);
27+
28+
const methods: Record<string, TypeDoc.DeclarationReflection> = project
2629
.getChildrenByKind(TypeDoc.ReflectionKind.Class)[0]
2730
.getChildrenByKind(TypeDoc.ReflectionKind.Method)
2831
.reduce((a, v) => ({ ...a, [v.name]: v }), {});
2932

3033
describe('analyzeSignature()', () => {
3134
const actuals = {};
3235

36+
it('dummy dependency to rerun the test if the example changes', () => {
37+
expect(new SignatureTest()).toBeTruthy();
38+
});
39+
3340
it('expected and actual methods are equal', () => {
3441
expect(Object.keys(methods).sort()).toEqual(Object.keys(expected).sort());
3542
});

0 commit comments

Comments
 (0)