From 5aa8eeb3649955bf03239e93c4b87b1bc874cb2e Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Thu, 7 Apr 2022 16:08:09 +0200 Subject: test: add parameter defaults to our signature generation test (#793) --- scripts/apidoc.ts | 29 +------ scripts/apidoc/utils.ts | 38 ++++++++++ test/scripts/apidoc/signature.example.ts | 114 ++++++++++++++++++++++++++++ test/scripts/apidoc/signature.expected.json | 100 ++++++++++++++++++++++++ test/scripts/apidoc/signature.spec.ts | 17 +++-- 5 files changed, 267 insertions(+), 31 deletions(-) diff --git a/scripts/apidoc.ts b/scripts/apidoc.ts index 4ac4fbf9..d519a320 100644 --- a/scripts/apidoc.ts +++ b/scripts/apidoc.ts @@ -1,32 +1,14 @@ import { resolve } from 'path'; -import * as TypeDoc from 'typedoc'; import { writeApiPagesIndex } from './apidoc/apiDocsWriter'; import { processDirectMethods } from './apidoc/directMethods'; import { processModuleMethods } from './apidoc/moduleMethods'; -import { - DefaultParameterAwareSerializer, - parameterDefaultReader, - patchProjectParameterDefaults, -} from './apidoc/parameterDefaults'; import type { PageIndex } from './apidoc/utils'; -import { pathOutputDir } from './apidoc/utils'; +import { newTypeDocApp, patchProject, pathOutputDir } from './apidoc/utils'; const pathOutputJson = resolve(pathOutputDir, 'typedoc.json'); async function build(): Promise { - const app = new TypeDoc.Application(); - - app.options.addReader(new TypeDoc.TSConfigReader()); - // If you want TypeDoc to load typedoc.json files - //app.options.addReader(new TypeDoc.TypeDocReader()); - - // Read parameter defaults - app.converter.on( - TypeDoc.Converter.EVENT_CREATE_DECLARATION, - parameterDefaultReader - ); - // Add to debug json output - app.serializer.addSerializer(new DefaultParameterAwareSerializer(undefined)); + const app = newTypeDocApp(); app.bootstrap({ entryPoints: ['src/index.ts'], @@ -36,15 +18,10 @@ async function build(): Promise { const project = app.convert(); - if (!project) { - // Project may not have converted correctly - return; - } // Useful for manually analyzing the content await app.generateJson(project, pathOutputJson); - console.log(pathOutputDir); - patchProjectParameterDefaults(project); + patchProject(project); const modulesPages: PageIndex = []; modulesPages.push({ text: 'Localization', link: '/api/localization.html' }); diff --git a/scripts/apidoc/utils.ts b/scripts/apidoc/utils.ts index ee38d58d..68b69746 100644 --- a/scripts/apidoc/utils.ts +++ b/scripts/apidoc/utils.ts @@ -1,4 +1,10 @@ import { resolve } from 'node:path'; +import * as TypeDoc from 'typedoc'; +import { + DefaultParameterAwareSerializer, + parameterDefaultReader, + patchProjectParameterDefaults, +} from './parameterDefaults'; export type Page = { text: string; link: string }; export type PageIndex = Array; @@ -6,3 +12,35 @@ export type PageIndex = Array; const pathRoot = resolve(__dirname, '..', '..'); export const pathDocsDir = resolve(pathRoot, 'docs'); export const pathOutputDir = resolve(pathDocsDir, 'api'); + +/** + * Creates and configures a new typedoc application. + */ +export function newTypeDocApp(): TypeDoc.Application { + const app = new TypeDoc.Application(); + + app.options.addReader(new TypeDoc.TSConfigReader()); + // If you want TypeDoc to load typedoc.json files + //app.options.addReader(new TypeDoc.TypeDocReader()); + + // Read parameter defaults + app.converter.on( + TypeDoc.Converter.EVENT_CREATE_DECLARATION, + parameterDefaultReader + ); + // Add to debug json output + app.serializer.addSerializer(new DefaultParameterAwareSerializer(undefined)); + + return app; +} + +/** + * Apply our patches to the generated typedoc data. + * + * This is moved to a separate method to allow printing/saving the original content before patching it. + * + * @param project The project to patch. + */ +export function patchProject(project: TypeDoc.ProjectReflection): void { + patchProjectParameterDefaults(project); +} diff --git a/test/scripts/apidoc/signature.example.ts b/test/scripts/apidoc/signature.example.ts index b413dd20..16dae935 100644 --- a/test/scripts/apidoc/signature.example.ts +++ b/test/scripts/apidoc/signature.example.ts @@ -1,3 +1,63 @@ +/** + * Parameter options type with default from signature. + */ +export type ParameterOptionsTypeA = { + /** + * Options value. + */ + value?: number; +}; + +/** + * Parameter options type with default from jsdocs. Defaults to `{value: 0}`. + */ +export type ParameterOptionsTypeB = { + /** + * Options value. + */ + value?: number; +}; + +/** + * Parameter options type with default from inner jsdocs. + */ +export type ParameterOptionsTypeC = { + /** + * Options value. Defaults to `0`. + */ + value?: number; +}; + +/** + * Parameter options type with default from signature. + */ +export interface ParameterOptionsInterfaceA { + /** + * Options value. + */ + value?: number; +} + +/** + * Parameter options type with default from jsdocs. + */ +export interface ParameterOptionsInterfaceB { + /** + * Options value. + */ + value?: number; +} + +/** + * Parameter options type with default from inner jsdocs. + */ +export interface ParameterOptionsInterfaceC { + /** + * Options value. Defaults to `0`. + */ + value?: number; +} + export class SignatureTest { /** * Test with no parameters. @@ -71,6 +131,60 @@ export class SignatureTest { return options.c ? options.a : +options.b; } + /** + * Test with a function parameters (inline types) with defaults. + * + * @param a Parameter with signature default. + * @param a.value The number parameter. + * @param b Parameter with jsdocs default. Defaults to `{ value: 1 }`. + * @param b.value The boolean parameter. + * @param c Parameter with inner jsdocs default. + * @param c.value The boolean parameter. Defaults to `2`. + */ + optionsInlineParamMethodWithDefaults( + a: { value?: number } = { value: 1 }, + b: { value?: number }, + c: { value?: number } + ): number { + return a.value ?? b.value ?? c.value ?? -1; + } + + /** + * Test with a function parameters with defaults. + * + * @param a Parameter with signature default. + * @param a.value The number parameter. + * @param b Parameter with jsdocs default. Defaults to `{ value: 1 }`. + * @param b.value The boolean parameter. + * @param c Parameter with inner jsdocs default. + * @param c.value The boolean parameter. Defaults to `2`. + */ + optionsTypeParamMethodWithDefaults( + a: ParameterOptionsTypeA = { value: 1 }, + b: ParameterOptionsTypeB, + c: ParameterOptionsTypeC + ): number { + return a.value ?? b.value ?? c.value ?? -1; + } + + /** + * Test with a function parameters with defaults. + * + * @param a Parameter with signature default. + * @param a.value The number parameter. + * @param b Parameter with jsdocs default. Defaults to `{ value: 1 }`. + * @param b.value The boolean parameter. + * @param c Parameter with inner jsdocs default. + * @param c.value The boolean parameter. Defaults to `2`. + */ + optionsInterfaceParamMethodWithDefaults( + a: ParameterOptionsInterfaceA = { value: 1 }, + b: ParameterOptionsInterfaceB, + c: ParameterOptionsInterfaceC + ): number { + return a.value ?? b.value ?? c.value ?? -1; + } + /** * Test with example marker. * diff --git a/test/scripts/apidoc/signature.expected.json b/test/scripts/apidoc/signature.expected.json index da7c2e87..f6e398fe 100644 --- a/test/scripts/apidoc/signature.expected.json +++ b/test/scripts/apidoc/signature.expected.json @@ -89,6 +89,106 @@ "deprecated": false, "seeAlsos": [] }, + "optionsInlineParamMethodWithDefaults": { + "name": "optionsInlineParamMethodWithDefaults", + "title": "Options Inline Param Method With Defaults", + "description": "

Test with a function parameters (inline types) with defaults.

\n", + "parameters": [ + { + "name": "a", + "type": "{ ... }", + "default": "{ value: 1 }", + "description": "

Parameter with signature default.

\n" + }, + { + "name": "a.value?", + "type": "number", + "description": "

The number parameter.

\n" + }, + { + "name": "b", + "type": "{ ... }", + "default": "{ value: 1 }", + "description": "

Parameter with jsdocs default.

\n" + }, + { + "name": "b.value?", + "type": "number", + "description": "

The boolean parameter.

\n" + }, + { + "name": "c", + "type": "{ ... }", + "description": "

Parameter with inner jsdocs default.

\n" + }, + { + "name": "c.value?", + "type": "number", + "default": "2", + "description": "

The boolean parameter.

\n" + } + ], + "returns": "number", + "examples": "
faker.optionsInlineParamMethodWithDefaults(a: {\n  value: number\n} = { value: 1 }, b: {\n  value: number\n} = { value: 1 }, c: {\n  value: number\n}): number\n
\n
", + "deprecated": false, + "seeAlsos": [] + }, + "optionsInterfaceParamMethodWithDefaults": { + "name": "optionsInterfaceParamMethodWithDefaults", + "title": "Options Interface Param Method With Defaults", + "description": "

Test with a function parameters with defaults.

\n", + "parameters": [ + { + "name": "a", + "type": "ParameterOptionsInterfaceA", + "default": "{ value: 1 }", + "description": "

Parameter with signature default.

\n" + }, + { + "name": "b", + "type": "ParameterOptionsInterfaceB", + "default": "{ value: 1 }", + "description": "

Parameter with jsdocs default.

\n" + }, + { + "name": "c", + "type": "ParameterOptionsInterfaceC", + "description": "

Parameter with inner jsdocs default.

\n" + } + ], + "returns": "number", + "examples": "
faker.optionsInterfaceParamMethodWithDefaults(a: ParameterOptionsInterfaceA = { value: 1 }, b: ParameterOptionsInterfaceB = { value: 1 }, c: ParameterOptionsInterfaceC): number\n
\n
", + "deprecated": false, + "seeAlsos": [] + }, + "optionsTypeParamMethodWithDefaults": { + "name": "optionsTypeParamMethodWithDefaults", + "title": "Options Type Param Method With Defaults", + "description": "

Test with a function parameters with defaults.

\n", + "parameters": [ + { + "name": "a", + "type": "ParameterOptionsTypeA", + "default": "{ value: 1 }", + "description": "

Parameter with signature default.

\n" + }, + { + "name": "b", + "type": "ParameterOptionsTypeB", + "default": "{ value: 1 }", + "description": "

Parameter with jsdocs default.

\n" + }, + { + "name": "c", + "type": "ParameterOptionsTypeC", + "description": "

Parameter with inner jsdocs default.

\n" + } + ], + "returns": "number", + "examples": "
faker.optionsTypeParamMethodWithDefaults(a: ParameterOptionsTypeA = { value: 1 }, b: ParameterOptionsTypeB = { value: 1 }, c: ParameterOptionsTypeC): number\n
\n
", + "deprecated": false, + "seeAlsos": [] + }, "optionalStringParamMethod": { "name": "optionalStringParamMethod", "title": "Optional String Param Method", diff --git a/test/scripts/apidoc/signature.spec.ts b/test/scripts/apidoc/signature.spec.ts index f536a219..d550dfd2 100644 --- a/test/scripts/apidoc/signature.spec.ts +++ b/test/scripts/apidoc/signature.spec.ts @@ -4,6 +4,8 @@ import * as TypeDoc from 'typedoc'; import { afterAll, describe, expect, it } from 'vitest'; import type { Method } from '../../../docs/.vitepress/components/api-docs/method'; import { analyzeSignature } from '../../../scripts/apidoc/signature'; +import { newTypeDocApp, patchProject } from '../../../scripts/apidoc/utils'; +import { SignatureTest } from './signature.example'; import expected_ from './signature.expected.json'; const expected: Record = expected_; @@ -12,17 +14,18 @@ function prettyJson(object): string { } describe('signature', () => { - const app = new TypeDoc.Application(); - - app.options.addReader(new TypeDoc.TSConfigReader()); + const app = newTypeDocApp(); app.bootstrap({ entryPoints: ['test/scripts/apidoc/signature.example.ts'], tsconfig: 'test/scripts/apidoc/tsconfig.json', }); - const methods: Record = app - .convert() + const project = app.convert(); + + patchProject(project); + + const methods: Record = project .getChildrenByKind(TypeDoc.ReflectionKind.Class)[0] .getChildrenByKind(TypeDoc.ReflectionKind.Method) .reduce((a, v) => ({ ...a, [v.name]: v }), {}); @@ -30,6 +33,10 @@ describe('signature', () => { describe('analyzeSignature()', () => { const actuals = {}; + it('dummy dependency to rerun the test if the example changes', () => { + expect(new SignatureTest()).toBeTruthy(); + }); + it('expected and actual methods are equal', () => { expect(Object.keys(methods).sort()).toEqual(Object.keys(expected).sort()); }); -- cgit v1.2.3