test(docs): ensure defaults are consistent (#2177)

3 files changed, 75 insertions, 30 deletions

diff --git a/scripts/apidoc/parameter-defaults.ts b/scripts/apidoc/parameter-defaults.ts
index 34264b05..c2eecdc2 100644
--- a/scripts/apidoc/parameter-defaults.ts
+++ b/scripts/apidoc/parameter-defaults.ts
@@ -58,7 +58,7 @@ function cleanParameterDefault(value?: string): string | undefined {
   }
 
   // Strip type casts: "'foobar' as unknown as T" => "'foobar'"
-  return value.replace(/ as unknown as [A-Za-z<>]+/, '');
+  return value.replace(/( as unknown)? as [A-Za-z<>]+/, '');
 }
 
 /**
diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts
index 43026a78..08fe5896 100644
--- a/scripts/apidoc/signature.ts
+++ b/scripts/apidoc/signature.ts
@@ -23,8 +23,8 @@ import {
   extractSeeAlsos,
   extractSince,
   extractSourcePath,
+  extractSummaryDefault,
   extractThrows,
-  joinTagParts,
   toBlock,
 } from './typedoc';
 
@@ -108,8 +108,7 @@ async function analyzeParameter(parameter: ParameterReflection): Promise<{
   const name = parameter.name;
   const declarationName = name + (isOptional(parameter) ? '?' : '');
   const type = parameter.type;
-  const commentDefault = extractDefaultFromComment(parameter.comment);
-  const defaultValue = parameter.defaultValue ?? commentDefault;
+  const defaultValue = extractDefaultFromParameter(parameter);
 
   let signatureText = '';
   if (defaultValue) {
@@ -136,6 +135,7 @@ async function analyzeParameter(parameter: ParameterReflection): Promise<{
   };
 }
 
+// keep in sync with assertNestedParameterDefault
 async function analyzeParameterOptions(
   name: string,
   parameterType?: SomeType
@@ -311,39 +311,41 @@ async function signatureTypeToText(
 }
 
 /**
- * Extracts and removed the parameter default from the comments.
+ * Extracts and optionally removes the parameter default from the parameter.
+ *
+ * @param parameter The parameter to extract the default from.
+ * @param eraseDefault Whether to erase the default text from the parameter comment.
+ *
+ * @returns The extracted default value.
+ */
+function extractDefaultFromParameter(
+  parameter: ParameterReflection,
+  eraseDefault = true
+): string | undefined {
+  const commentDefault = extractDefaultFromComment(
+    parameter.comment,
+    eraseDefault
+  );
+  return parameter.defaultValue ?? commentDefault;
+}
+
+/**
+ * Extracts and optionally removes the parameter default from the comments.
  *
  * @param comment The comment to extract the default from.
+ * @param eraseDefault Whether to erase the default text from the comment.
  *
  * @returns The extracted default value.
  */
-function extractDefaultFromComment(comment?: Comment): string | undefined {
+function extractDefaultFromComment(
+  comment?: Comment,
+  eraseDefault = true
+): string | undefined {
   if (!comment) {
     return;
   }
 
-  const defaultTag = comment.getTag('@default');
-  if (defaultTag) {
-    return extractRawDefault({ comment });
-  }
-
-  const summary = comment.summary;
-  const text = joinTagParts(summary).trim();
-  if (!text) {
-    return;
-  }
-
-  const result = /^(.*)[ \n]Defaults to `([^`]+)`\.(.*)$/s.exec(text);
-  if (!result) {
-    return;
-  }
-
-  if (result[3].trim()) {
-    throw new Error(`Found description text after the default value:\n${text}`);
-  }
-
-  summary.splice(-2, 2);
-  const lastSummaryPart = summary[summary.length - 1];
-  lastSummaryPart.text = lastSummaryPart.text.replace(/[ \n]Defaults to $/, '');
-  return result[2];
+  const tagDefault = extractRawDefault({ comment });
+  const summaryDefault = extractSummaryDefault(comment, eraseDefault);
+  return tagDefault || summaryDefault;
 }
diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts
index 0d3799df..12b474b0 100644
--- a/scripts/apidoc/typedoc.ts
+++ b/scripts/apidoc/typedoc.ts
@@ -247,6 +247,49 @@ export function extractRawDefault(reflection?: CommentHolder): string {
 }
 
 /**
+ * Extracts and optionally removes the default from the comment summary.
+ *
+ * @param comment The comment to extract the default from.
+ * @param eraseDefault Whether to erase the default text from the comment.
+ *
+ * @returns The extracted default value.
+ */
+export function extractSummaryDefault(
+  comment?: Comment,
+  eraseDefault = true
+): string | undefined {
+  if (!comment) {
+    return;
+  }
+
+  const summary = comment.summary;
+  const text = joinTagParts(summary).trim();
+  if (!text) {
+    return;
+  }
+
+  const result = /^(.*)[ \n]Defaults to `([^`]+)`\.(.*)$/s.exec(text);
+  if (!result) {
+    return;
+  }
+
+  if (result[3].trim()) {
+    throw new Error(`Found description text after the default value:\n${text}`);
+  }
+
+  if (eraseDefault) {
+    summary.splice(-2, 2);
+    const lastSummaryPart = summary[summary.length - 1];
+    lastSummaryPart.text = lastSummaryPart.text.replace(
+      /[ \n]Defaults to $/,
+      ''
+    );
+  }
+
+  return result[2];
+}
+
+/**
  * Extracts the examples from the jsdocs without the surrounding md code block.
  *
  * @param reflection The reflection to extract the examples from.