From edc50b69197260f9d3e8ac22f2bf062c9a71c390 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Mon, 3 Apr 2023 17:39:43 +0200 Subject: docs: Faker and utility pages (#1940) --- .../apidoc/__snapshots__/signature.spec.ts.snap | 57 ++++++++-------------- test/scripts/apidoc/signature.debug.ts | 2 +- test/scripts/apidoc/signature.spec.ts | 2 +- test/scripts/apidoc/verify-jsdoc-tags.spec.ts | 24 ++++----- 4 files changed, 33 insertions(+), 52 deletions(-) (limited to 'test/scripts') diff --git a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap index f93bcd49..715c85aa 100644 --- a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap +++ b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap @@ -5,7 +5,7 @@ exports[`signature > analyzeSignature() > complexArrayParameter 1`] = ` "deprecated": undefined, "description": "

Complex array parameter.

", - "examples": "
ts
faker.complexArrayParameter<T>(array: readonly Array<{
+  "examples": "
ts
complexArrayParameter<T>(array: readonly Array<{
   value: T,
   weight: number
 }>): T
@@ -45,7 +45,6 @@ exports[`signature > analyzeSignature() > complexArrayParameter 1`] = `
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L343",
-  "title": "Complex Array Parameter",
 }
 `;
 
@@ -54,7 +53,7 @@ exports[`signature > analyzeSignature() > defaultBooleanParamMethod 1`] = `
   "deprecated": undefined,
   "description": "
Test with a default parameter.

 ",
-  "examples": "
ts
faker.defaultBooleanParamMethod(c: boolean = true): number
+  "examples": "
ts
defaultBooleanParamMethod(c: boolean = true): number
 

 
",
   "name": "defaultBooleanParamMethod",
@@ -71,7 +70,6 @@ exports[`signature > analyzeSignature() > defaultBooleanParamMethod 1`] = `
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L101",
-  "title": "Default Boolean Param Method",
 }
 `;
 
@@ -104,7 +102,7 @@ exports[`signature > analyzeSignature() > functionParamMethod 1`] = `
   "deprecated": undefined,
   "description": "
Test with a function parameters.

 ",
-  "examples": "
ts
faker.functionParamMethod(fn: (a: string) => number): number
+  "examples": "
ts
functionParamMethod(fn: (a: string) => number): number
 

 
",
   "name": "functionParamMethod",
@@ -121,7 +119,6 @@ exports[`signature > analyzeSignature() > functionParamMethod 1`] = `
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L121",
-  "title": "Function Param Method",
 }
 `;
 
@@ -130,7 +127,7 @@ exports[`signature > analyzeSignature() > literalUnionParamMethod 1`] = `
   "deprecated": undefined,
   "description": "
Test with LiteralUnion.

 ",
-  "examples": "
ts
faker.literalUnionParamMethod(value: 'a' | 'b' | string, namedValue: 'a' | 'b' | string, array: readonly Array<'a' | 'b' | string>, namedArray: readonly Array<'a' | 'b' | string>, mixed: 'a' | 'b' | string | readonly Array<'a' | 'b' | string>, namedMixed: 'a' | 'b' | string | readonly Array<'a' | 'b' | string>): string
+  "examples": "
ts
literalUnionParamMethod(value: 'a' | 'b' | string, namedValue: 'a' | 'b' | string, array: readonly Array<'a' | 'b' | string>, namedArray: readonly Array<'a' | 'b' | string>, mixed: 'a' | 'b' | string | readonly Array<'a' | 'b' | string>, namedMixed: 'a' | 'b' | string | readonly Array<'a' | 'b' | string>): string
 

 
",
   "name": "literalUnionParamMethod",
@@ -182,7 +179,6 @@ exports[`signature > analyzeSignature() > literalUnionParamMethod 1`] = `
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L155",
-  "title": "Literal Union Param Method",
 }
 `;
 
@@ -192,7 +188,7 @@ exports[`signature > analyzeSignature() > methodWithDeprecated 1`] = `
 ",
   "description": "
Test with deprecated and see marker.

 ",
-  "examples": "
ts
faker.methodWithDeprecated(): number
+  "examples": "
ts
methodWithDeprecated(): number
 

 
",
   "name": "methodWithDeprecated",
@@ -203,7 +199,6 @@ exports[`signature > analyzeSignature() > methodWithDeprecated 1`] = `
   ],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L273",
-  "title": "Method With Deprecated",
 }
 `;
 
@@ -212,7 +207,7 @@ exports[`signature > analyzeSignature() > methodWithDeprecatedOption 1`] = `
   "deprecated": undefined,
   "description": "
Test with deprecated option.

 ",
-  "examples": "
ts
faker.methodWithDeprecatedOption(option: {
+  "examples": "
ts
methodWithDeprecatedOption(option: {
   a: string,
   b: () => number,
   c: number
@@ -256,7 +251,6 @@ exports[`signature > analyzeSignature() > methodWithDeprecatedOption 1`] = `
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L285",
-  "title": "Method With Deprecated Option",
 }
 `;
 
@@ -265,7 +259,7 @@ exports[`signature > analyzeSignature() > methodWithExample 1`] = `
   "deprecated": undefined,
   "description": "
Test with example marker.

 ",
-  "examples": "
ts
faker.methodWithExample(): number
+  "examples": "
ts
methodWithExample(): number
 test.apidoc.methodWithExample() // 0
 

 
",
@@ -275,7 +269,6 @@ exports[`signature > analyzeSignature() > methodWithExample 1`] = `
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L262",
-  "title": "Method With Example",
 }
 `;
 
@@ -284,7 +277,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = `
   "deprecated": undefined,
   "description": "
Test with multiple see markers.

 ",
-  "examples": "
ts
faker.methodWithMultipleSeeMarkers(): number
+  "examples": "
ts
methodWithMultipleSeeMarkers(): number
 

 
",
   "name": "methodWithMultipleSeeMarkers",
@@ -296,7 +289,6 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = `
   ],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L312",
-  "title": "Method With Multiple See Markers",
 }
 `;
 
@@ -305,7 +297,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBacktic
   "deprecated": undefined,
   "description": "
Test with multiple see markers and backticks.

 ",
-  "examples": "
ts
faker.methodWithMultipleSeeMarkersAndBackticks(): number
+  "examples": "
ts
methodWithMultipleSeeMarkersAndBackticks(): number
 

 
",
   "name": "methodWithMultipleSeeMarkersAndBackticks",
@@ -317,7 +309,6 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBacktic
   ],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L322",
-  "title": "Method With Multiple See Markers And Backticks",
 }
 `;
 
@@ -326,7 +317,7 @@ exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = `
   "deprecated": undefined,
   "description": "
Test with since marker.

 ",
-  "examples": "
ts
faker.methodWithSinceMarker(): number
+  "examples": "
ts
methodWithSinceMarker(): number
 

 
",
   "name": "methodWithSinceMarker",
@@ -335,7 +326,6 @@ exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = `
   "seeAlsos": [],
   "since": "1.0.0",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L331",
-  "title": "Method With Since Marker",
 }
 `;
 
@@ -344,7 +334,7 @@ exports[`signature > analyzeSignature() > multiParamMethod 1`] = `
   "deprecated": undefined,
   "description": "
Test with multiple parameters.

 ",
-  "examples": "
ts
faker.multiParamMethod(a: number, b?: string, c: boolean = true): number
+  "examples": "
ts
multiParamMethod(a: number, b?: string, c: boolean = true): number
 

 
",
   "name": "multiParamMethod",
@@ -375,7 +365,6 @@ exports[`signature > analyzeSignature() > multiParamMethod 1`] = `
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L112",
-  "title": "Multi Param Method",
 }
 `;
 
@@ -384,7 +373,7 @@ exports[`signature > analyzeSignature() > noParamMethod 1`] = `
   "deprecated": undefined,
   "description": "
Test with no parameters.

 ",
-  "examples": "
ts
faker.noParamMethod(): number
+  "examples": "
ts
noParamMethod(): number
 

 
",
   "name": "noParamMethod",
@@ -393,7 +382,6 @@ exports[`signature > analyzeSignature() > noParamMethod 1`] = `
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L74",
-  "title": "No Param Method",
 }
 `;
 
@@ -402,7 +390,7 @@ exports[`signature > analyzeSignature() > optionalStringParamMethod 1`] = `
   "deprecated": undefined,
   "description": "
Test with an optional parameter.

 ",
-  "examples": "
ts
faker.optionalStringParamMethod(b?: string): number
+  "examples": "
ts
optionalStringParamMethod(b?: string): number
 

 
",
   "name": "optionalStringParamMethod",
@@ -419,7 +407,6 @@ exports[`signature > analyzeSignature() > optionalStringParamMethod 1`] = `
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L92",
-  "title": "Optional String Param Method",
 }
 `;
 
@@ -428,7 +415,7 @@ exports[`signature > analyzeSignature() > optionsInlineParamMethodWithDefaults 1
   "deprecated": undefined,
   "description": "
Test with a function parameters (inline types) with defaults.

 ",
-  "examples": "
ts
faker.optionsInlineParamMethodWithDefaults(a: {
+  "examples": "
ts
optionsInlineParamMethodWithDefaults(a: {
   value: number
 } = { value: 1 }, b: {
   value: number
@@ -488,7 +475,6 @@ It also has a more complex description.

   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L212",
-  "title": "Options Inline Param Method With Defaults",
 }
 `;
 
@@ -497,7 +483,7 @@ exports[`signature > analyzeSignature() > optionsInterfaceParamMethodWithDefault
   "deprecated": undefined,
   "description": "
Test with a function parameters with defaults.

 ",
-  "examples": "
ts
faker.optionsInterfaceParamMethodWithDefaults(a: ParameterOptionsInterfaceA = { value: 1 }, b: ParameterOptionsInterfaceB = { value: 1 }, c: ParameterOptionsInterfaceC): number
+  "examples": "
ts
optionsInterfaceParamMethodWithDefaults(a: ParameterOptionsInterfaceA = { value: 1 }, b: ParameterOptionsInterfaceB = { value: 1 }, c: ParameterOptionsInterfaceC): number
 

 
",
   "name": "optionsInterfaceParamMethodWithDefaults",
@@ -528,7 +514,6 @@ exports[`signature > analyzeSignature() > optionsInterfaceParamMethodWithDefault
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L248",
-  "title": "Options Interface Param Method With Defaults",
 }
 `;
 
@@ -537,7 +522,7 @@ exports[`signature > analyzeSignature() > optionsParamMethod 1`] = `
   "deprecated": undefined,
   "description": "
Test with a function parameters.

 ",
-  "examples": "
ts
faker.optionsParamMethod(options: {
+  "examples": "
ts
optionsParamMethod(options: {
   a: number,
   b: string,
   c: boolean,
@@ -595,7 +580,6 @@ exports[`signature > analyzeSignature() > optionsParamMethod 1`] = `
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L182",
-  "title": "Options Param Method",
 }
 `;
 
@@ -604,7 +588,7 @@ exports[`signature > analyzeSignature() > optionsTypeParamMethodWithDefaults 1`]
   "deprecated": undefined,
   "description": "
Test with a function parameters with defaults.

 ",
-  "examples": "
ts
faker.optionsTypeParamMethodWithDefaults(a: ParameterOptionsTypeA = { value: 1 }, b: ParameterOptionsTypeB = { value: 1 }, c: ParameterOptionsTypeC): number
+  "examples": "
ts
optionsTypeParamMethodWithDefaults(a: ParameterOptionsTypeA = { value: 1 }, b: ParameterOptionsTypeB = { value: 1 }, c: ParameterOptionsTypeC): number
 

 
",
   "name": "optionsTypeParamMethodWithDefaults",
@@ -635,7 +619,6 @@ exports[`signature > analyzeSignature() > optionsTypeParamMethodWithDefaults 1`]
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L230",
-  "title": "Options Type Param Method With Defaults",
 }
 `;
 
@@ -644,7 +627,7 @@ exports[`signature > analyzeSignature() > requiredNumberParamMethod 1`] = `
   "deprecated": undefined,
   "description": "
Test with a required parameter.

 ",
-  "examples": "
ts
faker.requiredNumberParamMethod(a: number): number
+  "examples": "
ts
requiredNumberParamMethod(a: number): number
 

 
",
   "name": "requiredNumberParamMethod",
@@ -661,7 +644,6 @@ exports[`signature > analyzeSignature() > requiredNumberParamMethod 1`] = `
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L83",
-  "title": "Required Number Param Method",
 }
 `;
 
@@ -670,7 +652,7 @@ exports[`signature > analyzeSignature() > stringUnionParamMethod 1`] = `
   "deprecated": undefined,
   "description": "
Test with string union.

 ",
-  "examples": "
ts
faker.stringUnionParamMethod(value: 'a' | 'b', options?: {
+  "examples": "
ts
stringUnionParamMethod(value: 'a' | 'b', options?: {
   casing: 'lower' | 'mixed' | 'upper',
   excludes: readonly AlphaNumericChar[],
   format: 'binary' | 'css' | 'decimal' | 'hex'
@@ -719,6 +701,5 @@ exports[`signature > analyzeSignature() > stringUnionParamMethod 1`] = `
   "seeAlsos": [],
   "since": "",
   "sourcePath": "test/scripts/apidoc/signature.example.ts#L134",
-  "title": "String Union Param Method",
 }
 `;
diff --git a/test/scripts/apidoc/signature.debug.ts b/test/scripts/apidoc/signature.debug.ts
index 6be0e49f..0076dfa7 100644
--- a/test/scripts/apidoc/signature.debug.ts
+++ b/test/scripts/apidoc/signature.debug.ts
@@ -16,7 +16,7 @@ initMarkdownRenderer()
   .then(() => {
     Object.entries(methods).forEach(([name, method]) => {
       console.log('Analyzing: ', name);
-      const result = analyzeSignature(method, null, method.name);
+      const result = analyzeSignature(method, '', method.name);
       console.log('Result: ', result);
     });
   })
diff --git a/test/scripts/apidoc/signature.spec.ts b/test/scripts/apidoc/signature.spec.ts
index d90370a2..3a48c29b 100644
--- a/test/scripts/apidoc/signature.spec.ts
+++ b/test/scripts/apidoc/signature.spec.ts
@@ -23,7 +23,7 @@ describe('signature', () => {
     });
 
     it.each(Object.entries(methods))('%s', (name, signature) => {
-      const actual = analyzeSignature(signature, null, name);
+      const actual = analyzeSignature(signature, '', name);
 
       expect(actual).toMatchSnapshot();
     });
diff --git a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts b/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
index 410bffc2..68692fab 100644
--- a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
+++ b/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
@@ -109,18 +109,18 @@ describe('verify JSDoc tags', () => {
         });
 
         it('verify @param tags', () => {
-          analyzeSignature(
-            signature,
-            moduleName,
-            methodName
-          ).parameters.forEach((param) => {
-            const { name, description } = param;
-            const plainDescription = description.replace(/<[^>]+>/g, '').trim();
-            expect(
-              plainDescription,
-              `Expect param ${name} to have a description`
-            ).not.toBe(MISSING_DESCRIPTION);
-          });
+          analyzeSignature(signature, '', methodName).parameters.forEach(
+            (param) => {
+              const { name, description } = param;
+              const plainDescription = description
+                .replace(/<[^>]+>/g, '')
+                .trim();
+              expect(
+                plainDescription,
+                `Expect param ${name} to have a description`
+              ).not.toBe(MISSING_DESCRIPTION);
+            }
+          );
         });
 
         it('verify @see tags', () => {
-- 
cgit v1.2.3