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

2 files changed, 17 insertions, 0 deletions

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.