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

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>

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 = '```';

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)
+  );
 }
 
 /**

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,

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.
    *