docs(datatype): allow markdown in @see links (#1667)

2 files changed, 25 insertions, 12 deletions

diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts
index 0e85b22b..72036a43 100644
--- a/scripts/apidoc/signature.ts
+++ b/scripts/apidoc/signature.ts
@@ -81,8 +81,14 @@ function comparableSanitizedHtml(html: string): string {
     .replace(/'/g, "'");
 }
 
-function mdToHtml(md: string): string {
-  const rawHtml = markdown.render(md);
+/**
+ * Converts Markdown to an HTML string and sanitizes it.
+ * @param md The markdown to convert.
+ * @param inline Whether to render the markdown as inline, without a wrapping `<p>` tag. Defaults to `false`.
+ * @returns The converted HTML string.
+ */
+function mdToHtml(md: string, inline: boolean = false): string {
+  const rawHtml = inline ? markdown.renderInline(md) : markdown.render(md);
 
   const safeHtml: string = sanitizeHtml(rawHtml, htmlSanitizeOptions);
   // Revert some escaped characters for comparison.
@@ -164,7 +170,9 @@ export function analyzeSignature(
     examples += `${exampleTags.join('\n').trim()}\n`;
   }
 
-  const seeAlsos = extractSeeAlsos(signature);
+  const seeAlsos = extractSeeAlsos(signature).map((seeAlso) =>
+    mdToHtml(seeAlso, true)
+  );
 
   const prettyMethodName = prettifyMethodName(methodName);
   const code = '```';
diff --git a/scripts/apidoc/utils.ts b/scripts/apidoc/utils.ts
index 651a0119..ef26a67d 100644
--- a/scripts/apidoc/utils.ts
+++ b/scripts/apidoc/utils.ts
@@ -112,15 +112,20 @@ export function extractRawExamples(signature?: SignatureReflection): string[] {
  * @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);
-  });
+  return extractTagContent('@see', signature, (tag) =>
+    // If the @see tag contains code in backticks, the content is split into multiple parts.
+    // So we join together, split on newlines and filter out empty tags.
+    joinTagParts(tag.content)
+      .split('\n')
+      .map((link) => {
+        link = link.trim();
+        if (link.startsWith('-')) {
+          link = link.slice(1).trim();
+        }
+        return link;
+      })
+      .filter((link) => link)
+  );
 }
 
 /**