From e228183efc0fe74ee0438fbcb693932358921a20 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Sat, 14 Oct 2023 10:50:05 +0200 Subject: [PATCH] docs: fix bad Promise usage (#2475) --- scripts/apidoc/generate.ts | 6 +-- scripts/apidoc/signature.ts | 6 +-- .../__snapshots__/signature.spec.ts.snap | 54 ++++++++++++++----- test/scripts/apidoc/signature.debug.ts | 4 +- test/scripts/apidoc/signature.example.ts | 13 ++++- 5 files changed, 59 insertions(+), 24 deletions(-) diff --git a/scripts/apidoc/generate.ts b/scripts/apidoc/generate.ts index e3047131133..aa33a46e831 100644 --- a/scripts/apidoc/generate.ts +++ b/scripts/apidoc/generate.ts @@ -22,14 +22,14 @@ export async function generate(): Promise { // Useful for manually analyzing the content await app.generateJson(project, pathOutputJson); - const pages = await Promise.all([ + const pages = [ ...(await processFakerClasses(project)), ...(await processModules(project)).sort((a, b) => a.text.localeCompare(b.text) ), await processFakerRandomizer(project), - processFakerUtilities(project), - ]); + await processFakerUtilities(project), + ]; await writeApiPagesIndex(pages.map(({ text, link }) => ({ text, link }))); writeApiDiffIndex( Object.fromEntries(pages.map(({ text, diff }) => [text, diff])) diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts index fe11c78d0ab..2cca92b99d9 100644 --- a/scripts/apidoc/signature.ts +++ b/scripts/apidoc/signature.ts @@ -226,9 +226,9 @@ async function typeToText(type_?: Type, short = false): Promise { ].join(' | '); } - return `${type.name}<${type.typeArguments - .map(async (t) => await typeToText(t, short)) - .join(', ')}>`; + return `${type.name}<${( + await Promise.all(type.typeArguments.map((t) => typeToText(t, short))) + ).join(', ')}>`; case 'reflection': return declarationTypeToText(type.declaration, short); diff --git a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap index 79ceecf57e5..12e7df29bb5 100644 --- a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap +++ b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap @@ -43,7 +43,7 @@ exports[`signature > analyzeSignature() > complexArrayParameter 1`] = ` "returns": "T", "seeAlsos": [], "since": "", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L358", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L367", "throws": undefined, } `; @@ -93,6 +93,7 @@ exports[`signature > analyzeSignature() > expected and actual methods are equal "optionsInterfaceParamMethodWithDefaults", "optionsParamMethod", "optionsTypeParamMethodWithDefaults", + "recordParamMethod", "requiredNumberParamMethod", "stringUnionParamMethod", ] @@ -198,7 +199,7 @@ exports[`signature > analyzeSignature() > methodWithDeprecated 1`] = ` "test.apidoc.methodWithExample()", ], "since": "", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L278", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L287", "throws": undefined, } `; @@ -250,7 +251,7 @@ exports[`signature > analyzeSignature() > methodWithDeprecatedOption 1`] = ` "returns": "number", "seeAlsos": [], "since": "", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L299", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L308", "throws": undefined, } `; @@ -268,7 +269,7 @@ exports[`signature > analyzeSignature() > methodWithExample 1`] = ` "returns": "number", "seeAlsos": [], "since": "", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L267", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L276", "throws": undefined, } `; @@ -288,7 +289,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = ` "test.apidoc.methodWithDeprecated()", ], "since": "", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L326", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L335", "throws": undefined, } `; @@ -308,7 +309,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBacktic "test.apidoc.methodWithDeprecated() with parameter bar and baz.", ], "since": "", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L336", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L345", "throws": undefined, } `; @@ -325,7 +326,7 @@ exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = ` "returns": "number", "seeAlsos": [], "since": "1.0.0", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L345", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L354", "throws": undefined, } `; @@ -342,7 +343,7 @@ exports[`signature > analyzeSignature() > methodWithThrows 1`] = ` "returns": "number", "seeAlsos": [], "since": "", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L287", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L296", "throws": "a Faker error", } `; @@ -491,7 +492,7 @@ It also has a more complex description.

"returns": "number", "seeAlsos": [], "since": "", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L217", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L226", "throws": undefined, } `; @@ -530,7 +531,7 @@ exports[`signature > analyzeSignature() > optionsInterfaceParamMethodWithDefault "returns": "number", "seeAlsos": [], "since": "", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L253", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L262", "throws": undefined, } `; @@ -538,7 +539,7 @@ exports[`signature > analyzeSignature() > optionsInterfaceParamMethodWithDefault exports[`signature > analyzeSignature() > optionsParamMethod 1`] = ` { "deprecated": undefined, - "description": "

Test with a function parameters.

+ "description": "

Test with an options parameter.

", "examples": "
ts
optionsParamMethod(options: {
   a: number,
@@ -552,7 +553,7 @@ exports[`signature > analyzeSignature() > optionsParamMethod 1`] = `
   "parameters": [
     {
       "default": undefined,
-      "description": "
The function parameter.

+      "description": "
The options parameter.

 ",
       "name": "options",
       "type": "{ ... }",
@@ -596,7 +597,7 @@ exports[`signature > analyzeSignature() > optionsParamMethod 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L187",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L196",
   "throws": undefined,
 }
 `;
@@ -635,7 +636,32 @@ exports[`signature > analyzeSignature() > optionsTypeParamMethodWithDefaults 1`]
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L235",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L244",
+  "throws": undefined,
+}
+`;
+
+exports[`signature > analyzeSignature() > recordParamMethod 1`] = `
+{
+  "deprecated": undefined,
+  "description": "
Test with a Record parameter.

+",
+  "examples": "
ts
recordParamMethod(object: Record<string, number>): number

+
",
+  "name": "recordParamMethod",
+  "parameters": [
+    {
+      "default": undefined,
+      "description": "
The Record parameter.

+",
+      "name": "object",
+      "type": "Record",
+    },
+  ],
+  "returns": "number",
+  "seeAlsos": [],
+  "since": "",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L182",
   "throws": undefined,
 }
 `;
diff --git a/test/scripts/apidoc/signature.debug.ts b/test/scripts/apidoc/signature.debug.ts
index 52b6976aa65..d72709b0754 100644
--- a/test/scripts/apidoc/signature.debug.ts
+++ b/test/scripts/apidoc/signature.debug.ts
@@ -11,10 +11,10 @@ import { loadExampleMethods } from './utils';
 const methods = loadExampleMethods();
 
 initMarkdownRenderer()
-  .then(() => {
+  .then(async () => {
     for (const [name, method] of Object.entries(methods)) {
       console.log('Analyzing:', name);
-      const result = analyzeSignature(method, '', method.name);
+      const result = await analyzeSignature(method, '', method.name);
       console.log('Result:', result);
     }
   })
diff --git a/test/scripts/apidoc/signature.example.ts b/test/scripts/apidoc/signature.example.ts
index a4849e304a5..724f687d3a6 100644
--- a/test/scripts/apidoc/signature.example.ts
+++ b/test/scripts/apidoc/signature.example.ts
@@ -175,9 +175,18 @@ export class SignatureTest {
   }
 
   /**
-   * Test with a function parameters.
+   * Test with a Record parameter.
    *
-   * @param options The function parameter.
+   * @param object The Record parameter.
+   */
+  recordParamMethod(object: Record): number {
+    return object.a;
+  }
+
+  /**
+   * Test with an options parameter.
+   *
+   * @param options The options parameter.
    * @param options.a The number parameter.
    * @param options.b The string parameter.
    * @param options.c The boolean parameter.