diff options
| author | ST-DDT <[email protected]> | 2024-04-01 10:21:18 +0200 |
|---|---|---|
| committer | GitHub <[email protected]> | 2024-04-01 10:21:18 +0200 |
| commit | 6191a5d883048b694404dbf42527caba395828ea (patch) | |
| tree | d0f18f17789cb0bbdb5d6087f1a95772438dfe27 /test/scripts/apidoc | |
| parent | 7dae52bfcd93c41ec9d2c4dd4d96a07f31c3dfc1 (diff) | |
| download | faker-6191a5d883048b694404dbf42527caba395828ea.tar.xz faker-6191a5d883048b694404dbf42527caba395828ea.zip | |
docs: rewrite api-docs generation using ts-morph (#2628)
Diffstat (limited to 'test/scripts/apidoc')
| -rw-r--r-- | test/scripts/apidoc/.gitignore | 1 | ||||
| -rw-r--r-- | test/scripts/apidoc/__snapshots__/module.spec.ts.snap | 54 | ||||
| -rw-r--r-- | test/scripts/apidoc/__snapshots__/signature.spec.ts.snap | 768 | ||||
| -rw-r--r-- | test/scripts/apidoc/module.example.ts | 33 | ||||
| -rw-r--r-- | test/scripts/apidoc/module.spec.ts | 26 | ||||
| -rw-r--r-- | test/scripts/apidoc/signature.debug.ts | 17 | ||||
| -rw-r--r-- | test/scripts/apidoc/signature.example.ts | 391 | ||||
| -rw-r--r-- | test/scripts/apidoc/signature.spec.ts | 26 | ||||
| -rw-r--r-- | test/scripts/apidoc/utils.ts | 66 | ||||
| -rw-r--r-- | test/scripts/apidoc/verify-jsdoc-tags.spec.ts | 315 |
10 files changed, 0 insertions, 1697 deletions
diff --git a/test/scripts/apidoc/.gitignore b/test/scripts/apidoc/.gitignore deleted file mode 100644 index a6d7ecd9..00000000 --- a/test/scripts/apidoc/.gitignore +++ /dev/null @@ -1 +0,0 @@ -temp/ diff --git a/test/scripts/apidoc/__snapshots__/module.spec.ts.snap b/test/scripts/apidoc/__snapshots__/module.spec.ts.snap deleted file mode 100644 index d4275860..00000000 --- a/test/scripts/apidoc/__snapshots__/module.spec.ts.snap +++ /dev/null @@ -1,54 +0,0 @@ -// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html - -exports[`module > analyzeModule() > ModuleDeprecationTest 1`] = ` -{ - "comment": "This is a description for a module with a code example.", - "deprecated": "Well, this is deprecated.", - "examples": undefined, -} -`; - -exports[`module > analyzeModule() > ModuleExampleTest 1`] = ` -{ - "comment": "This is a description for a module with a code example.", - "deprecated": undefined, - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0"> ModuleExampleTest</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">()</span></span></code></pre> -</div>", -} -`; - -exports[`module > analyzeModule() > ModuleFakerJsLinkTest 1`] = ` -{ - "comment": "Description with a link to our [website](/) -and [api docs](/api/).", - "deprecated": undefined, - "examples": undefined, -} -`; - -exports[`module > analyzeModule() > ModuleNextFakerJsLinkTest 1`] = ` -{ - "comment": "Description with a link to our [website](/) -and [api docs](/api/).", - "deprecated": undefined, - "examples": undefined, -} -`; - -exports[`module > analyzeModule() > ModuleSimpleTest 1`] = ` -{ - "comment": "A simple module without anything special.", - "deprecated": undefined, - "examples": undefined, -} -`; - -exports[`module > analyzeModule() > expected and actual modules are equal 1`] = ` -[ - "ModuleDeprecationTest", - "ModuleExampleTest", - "ModuleFakerJsLinkTest", - "ModuleNextFakerJsLinkTest", - "ModuleSimpleTest", -] -`; diff --git a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap deleted file mode 100644 index 37a9f754..00000000 --- a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap +++ /dev/null @@ -1,768 +0,0 @@ -// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html - -exports[`signature > analyzeSignature() > complexArrayParameter 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Complex array parameter.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">complexArrayParameter</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"><</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">T</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">>(array: readonly </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">Array</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"><{</span></span> -<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70"> value</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0"> T</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">,</span></span> -<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70"> weight</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF"> number</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">}>): </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF">T</span></span></code></pre> -</div>", - "name": "complexArrayParameter", - "parameters": [ - { - "description": "<p>The type of the entries to pick from.</p> -", - "name": "<T>", - "type": undefined, - }, - { - "default": undefined, - "description": "<p>Array to pick the value from.</p> -", - "name": "array", - "type": "Array<{ ... }>", - }, - { - "default": undefined, - "description": "<p>The value to pick.</p> -", - "name": "array[].value", - "type": "T", - }, - { - "default": undefined, - "description": "<p>The weight of the value.</p> -", - "name": "array[].weight", - "type": "number", - }, - ], - "returns": "T", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L377", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > defaultBooleanParamMethod 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with a default parameter.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">defaultBooleanParamMethod</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(c: boolean </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF"> true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">): number</span></span></code></pre> -</div>", - "name": "defaultBooleanParamMethod", - "parameters": [ - { - "default": "true", - "description": "<p>The boolean parameter.</p> -", - "name": "c", - "type": "boolean", - }, - ], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L105", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > expected and actual methods are equal 1`] = ` -[ - "complexArrayParameter", - "defaultBooleanParamMethod", - "functionParamMethod", - "literalUnionParamMethod", - "methodWithDeprecated", - "methodWithDeprecatedOption", - "methodWithExample", - "methodWithMultipleSeeMarkers", - "methodWithMultipleSeeMarkersAndBackticks", - "methodWithMultipleThrows", - "methodWithSinceMarker", - "methodWithThrows", - "multiParamMethod", - "noParamMethod", - "optionalStringParamMethod", - "optionsInlineParamMethodWithDefaults", - "optionsInterfaceParamMethodWithDefaults", - "optionsParamMethod", - "optionsTypeParamMethodWithDefaults", - "recordParamMethod", - "requiredNumberParamMethod", - "stringUnionParamMethod", -] -`; - -exports[`signature > analyzeSignature() > functionParamMethod 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with a function parameters.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">functionParamMethod</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(fn: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70">a</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> number): number</span></span></code></pre> -</div>", - "name": "functionParamMethod", - "parameters": [ - { - "default": undefined, - "description": "<p>The function parameter.</p> -", - "name": "fn", - "type": "(a: string) => number", - }, - ], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L125", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > literalUnionParamMethod 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with LiteralUnion.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">literalUnionParamMethod</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF">'a'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'b'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">, namedValue</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'a'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'b'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">, array</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> readonly Array</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF">'a'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'b'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> ?></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">, namedArray</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> readonly Array</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF">'a'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'b'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> ?></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">, mixed</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'a'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'b'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> ?</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> readonly Array</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF">'a'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'b'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> ?></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">, namedMixed</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'a'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'b'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> ?</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> readonly Array</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF">'a'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'b'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> ?></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> string</span></span></code></pre> -</div>", - "name": "literalUnionParamMethod", - "parameters": [ - { - "default": undefined, - "description": "<p><code>'a'</code> or <code>'b'</code>.</p> -", - "name": "value", - "type": "'a' | 'b' | ?", - }, - { - "default": undefined, - "description": "<p><code>'a'</code> or <code>'b'</code>.</p> -", - "name": "namedValue", - "type": "'a' | 'b' | ?", - }, - { - "default": undefined, - "description": "<p>Array of <code>'a'</code> or <code>'b'</code>.</p> -", - "name": "array", - "type": "Array<'a' | 'b' | ?>", - }, - { - "default": undefined, - "description": "<p>Array of <code>'a'</code> or <code>'b'</code>.</p> -", - "name": "namedArray", - "type": "Array<'a' | 'b' | ?>", - }, - { - "default": undefined, - "description": "<p>Value <code>'a'</code> or <code>'b'</code> or an array thereof.</p> -", - "name": "mixed", - "type": "'a' | 'b' | ? | Array<'a' | 'b' | ?>", - }, - { - "default": undefined, - "description": "<p>Value <code>'a'</code> or <code>'b'</code> or an array thereof.</p> -", - "name": "namedMixed", - "type": "'a' | 'b' | ? | Array<'a' | 'b' | ?>", - }, - ], - "returns": "string", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L159", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > methodWithDeprecated 1`] = ` -{ - "deprecated": "<p>do something else</p> -", - "description": "<p>Test with deprecated and see marker.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">methodWithDeprecated</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(): number</span></span></code></pre> -</div>", - "name": "methodWithDeprecated", - "parameters": [], - "returns": "number", - "seeAlsos": [ - "test.apidoc.methodWithExample()", - ], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L287", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > methodWithDeprecatedOption 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with deprecated option.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">methodWithDeprecatedOption</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(option: {</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> a: string,</span></span> -<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0"> b</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">: () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> number,</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> c: number</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">}): number</span></span></code></pre> -</div>", - "name": "methodWithDeprecatedOption", - "parameters": [ - { - "default": undefined, - "description": "<p>The options.</p> -", - "name": "option", - "type": "{ ... }", - }, - { - "default": undefined, - "description": "<p>Some deprecated option.</p> -<p><strong>DEPRECATED:</strong> do something else.</p> -", - "name": "option.a", - "type": "string", - }, - { - "default": undefined, - "description": "<p>Some other deprecated option.</p> -<p><strong>DEPRECATED:</strong> do something else.</p> -", - "name": "option.b", - "type": "() => number", - }, - { - "default": undefined, - "description": "<p>Some other option.</p> -", - "name": "option.c", - "type": "number", - }, - ], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L318", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > methodWithExample 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with example marker.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">methodWithExample</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(): number</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">test.apidoc.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">methodWithExample</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">() </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D">// 0</span></span></code></pre> -</div>", - "name": "methodWithExample", - "parameters": [], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L276", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with multiple see markers.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">methodWithMultipleSeeMarkers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(): number</span></span></code></pre> -</div>", - "name": "methodWithMultipleSeeMarkers", - "parameters": [], - "returns": "number", - "seeAlsos": [ - "test.apidoc.methodWithExample()", - "test.apidoc.methodWithDeprecated()", - ], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L345", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBackticks 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with multiple see markers and backticks.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">methodWithMultipleSeeMarkersAndBackticks</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(): number</span></span></code></pre> -</div>", - "name": "methodWithMultipleSeeMarkersAndBackticks", - "parameters": [], - "returns": "number", - "seeAlsos": [ - "test.apidoc.methodWithExample() with parameter <code>foo</code>.", - "test.apidoc.methodWithDeprecated() with parameter <code>bar</code> and <code>baz</code>.", - ], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L355", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > methodWithMultipleThrows 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with multiple throws.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">methodWithMultipleThrows</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(): number</span></span></code></pre> -</div>", - "name": "methodWithMultipleThrows", - "parameters": [], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L306", - "throws": "First error case. -Another error case.", -} -`; - -exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with since marker.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">methodWithSinceMarker</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(): number</span></span></code></pre> -</div>", - "name": "methodWithSinceMarker", - "parameters": [], - "returns": "number", - "seeAlsos": [], - "since": "1.0.0", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L364", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > methodWithThrows 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with throws.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">methodWithThrows</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(): number</span></span></code></pre> -</div>", - "name": "methodWithThrows", - "parameters": [], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L296", - "throws": "Everytime.", -} -`; - -exports[`signature > analyzeSignature() > multiParamMethod 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with multiple parameters.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">multiParamMethod</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(a: number, b</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">?:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> string, c: boolean </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF"> true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">): number</span></span></code></pre> -</div>", - "name": "multiParamMethod", - "parameters": [ - { - "default": undefined, - "description": "<p>The number parameter.</p> -", - "name": "a", - "type": "number", - }, - { - "default": undefined, - "description": "<p>The string parameter.</p> -", - "name": "b?", - "type": "string", - }, - { - "default": "true", - "description": "<p>The boolean parameter.</p> -", - "name": "c", - "type": "boolean", - }, - ], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L116", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > noParamMethod 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with no parameters.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">noParamMethod</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(): number</span></span></code></pre> -</div>", - "name": "noParamMethod", - "parameters": [], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L78", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > optionalStringParamMethod 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with an optional parameter.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">optionalStringParamMethod</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(b</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">?:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> string): number</span></span></code></pre> -</div>", - "name": "optionalStringParamMethod", - "parameters": [ - { - "default": undefined, - "description": "<p>The string parameter.</p> -", - "name": "b?", - "type": "string", - }, - ], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L96", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > optionsInlineParamMethodWithDefaults 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with a function parameters (inline types) with defaults.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">optionsInlineParamMethodWithDefaults</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(a: {</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> value: number</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">} </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> { value: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> }, b: {</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> value: number</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">} </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> { value: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> }, c: {</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> value: number</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">}): number</span></span></code></pre> -</div>", - "name": "optionsInlineParamMethodWithDefaults", - "parameters": [ - { - "default": "{ value: 1 }", - "description": "<p>Parameter with signature default. -It also has a more complex description.</p> -", - "name": "a", - "type": "{ ... }", - }, - { - "default": undefined, - "description": "<p>The number parameter.</p> -", - "name": "a.value?", - "type": "number", - }, - { - "default": "{ value: 1 }", - "description": "<p>Parameter with jsdocs default.</p> -<p>It also has a more complex description.</p> -", - "name": "b", - "type": "{ ... }", - }, - { - "default": undefined, - "description": "<p>The number parameter.</p> -", - "name": "b.value?", - "type": "number", - }, - { - "default": undefined, - "description": "<p>Parameter with inner jsdocs default.</p> -", - "name": "c", - "type": "{ ... }", - }, - { - "default": "2", - "description": "<p>The number parameter. It also has a more complex description.</p> -", - "name": "c.value?", - "type": "number", - }, - ], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L226", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > optionsInterfaceParamMethodWithDefaults 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with a function parameters with defaults.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">optionsInterfaceParamMethodWithDefaults</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(a: ParameterOptionsInterfaceA </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> { value: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> }, b: ParameterOptionsInterfaceB </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> { value: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> }, c: ParameterOptionsInterfaceC): number</span></span></code></pre> -</div>", - "name": "optionsInterfaceParamMethodWithDefaults", - "parameters": [ - { - "default": "{ value: 1 }", - "description": "<p>Parameter with signature default.</p> -", - "name": "a", - "type": "ParameterOptionsInterfaceA", - }, - { - "default": "{ value: 1 }", - "description": "<p>Parameter with jsdocs default.</p> -", - "name": "b", - "type": "ParameterOptionsInterfaceB", - }, - { - "default": undefined, - "description": "<p>Parameter with inner jsdocs default.</p> -", - "name": "c", - "type": "ParameterOptionsInterfaceC", - }, - ], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L262", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > optionsParamMethod 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with an options parameter.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">optionsParamMethod</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(options: {</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> a: number,</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> b: string,</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> c: boolean,</span></span> -<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0"> d</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">: () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> string,</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> e: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF">'a'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'b'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> ?</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">})</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> number</span></span></code></pre> -</div>", - "name": "optionsParamMethod", - "parameters": [ - { - "default": undefined, - "description": "<p>The options parameter.</p> -", - "name": "options", - "type": "{ ... }", - }, - { - "default": undefined, - "description": "<p>The number parameter.</p> -", - "name": "options.a", - "type": "number", - }, - { - "default": undefined, - "description": "<p>The string parameter.</p> -", - "name": "options.b?", - "type": "string", - }, - { - "default": undefined, - "description": "<p>The boolean parameter.</p> -", - "name": "options.c", - "type": "boolean", - }, - { - "default": undefined, - "description": "<p>The method parameter.</p> -", - "name": "options.d", - "type": "() => string", - }, - { - "default": "'a'", - "description": "<p>A parameter with inline documentation.</p> -", - "name": "options.e", - "type": "'a' | 'b' | ?", - }, - ], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L196", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > optionsTypeParamMethodWithDefaults 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with a function parameters with defaults.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">optionsTypeParamMethodWithDefaults</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(a: ParameterOptionsTypeA </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> { value: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> }, b: ParameterOptionsTypeB </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> { value: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> }, c: ParameterOptionsTypeC): number</span></span></code></pre> -</div>", - "name": "optionsTypeParamMethodWithDefaults", - "parameters": [ - { - "default": "{ value: 1 }", - "description": "<p>Parameter with signature default.</p> -", - "name": "a", - "type": "ParameterOptionsTypeA", - }, - { - "default": "{ value: 1 }", - "description": "<p>Parameter with jsdocs default.</p> -", - "name": "b", - "type": "ParameterOptionsTypeB", - }, - { - "default": undefined, - "description": "<p>Parameter with inner jsdocs default.</p> -", - "name": "c", - "type": "ParameterOptionsTypeC", - }, - ], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L244", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > recordParamMethod 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with a Record parameter.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">recordParamMethod</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(object: Record</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"><</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">string, number</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">): number</span></span></code></pre> -</div>", - "name": "recordParamMethod", - "parameters": [ - { - "default": undefined, - "description": "<p>The Record parameter.</p> -", - "name": "object", - "type": "Record<string, number>", - }, - ], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L182", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > requiredNumberParamMethod 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with a required parameter.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">requiredNumberParamMethod</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(a: number): number</span></span></code></pre> -</div>", - "name": "requiredNumberParamMethod", - "parameters": [ - { - "default": undefined, - "description": "<p>The number parameter.</p> -", - "name": "a", - "type": "number", - }, - ], - "returns": "number", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L87", - "throws": undefined, -} -`; - -exports[`signature > analyzeSignature() > stringUnionParamMethod 1`] = ` -{ - "deprecated": undefined, - "description": "<p>Test with string union.</p> -", - "examples": "<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" v-pre><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0">stringUnionParamMethod</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">(value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF">'a'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'b'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">, options</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583">?:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> {</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> casing: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF">'lower'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'mixed'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'upper'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">,</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> excludes: readonly AlphaNumericChar[],</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8"> format: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF">'binary'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'css'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'decimal'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF"> 'hex'</span></span> -<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8">}): string</span></span></code></pre> -</div>", - "name": "stringUnionParamMethod", - "parameters": [ - { - "default": undefined, - "description": "<p><code>'a'</code> or <code>'b'</code>.</p> -", - "name": "value", - "type": "'a' | 'b'", - }, - { - "default": undefined, - "description": "<p>The options parameter.</p> -", - "name": "options?", - "type": "{ ... }", - }, - { - "default": undefined, - "description": "<p>The casing parameter.</p> -", - "name": "options.casing?", - "type": "'lower' | 'mixed' | 'upper'", - }, - { - "default": undefined, - "description": "<p>The excludes parameter.</p> -", - "name": "options.excludes?", - "type": "readonly AlphaNumericChar[]", - }, - { - "default": undefined, - "description": "<p>The format parameter.</p> -", - "name": "options.format?", - "type": "'binary' | 'css' | 'decimal' | 'hex'", - }, - ], - "returns": "string", - "seeAlsos": [], - "since": "Missing", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L138", - "throws": undefined, -} -`; diff --git a/test/scripts/apidoc/module.example.ts b/test/scripts/apidoc/module.example.ts deleted file mode 100644 index 0e5d9d89..00000000 --- a/test/scripts/apidoc/module.example.ts +++ /dev/null @@ -1,33 +0,0 @@ -/* eslint-disable @typescript-eslint/no-extraneous-class -- required for tests */ - -/** - * A simple module without anything special. - */ -export class ModuleSimpleTest {} - -/** - * Description with a link to our [website](https://fakerjs.dev/) - * and [api docs](https://fakerjs.dev/api/). - */ -export class ModuleFakerJsLinkTest {} - -/** - * Description with a link to our [website](https://next.fakerjs.dev/) - * and [api docs](https://next.fakerjs.dev/api/). - */ -export class ModuleNextFakerJsLinkTest {} - -/** - * This is a description for a module with a code example. - * - * @deprecated Well, this is deprecated. - */ -export class ModuleDeprecationTest {} - -/** - * This is a description for a module with a code example. - * - * @example - * new ModuleExampleTest() - */ -export class ModuleExampleTest {} diff --git a/test/scripts/apidoc/module.spec.ts b/test/scripts/apidoc/module.spec.ts deleted file mode 100644 index 5e55afea..00000000 --- a/test/scripts/apidoc/module.spec.ts +++ /dev/null @@ -1,26 +0,0 @@ -import { beforeAll, describe, expect, it } from 'vitest'; -import { initMarkdownRenderer } from '../../../scripts/apidoc/markdown'; -import { analyzeModule } from '../../../scripts/apidoc/module-methods'; -import * as ModuleTests from './module.example'; -import { loadExampleModules } from './utils'; - -beforeAll(initMarkdownRenderer); -const modules = await loadExampleModules(); - -describe('module', () => { - describe('analyzeModule()', () => { - it('dummy dependency to rerun the test if the example changes', () => { - expect(Object.keys(ModuleTests)).not.toEqual([]); - }); - - it('expected and actual modules are equal', () => { - expect(Object.keys(modules).sort()).toMatchSnapshot(); - }); - - it.each(Object.entries(modules))('%s', (_, module) => { - const actual = analyzeModule(module); - - expect(actual).toMatchSnapshot(); - }); - }); -}); diff --git a/test/scripts/apidoc/signature.debug.ts b/test/scripts/apidoc/signature.debug.ts deleted file mode 100644 index 704b629c..00000000 --- a/test/scripts/apidoc/signature.debug.ts +++ /dev/null @@ -1,17 +0,0 @@ -/** - * This file exists, because vitest doesn't allow me to debug code outside of src and test. - * And it's easier to test these features independently from the main project. - */ -import { initMarkdownRenderer } from '../../../scripts/apidoc/markdown'; -import { analyzeSignature } from '../../../scripts/apidoc/signature'; -import { loadExampleMethods } from './utils'; - -/* Run with `pnpm tsx test/scripts/apidoc/signature.debug.ts` */ - -await initMarkdownRenderer(); -const methods = await loadExampleMethods(); -for (const [name, method] of Object.entries(methods)) { - console.log('Analyzing:', 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 deleted file mode 100644 index c42d2d45..00000000 --- a/test/scripts/apidoc/signature.example.ts +++ /dev/null @@ -1,391 +0,0 @@ -import type { Casing, ColorFormat } from '../../../src'; -import { FakerError } from '../../../src/errors/faker-error'; -import type { AlphaNumericChar } from '../../../src/modules/string'; -import type { LiteralUnion } from '../../../src/utils/types'; -// explicitly export types so they show up in the docs as decomposed types -export type { NumberColorFormat, StringColorFormat } from '../../../src'; -export type { AlphaNumericChar, Casing, ColorFormat, LiteralUnion }; - -/** - * 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; -} - -/** - * A or B. - */ -export type AB = 'a' | 'b'; - -export class SignatureTest { - /** - * Test with no parameters. - */ - noParamMethod(): number { - return 0; - } - - /** - * Test with a required parameter. - * - * @param a The number parameter. - */ - requiredNumberParamMethod(a: number): number { - return a; - } - - /** - * Test with an optional parameter. - * - * @param b The string parameter. - */ - optionalStringParamMethod(b?: string): number { - return b ? 0 : 1; - } - - /** - * Test with a default parameter. - * - * @param c The boolean parameter. - */ - defaultBooleanParamMethod(c: boolean = true): number { - return c ? 1 : 0; - } - - /** - * Test with multiple parameters. - * - * @param a The number parameter. - * @param b The string parameter. - * @param c The boolean parameter. - */ - multiParamMethod(a: number, b?: string, c: boolean = true): number { - return c ? a : b ? 0 : 1; - } - - /** - * Test with a function parameters. - * - * @param fn The function parameter. - */ - functionParamMethod(fn: (a: string) => number): number { - return fn('a'); - } - - /** - * Test with string union. - * - * @param value `'a'` or `'b'`. - * @param options The options parameter. - * @param options.casing The casing parameter. - * @param options.format The format parameter. - * @param options.excludes The excludes parameter. - */ - stringUnionParamMethod( - value: 'a' | 'b', - options?: { - casing?: Casing; - format?: 'hex' | ColorFormat; - excludes?: ReadonlyArray<AlphaNumericChar>; - } - ): string { - return options?.format ?? value; - } - - /** - * Test with LiteralUnion. - * - * @param value `'a'` or `'b'`. - * @param namedValue `'a'` or `'b'`. - * @param array Array of `'a'` or `'b'`. - * @param namedArray Array of `'a'` or `'b'`. - * @param mixed Value `'a'` or `'b'` or an array thereof. - * @param namedMixed Value `'a'` or `'b'` or an array thereof. - */ - literalUnionParamMethod( - value: LiteralUnion<'a' | 'b'>, - namedValue: LiteralUnion<AB>, - array: ReadonlyArray<LiteralUnion<'a' | 'b'>>, - namedArray: ReadonlyArray<LiteralUnion<AB>>, - mixed: LiteralUnion<'a' | 'b'> | ReadonlyArray<LiteralUnion<'a' | 'b'>>, - namedMixed: ReadonlyArray<LiteralUnion<AB>> | LiteralUnion<AB> - ): string { - return ( - value + - namedValue + - array.join('') + - namedArray.join('') + - String(mixed) + - String(namedMixed) - ); - } - - /** - * Test with a Record parameter. - * - * @param object The Record parameter. - */ - recordParamMethod(object: Record<string, number>): 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. - * @param options.d The method parameter. - * @param options.e The LiteralUnion parameter. - */ - optionsParamMethod(options: { - a: number; - b?: string; - c: boolean; - d: () => string; - /** - * A parameter with inline documentation. - * - * @default 'a' - */ - e: LiteralUnion<'a' | 'b'>; - }): number { - return options.a; - } - - /** - * Test with a function parameters (inline types) with defaults. - * - * @param a Parameter with signature default. - * It also has a more complex description. - * @param a.value The number parameter. - * @param b Parameter with jsdocs default. - * - * It also has a more complex description. - * - * Defaults to `{ value: 1 }`. - * @param b.value The number parameter. - * @param c Parameter with inner jsdocs default. - * @param c.value The number parameter. It also has a more complex description. 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 number parameter. - * @param c Parameter with inner jsdocs default. - * @param c.value The number 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 number parameter. - * @param c Parameter with inner jsdocs default. - * @param c.value The number 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. - * - * @example - * test.apidoc.methodWithExample() // 0 - */ - methodWithExample(): number { - return 0; - } - - /** - * Test with deprecated and see marker. - * - * @see test.apidoc.methodWithExample() - * - * @deprecated do something else - */ - methodWithDeprecated(): number { - return 0; - } - - /** - * Test with throws. - * - * @throws Everytime. - */ - methodWithThrows(): number { - throw new FakerError('Test error'); - } - - /** - * Test with multiple throws. - * - * @throws First error case. - * @throws Another error case. - */ - methodWithMultipleThrows(): number { - throw new FakerError('Another test error'); - } - - /** - * Test with deprecated option. - * - * @param option The options. - * @param option.a Some deprecated option. - * @param option.b Some other deprecated option. - * @param option.c Some other option. - */ - methodWithDeprecatedOption(option: { - /** - * Some deprecated option. - * - * @deprecated do something else. - */ - a: string; - /** - * Some other deprecated option. - * - * @deprecated do something else. - */ - b: () => number; - /** - * Some other option. - */ - c: number; - }): number { - return option.c; - } - - /** - * Test with multiple see markers. - * - * @see test.apidoc.methodWithExample() - * @see test.apidoc.methodWithDeprecated() - */ - methodWithMultipleSeeMarkers(): number { - return 0; - } - - /** - * Test with multiple see markers and backticks. - * - * @see test.apidoc.methodWithExample() with parameter `foo`. - * @see test.apidoc.methodWithDeprecated() with parameter `bar` and `baz`. - */ - methodWithMultipleSeeMarkersAndBackticks(): number { - return 0; - } - - /** - * Test with since marker. - * - * @since 1.0.0 - */ - methodWithSinceMarker(): number { - return 0; - } - - /** - * Complex array parameter. - * - * @template T The type of the entries to pick from. - * - * @param array Array to pick the value from. - * @param array[].weight The weight of the value. - * @param array[].value The value to pick. - */ - complexArrayParameter<T>( - array: ReadonlyArray<{ - /** - * The weight of the value. - */ - weight: number; - /** - * The value to pick. - */ - value: T; - }> - ): T { - return array[0].value; - } -} diff --git a/test/scripts/apidoc/signature.spec.ts b/test/scripts/apidoc/signature.spec.ts deleted file mode 100644 index 51935fcf..00000000 --- a/test/scripts/apidoc/signature.spec.ts +++ /dev/null @@ -1,26 +0,0 @@ -import { beforeAll, describe, expect, it } from 'vitest'; -import { initMarkdownRenderer } from '../../../scripts/apidoc/markdown'; -import { analyzeSignature } from '../../../scripts/apidoc/signature'; -import { SignatureTest } from './signature.example'; -import { loadExampleMethods } from './utils'; - -beforeAll(initMarkdownRenderer); -const methods = await loadExampleMethods(); - -describe('signature', () => { - describe('analyzeSignature()', () => { - 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)).toMatchSnapshot(); - }); - - it.each(Object.entries(methods))('%s', async (name, signature) => { - const actual = await analyzeSignature(signature, '', name); - - expect(actual).toMatchSnapshot(); - }); - }); -}); diff --git a/test/scripts/apidoc/utils.ts b/test/scripts/apidoc/utils.ts deleted file mode 100644 index 2752f25b..00000000 --- a/test/scripts/apidoc/utils.ts +++ /dev/null @@ -1,66 +0,0 @@ -import type { - DeclarationReflection, - SignatureReflection, - TypeDocOptions, -} from 'typedoc'; -import { - loadProject, - selectApiMethodSignatures, - selectApiModules, -} from '../../../scripts/apidoc/typedoc'; -import { mapByName } from '../../../scripts/apidoc/utils'; - -/** - * Returns a record with the (Module-Name -> (Method-Name -> Method-Signature)) for the project. - * - * @param options The TypeDoc options. - * @param includeTestModules Whether to include the test modules. - */ -export async function loadProjectModules( - options?: Partial<TypeDocOptions>, - includeTestModules = false -): Promise< - Record<string, [DeclarationReflection, Record<string, SignatureReflection>]> -> { - const [, project] = await loadProject(options); - - const modules = selectApiModules(project, includeTestModules); - - return mapByName(modules, (m) => [m, selectApiMethodSignatures(m)]); -} - -/** - * Loads the example methods using TypeDoc. - */ -export async function loadExampleMethods(): Promise< - Record<string, SignatureReflection> -> { - const modules = await loadProjectModules( - { - entryPoints: ['test/scripts/apidoc/signature.example.ts'], - }, - true - ); - return modules['SignatureTest'][1]; -} - -/** - * Loads the example modules using TypeDoc. - */ -export async function loadExampleModules(): Promise< - Record<string, DeclarationReflection> -> { - const modules = await loadProjectModules( - { - entryPoints: ['test/scripts/apidoc/module.example.ts'], - }, - true - ); - - const result: Record<string, DeclarationReflection> = {}; - for (const key in modules) { - result[key] = modules[key][0]; - } - - return result; -} diff --git a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts b/test/scripts/apidoc/verify-jsdoc-tags.spec.ts deleted file mode 100644 index da34316e..00000000 --- a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts +++ /dev/null @@ -1,315 +0,0 @@ -import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'; -import { dirname, resolve } from 'node:path'; -import { fileURLToPath } from 'node:url'; -import type { ReflectionType, SomeType } from 'typedoc'; -import validator from 'validator'; -import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'; -import { initMarkdownRenderer } from '../../../scripts/apidoc/markdown'; -import { analyzeSignature } from '../../../scripts/apidoc/signature'; -import { - MISSING_DESCRIPTION, - extractDeprecated, - extractDescription, - extractJoinedRawExamples, - extractModuleFieldName, - extractRawDefault, - extractSeeAlsos, - extractSince, - extractSummaryDefault, - extractTagContent, -} from '../../../scripts/apidoc/typedoc'; -import { loadProjectModules } from './utils'; - -// This test ensures, that every method -// - has working examples -// - running these do not log anything, unless the method is deprecated - -beforeAll(initMarkdownRenderer); - -const tempDir = resolve(dirname(fileURLToPath(import.meta.url)), 'temp'); - -afterAll(() => { - // Remove temp folder - if (existsSync(tempDir)) { - rmSync(tempDir, { recursive: true }); - } -}); - -const modules = await loadProjectModules(); - -function resolveDirToModule(moduleName: string): string { - return resolve(tempDir, moduleName); -} - -function resolvePathToMethodFile( - moduleName: string, - methodName: string -): string { - const dir = resolveDirToModule(moduleName); - return resolve(dir, `${methodName}.ts`); -} - -const allowedReferences = new Set( - Object.values(modules).flatMap(([module, methods]) => { - const moduleFieldName = extractModuleFieldName(module); - return Object.keys(methods).map( - (methodName) => `faker.${moduleFieldName}.${methodName}` - ); - }) -); -const allowedLinks = new Set( - Object.values(modules).flatMap(([module, methods]) => { - const moduleFieldName = extractModuleFieldName(module); - return [ - `/api/${moduleFieldName}.html`, - ...Object.keys(methods).map( - (methodName) => - `/api/${moduleFieldName}.html#${methodName.toLowerCase()}` - ), - ]; - }) -); - -function assertDescription(description: string, isHtml: boolean): void { - const linkRegexp = isHtml ? /(href)="([^"]+)"/g : /\[([^\]]+)\]\(([^)]+)\)/g; - const links = [...description.matchAll(linkRegexp)].map((m) => m[2]); - - for (const link of links) { - if (!isHtml) { - expect(link).toMatch(/^https?:\/\//); - expect(link).toSatisfy(validator.isURL); - } - - if (isHtml ? link.startsWith('/api/') : link.includes('fakerjs.dev/api/')) { - expect(allowedLinks, `${link} to point to a valid target`).toContain( - link.replace(/.*fakerjs.dev\//, '/') - ); - } - } -} - -// keep in sync with analyzeParameterOptions -function assertNestedParameterDefault( - name: string, - parameterType?: SomeType -): void { - if (!parameterType) { - return; - } - - switch (parameterType.type) { - case 'array': { - return assertNestedParameterDefault( - `${name}[]`, - parameterType.elementType - ); - } - - case 'union': { - for (const type of parameterType.types) { - assertNestedParameterDefault(name, type); - } - - return; - } - - case 'reflection': { - for (const property of parameterType.declaration.children ?? []) { - const reflection = property.comment - ? property - : (property.type as ReflectionType)?.declaration?.signatures?.[0]; - const comment = reflection?.comment; - const tagDefault = extractRawDefault({ comment }) || undefined; - const summaryDefault = extractSummaryDefault(comment, false); - - if (summaryDefault) { - expect( - tagDefault, - `Expect jsdoc summary default and @default for ${name}.${property.name} to be the same` - ).toBe(summaryDefault); - } - } - - return; - } - - case 'typeOperator': { - return assertNestedParameterDefault(name, parameterType.target); - } - - default: { - return; - } - } -} - -describe('verify JSDoc tags', () => { - describe.each(Object.entries(modules))( - '%s', - (moduleName, [module, methodsByName]) => { - describe('verify module', () => { - it('verify description', () => { - const description = extractDescription(module); - assertDescription(description, false); - }); - }); - - describe.each(Object.entries(methodsByName))( - '%s', - (methodName, signature) => { - beforeAll(() => { - // Write temp files to disk - - // Extract examples and make them runnable - const examples = extractJoinedRawExamples(signature) ?? ''; - - // Save examples to a file to run them later in the specific tests - const dir = resolveDirToModule(moduleName); - mkdirSync(dir, { recursive: true }); - - const path = resolvePathToMethodFile(moduleName, methodName); - const imports = [ - ...new Set(examples.match(/(?<!\.)faker[^.]*(?=\.)/g)), - ]; - writeFileSync( - path, - `import { ${imports.join( - ', ' - )} } from '../../../../../src';\n\n${examples}` - ); - }); - - it('verify description', () => { - const description = extractDescription(signature); - assertDescription(description, false); - }); - - it('verify @example tag', async () => { - // Extract the examples - const examples = extractJoinedRawExamples(signature); - - expect( - examples, - `${moduleName}.${methodName} to have examples` - ).not.toBe(''); - - // Grab path to example file - const path = resolvePathToMethodFile(moduleName, methodName); - - // Executing the examples should not throw - await expect( - import(`${path}?scope=example`) - ).resolves.toBeDefined(); - }); - - // This only checks whether the whole method is deprecated or not - // It does not check whether the method is deprecated for a specific set of arguments - it('verify @deprecated tag', async () => { - // Grab path to example file - const path = resolvePathToMethodFile(moduleName, methodName); - - const consoleWarnSpy = vi.spyOn(console, 'warn'); - - // Run the examples - await import(`${path}?scope=deprecated`); - - // Verify that deprecated methods log a warning - const deprecatedFlag = extractDeprecated(signature) !== undefined; - if (deprecatedFlag) { - expect(consoleWarnSpy).toHaveBeenCalled(); - expect( - extractTagContent('@deprecated', signature).join(''), - '@deprecated tag without message' - ).not.toBe(''); - } else { - expect(consoleWarnSpy).not.toHaveBeenCalled(); - } - }); - - it('verify @param tags', async () => { - // This must run before analyzeSignature - for (const param of signature.parameters ?? []) { - const type = param.type; - const paramDefault = param.defaultValue; - const commentDefault = extractSummaryDefault( - param.comment, - false - ); - if (paramDefault) { - if ( - /^{.*}$/.test(paramDefault) || - paramDefault.includes('\n') - ) { - expect(commentDefault).toBeUndefined(); - } else { - expect( - commentDefault, - `Expect '${param.name}'s js implementation default to be the same as the jsdoc summary default.` - ).toBe(paramDefault); - } - } - - assertNestedParameterDefault(param.name, type); - } - - for (const param of ( - await analyzeSignature(signature, '', methodName) - ).parameters) { - const { name, description } = param; - const plainDescription = description - .replaceAll(/<[^>]+>/g, '') - .trim(); - expect( - plainDescription, - `Expect param ${name} to have a description` - ).not.toBe(MISSING_DESCRIPTION); - assertDescription(description, true); - } - }); - - it('verify @see tags', () => { - for (const link of extractSeeAlsos(signature)) { - if (link.startsWith('faker.')) { - // Expected @see faker.xxx.yyy() - expect(link, 'Expect method reference to contain ()').toContain( - '(' - ); - expect(link, 'Expect method reference to contain ()').toContain( - ')' - ); - expect( - link, - "Expect method reference to have a ': ' after the parenthesis" - ).toContain('): '); - expect( - link, - 'Expect method reference to have a description starting with a capital letter' - ).toMatch(/\): [A-Z]/); - expect( - link, - 'Expect method reference to start with a standard description phrase' - ).toMatch( - /\): (?:For generating |For more information about |For using |For the replacement method)/ - ); - expect( - link, - 'Expect method reference to have a description ending with a dot' - ).toMatch(/\.$/); - expect(allowedReferences).toContain(link.replace(/\(.*/, '')); - } - } - }); - - it('verify @since tag', () => { - const since = extractSince(signature); - expect(since, '@since to be present').toBeTruthy(); - expect(since).not.toBe(MISSING_DESCRIPTION); - expect(since, '@since to be a valid semver').toSatisfy( - validator.isSemVer - ); - }); - } - ); - } - ); -}); |
