docs: document @throws parameter in API docs (#2050)

6 files changed, 88 insertions, 19 deletions

diff --git a/docs/.vitepress/components/api-docs/method.ts b/docs/.vitepress/components/api-docs/method.ts
index 6601a5ca..3c1b9b95 100644
--- a/docs/.vitepress/components/api-docs/method.ts
+++ b/docs/.vitepress/components/api-docs/method.ts
@@ -8,6 +8,7 @@ export interface Method {
   readonly since: string;
   readonly sourcePath: string; // URL-Suffix
   readonly seeAlsos: string[];
+  readonly throws?: string; // HTML
 }
 
 export interface MethodParameter {
diff --git a/docs/.vitepress/components/api-docs/method.vue b/docs/.vitepress/components/api-docs/method.vue
index 38d10586..2b3f0c5b 100644
--- a/docs/.vitepress/components/api-docs/method.vue
+++ b/docs/.vitepress/components/api-docs/method.vue
@@ -36,6 +36,10 @@ function seeAlsoToUrl(see: string): string {
 
     <p><strong>Returns:</strong> {{ props.method.returns }}</p>
 
+    <p v-if="props.method.throws">
+      <strong>Throws:</strong> <span v-html="props.method.throws" />
+    </p>
+
     <div v-html="props.method.examples" />
 
     <div v-if="props.method.seeAlsos.length > 0">
diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts
index 3d8fd6f7..8b5083ae 100644
--- a/scripts/apidoc/signature.ts
+++ b/scripts/apidoc/signature.ts
@@ -25,6 +25,7 @@ import {
   extractSeeAlsos,
   extractSince,
   extractSourcePath,
+  extractThrows,
   joinTagParts,
 } from './typedoc';
 import { pathOutputDir } from './utils';
@@ -160,12 +161,16 @@ export function analyzeSignature(
   const deprecated = deprecatedMessage
     ? mdToHtml(deprecatedMessage)
     : undefined;
+  const throwsMessage = extractThrows(signature);
+  const throws = throwsMessage ? mdToHtml(throwsMessage, true) : undefined;
+
   return {
     name: methodName,
     description: mdToHtml(toBlock(signature.comment)),
     parameters: parameters,
     since: extractSince(signature),
     sourcePath: extractSourcePath(signature),
+    throws,
     returns: typeToText(signature.type),
     examples: mdToHtml(`${code}ts\n${examples}${code}`),
     deprecated,
diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts
index 7fc1450b..858171ac 100644
--- a/scripts/apidoc/typedoc.ts
+++ b/scripts/apidoc/typedoc.ts
@@ -287,6 +287,18 @@ export function extractDeprecated(
 }
 
 /**
+ * Extracts the "throws" tag from the provided signature.
+ *
+ * @param reflection The reflection to check.
+ *
+ * @returns The message explaining the conditions when this method throws. Or `undefined` if it does not throw.
+ */
+export function extractThrows(reflection?: CommentHolder): string | undefined {
+  const throws = extractTagContent('@throws', reflection).join().trim();
+  return throws.length === 0 ? undefined : throws;
+}
+
+/**
  * Extracts the "since" tag from the provided signature.
  *
  * @param reflection The signature to check.
diff --git a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap
index bd916f0e..15bb4d00 100644
--- a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap
+++ b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap
@@ -43,7 +43,8 @@ exports[`signature > analyzeSignature() > complexArrayParameter 1`] = `
   "returns": "T",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L346",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L356",
+  "throws": undefined,
 }
 `;
 
@@ -67,7 +68,8 @@ exports[`signature > analyzeSignature() > defaultBooleanParamMethod 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L104",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L105",
+  "throws": undefined,
 }
 `;
 
@@ -83,6 +85,7 @@ exports[`signature > analyzeSignature() > expected and actual methods are equal
   "methodWithMultipleSeeMarkers",
   "methodWithMultipleSeeMarkersAndBackticks",
   "methodWithSinceMarker",
+  "methodWithThrows",
   "multiParamMethod",
   "noParamMethod",
   "optionalStringParamMethod",
@@ -115,7 +118,8 @@ exports[`signature > analyzeSignature() > functionParamMethod 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L124",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L125",
+  "throws": undefined,
 }
 `;
 
@@ -174,7 +178,8 @@ exports[`signature > analyzeSignature() > literalUnionParamMethod 1`] = `
   "returns": "string",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L158",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L159",
+  "throws": undefined,
 }
 `;
 
@@ -193,7 +198,8 @@ exports[`signature > analyzeSignature() > methodWithDeprecated 1`] = `
     "test.apidoc.methodWithExample()",
   ],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L276",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L277",
+  "throws": undefined,
 }
 `;
 
@@ -244,7 +250,8 @@ exports[`signature > analyzeSignature() > methodWithDeprecatedOption 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L288",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L298",
+  "throws": undefined,
 }
 `;
 
@@ -261,7 +268,8 @@ exports[`signature > analyzeSignature() > methodWithExample 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L265",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L266",
+  "throws": undefined,
 }
 `;
 
@@ -280,7 +288,8 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = `
     "test.apidoc.methodWithDeprecated()",
   ],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L315",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L325",
+  "throws": undefined,
 }
 `;
 
@@ -299,7 +308,8 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBacktic
     "test.apidoc.methodWithDeprecated() with parameter <code>bar</code> and <code>baz</code>.",
   ],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L325",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L335",
+  "throws": undefined,
 }
 `;
 
@@ -315,7 +325,25 @@ exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "1.0.0",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L334",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L344",
+  "throws": undefined,
+}
+`;
+
+exports[`signature > analyzeSignature() > methodWithThrows 1`] = `
+{
+  "deprecated": undefined,
+  "description": "<p>Test with throws</p>
+",
+  "examples": "<div class=\\"language-ts\\"><button title=\\"Copy Code\\" class=\\"copy\\"></button><span class=\\"lang\\">ts</span><pre v-pre class=\\"shiki material-theme-palenight\\"><code><span class=\\"line\\"><span style=\\"color:#82AAFF\\">methodWithThrows</span><span style=\\"color:#A6ACCD\\">(): number</span></span></code></pre>
+</div>",
+  "name": "methodWithThrows",
+  "parameters": [],
+  "returns": "number",
+  "seeAlsos": [],
+  "since": "",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L286",
+  "throws": "a Faker error",
 }
 `;
 
@@ -353,7 +381,8 @@ exports[`signature > analyzeSignature() > multiParamMethod 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L115",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L116",
+  "throws": undefined,
 }
 `;
 
@@ -369,7 +398,8 @@ exports[`signature > analyzeSignature() > noParamMethod 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L77",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L78",
+  "throws": undefined,
 }
 `;
 
@@ -393,7 +423,8 @@ exports[`signature > analyzeSignature() > optionalStringParamMethod 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L95",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L96",
+  "throws": undefined,
 }
 `;
 
@@ -460,7 +491,8 @@ It also has a more complex description.</p>
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L215",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L216",
+  "throws": undefined,
 }
 `;
 
@@ -498,7 +530,8 @@ exports[`signature > analyzeSignature() > optionsInterfaceParamMethodWithDefault
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L251",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L252",
+  "throws": undefined,
 }
 `;
 
@@ -563,7 +596,8 @@ exports[`signature > analyzeSignature() > optionsParamMethod 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L185",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L186",
+  "throws": undefined,
 }
 `;
 
@@ -601,7 +635,8 @@ exports[`signature > analyzeSignature() > optionsTypeParamMethodWithDefaults 1`]
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L233",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L234",
+  "throws": undefined,
 }
 `;
 
@@ -625,7 +660,8 @@ exports[`signature > analyzeSignature() > requiredNumberParamMethod 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L86",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L87",
+  "throws": undefined,
 }
 `;
 
@@ -681,6 +717,7 @@ exports[`signature > analyzeSignature() > stringUnionParamMethod 1`] = `
   "returns": "string",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L137",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L138",
+  "throws": undefined,
 }
 `;
diff --git a/test/scripts/apidoc/signature.example.ts b/test/scripts/apidoc/signature.example.ts
index f84112db..97db90c8 100644
--- a/test/scripts/apidoc/signature.example.ts
+++ b/test/scripts/apidoc/signature.example.ts
@@ -1,4 +1,5 @@
 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
@@ -278,6 +279,15 @@ export class SignatureTest {
   }
 
   /**
+   * Test with throws
+   *
+   * @throws a Faker error
+   */
+  methodWithThrows(): number {
+    throw new FakerError('Test error');
+  }
+
+  /**
    * Test with deprecated option.
    *
    * @param option The options.