From 3793ec1baffbf0d41b3f49fa94380ffd4048b054 Mon Sep 17 00:00:00 2001
From: Matt Mayer <matt@lemi.travel>
Date: Tue, 27 Dec 2022 00:30:18 +0700
Subject: docs(datatype): allow markdown in @see links (#1667)

---
 docs/.vitepress/components/api-docs/method.vue     | 10 ++++++----
 scripts/apidoc/signature.ts                        | 14 ++++++++++---
 scripts/apidoc/utils.ts                            | 23 +++++++++++++---------
 .../apidoc/__snapshots__/signature.spec.ts.snap    | 21 ++++++++++++++++++++
 test/scripts/apidoc/signature.example.ts           | 10 ++++++++++
 5 files changed, 62 insertions(+), 16 deletions(-)

diff --git a/docs/.vitepress/components/api-docs/method.vue b/docs/.vitepress/components/api-docs/method.vue
index db98657a..c24565ee 100644
--- a/docs/.vitepress/components/api-docs/method.vue
+++ b/docs/.vitepress/components/api-docs/method.vue
@@ -39,10 +39,12 @@ function seeAlsoToUrl(see: string): string {
       <h3>See Also</h3>
       <ul>
         <li v-for="seeAlso of props.method.seeAlsos" :key="seeAlso">
-          <a v-if="seeAlso.startsWith('faker.')" :href="seeAlsoToUrl(seeAlso)">
-            {{ seeAlso }}
-          </a>
-          <template v-else>{{ seeAlso }}</template>
+          <a
+            v-if="seeAlso.startsWith('faker.')"
+            :href="seeAlsoToUrl(seeAlso)"
+            v-html="seeAlso"
+          />
+          <template v-else v-html="seeAlso" />
         </li>
       </ul>
     </div>
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(/&#39;/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)
+  );
 }
 
 /**
diff --git a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap
index 46bb3eca..1a3612da 100644
--- a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap
+++ b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap
@@ -33,6 +33,7 @@ exports[`signature > analyzeSignature() > expected and actual methods are equal
   "methodWithDeprecated",
   "methodWithExample",
   "methodWithMultipleSeeMarkers",
+  "methodWithMultipleSeeMarkersAndBackticks",
   "methodWithSinceMarker",
   "multiParamMethod",
   "noParamMethod",
@@ -153,6 +154,26 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = `
 }
 `;
 
+exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBackticks 1`] = `
+{
+  "deprecated": false,
+  "description": "<p>Test with multiple see markers and backticks.</p>
+",
+  "examples": "<div class=\\"language-ts\\"><button title=\\"Copy Code\\" class=\\"copy\\"></button><span class=\\"lang\\">ts</span><pre v-pre class=\\"shiki material-palenight\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">methodWithMultipleSeeMarkersAndBackticks</span><span style=\\"color:#A6ACCD\\">(): number</span></span>
+<span class=\\"line\\"></span></code></pre>
+</div>",
+  "name": "methodWithMultipleSeeMarkersAndBackticks",
+  "parameters": [],
+  "returns": "number",
+  "seeAlsos": [
+    "test.apidoc.methodWithExample() with parameter <code>foo</code>.",
+    "test.apidoc.methodWithDeprecated() with parameter <code>bar</code> and <code>baz</code>.",
+  ],
+  "since": "",
+  "title": "Method With Multiple See Markers And Backticks",
+}
+`;
+
 exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = `
 {
   "deprecated": false,
diff --git a/test/scripts/apidoc/signature.example.ts b/test/scripts/apidoc/signature.example.ts
index 43407ab9..83bf5ce3 100644
--- a/test/scripts/apidoc/signature.example.ts
+++ b/test/scripts/apidoc/signature.example.ts
@@ -241,6 +241,16 @@ export class SignatureTest {
     return 0;
   }
 
+  /**
+   * Test with multiple see markers and backticks.
+   *
+   * @see test.apidoc.methodWithExample() with parameter `foo`.
+   * @see test.apidoc.methodWithDeprecated() with parameter `bar` and `baz`.
+   */
+  methodWithMultipleSeeMarkersAndBackticks(): number {
+    return 0;
+  }
+
   /**
    * Test with since marker.
    *
-- 
cgit v1.2.3