docs: properly handle multiple `@see` tags (#1270)

2 files changed, 24 insertions, 6 deletions

diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts
index ce037988..62b65ee8 100644
--- a/scripts/apidoc/signature.ts
+++ b/scripts/apidoc/signature.ts
@@ -20,7 +20,7 @@ import vitepressConfig from '../../docs/.vitepress/config';
 import { faker } from '../../src';
 import {
   extractRawExamples,
-  extractTagContent,
+  extractSeeAlsos,
   formatTypescript,
   isDeprecated,
   joinTagParts,
@@ -143,7 +143,7 @@ export function analyzeSignature(
     examples += `${exampleTags.join('\n').trim()}\n`;
   }
 
-  const seeAlsos = extractTagContent('@see', signature);
+  const seeAlsos = extractSeeAlsos(signature);
 
   const prettyMethodName = prettifyMethodName(methodName);
   const code = '```';
diff --git a/scripts/apidoc/utils.ts b/scripts/apidoc/utils.ts
index f4f0d3f7..783bf974 100644
--- a/scripts/apidoc/utils.ts
+++ b/scripts/apidoc/utils.ts
@@ -89,9 +89,10 @@ const prettierTypescript: Options = {
  */
 export function extractTagContent(
   tag: `@${string}`,
-  signature?: SignatureReflection
+  signature?: SignatureReflection,
+  tagProcessor: (tag: CommentTag) => string[] = joinTagContent
 ): string[] {
-  return signature?.comment?.getTags(tag).map(joinTagContent) ?? [];
+  return signature?.comment?.getTags(tag).flatMap(tagProcessor) ?? [];
 }
 
 /**
@@ -106,10 +107,27 @@ export function extractRawExamples(signature?: SignatureReflection): string[] {
 }
 
 /**
+ * Extracts all the `@see` references from the jsdocs separately.
+ *
+ * @param signature The signature to extract the see also references from.
+ */
+export function extractSeeAlsos(signature?: SignatureReflection): string[] {
+  return extractTagContent('@see', signature, (tag) => {
+    const content = tag.content;
+    if (content.length === 1) {
+      return joinTagContent(tag);
+    }
+    return tag.content
+      .filter((_, index) => index % 3 === 1) // ['-', 'content', '\n']
+      .map((part) => part.text);
+  });
+}
+
+/**
  * Joins the parts of the given jsdocs tag.
  */
-export function joinTagContent(tag: CommentTag): string {
-  return joinTagParts(tag?.content);
+export function joinTagContent(tag: CommentTag): string[] {
+  return [joinTagParts(tag?.content)];
 }
 
 export function joinTagParts(parts: CommentDisplayPart[]): string;