From ec4d428863a4aa670338b22439031495911fbd1b Mon Sep 17 00:00:00 2001
From: Matt Mayer <152770+matthewmayer@users.noreply.github.com>
Date: Sun, 16 Apr 2023 20:03:38 +0700
Subject: docs: document @throws parameter in API docs (#2050)

---
 scripts/apidoc/signature.ts |  5 +++++
 scripts/apidoc/typedoc.ts   | 12 ++++++++++++
 2 files changed, 17 insertions(+)

(limited to 'scripts')

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
@@ -286,6 +286,18 @@ export function extractDeprecated(
   return deprecated.length === 0 ? undefined : deprecated;
 }
 
+/**
+ * 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.
  *
-- 
cgit v1.2.3