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

Author: ST-DDT

docs/.vitepress/components/api-docs/method.vue

@@ -30,12 +30,14 @@ function seeAlsoToUrl(see: string): string {
 
     <div v-if="props.method.seeAlsos.length > 0">
       <h3>See Also</h3>
-      <div v-for="seeAlso of props.method.seeAlsos" :key="seeAlso">
-        <a :href="seeAlsoToUrl(seeAlso)" v-if="seeAlso.startsWith('faker.')">
-          <p>{{ seeAlso }}</p>
-        </a>
-        <p v-else>{{ seeAlso }}</p>
-      </div>
+      <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>
+        </li>
+      </ul>
     </div>
   </div>
 </template>

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

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) ?? [];
 }
 
 /**
@@ -105,11 +106,28 @@ 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;

test/scripts/apidoc/examplesAndDeprecations.spec.ts

@@ -8,6 +8,7 @@ import { selectDirectMethods } from '../../../scripts/apidoc/directMethods';
 import { selectApiModules } from '../../../scripts/apidoc/moduleMethods';
 import {
   extractRawExamples,
+  extractSeeAlsos,
   extractTagContent,
   isDeprecated,
 } from '../../../scripts/apidoc/utils';
@@ -111,8 +112,8 @@ describe('examples and deprecations', () => {
       }
 
       // Verify @see tag
-      extractTagContent('@see', signature).forEach((link) => {
-        if (link.startsWith('faker')) {
+      extractSeeAlsos(signature).forEach((link) => {
+        if (link.startsWith('faker.')) {
           // Expected @see faker.xxx.yyy()
           expect(link, 'Expect method reference to contain ()').toContain('(');
           expect(link, 'Expect method reference to contain ()').toContain(')');

test/scripts/apidoc/signature.debug.ts

@@ -2,15 +2,22 @@
  * This file exists, because vitest doesn't allow me to debug code outside of src and test.
  * And it's easier to test these features independently from the main project.
  */
-import { analyzeSignature } from '../../../scripts/apidoc/signature';
+import {
+  analyzeSignature,
+  initMarkdownRenderer,
+} from '../../../scripts/apidoc/signature';
 import { loadExampleMethods } from './utils';
 
 /* Run with `pnpm tsx test/scripts/apidoc/signature.debug.ts` */
 
 const methods = loadExampleMethods();
 
-Object.entries(methods).forEach(([name, method]) => {
-  console.log('Analyzing: ', name);
-  const result = analyzeSignature(method.signatures[0], null, method.name);
-  console.log('Result: ', result);
-});
+initMarkdownRenderer()
+  .then(() => {
+    Object.entries(methods).forEach(([name, method]) => {
+      console.log('Analyzing: ', name);
+      const result = analyzeSignature(method.signatures[0], null, method.name);
+      console.log('Result: ', result);
+    });
+  })
+  .catch(console.error);

test/scripts/apidoc/signature.example.ts

@@ -230,4 +230,14 @@ export class SignatureTest {
   methodWithDeprecated(): number {
     return 0;
   }
+
+  /**
+   * Test with multiple see markers.
+   *
+   * @see test.apidoc.methodWithExample()
+   * @see test.apidoc.methodWithDeprecated()
+   */
+  methodWithMultipleSeeMarkers(): number {
+    return 0;
+  }
 }

test/scripts/apidoc/signature.expected.json

@@ -68,6 +68,19 @@
     "deprecated": false,
     "seeAlsos": []
   },
+  "methodWithMultipleSeeMarkers": {
+    "name": "methodWithMultipleSeeMarkers",
+    "title": "Method With Multiple See Markers",
+    "description": "<p>Test with multiple see markers.</p>\n",
+    "parameters": [],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><button class=\"copy\"></button><span class=\"lang\">ts</span><pre v-pre><code><span class=\"line\"><span style=\"color: #A6ACCD\">faker</span><span style=\"color: #89DDFF\">.</span><span style=\"color: #82AAFF\">methodWithMultipleSeeMarkers</span><span style=\"color: #A6ACCD\">(): number</span></span>\n<span class=\"line\"></span></code></pre>\n</div>",
+    "deprecated": false,
+    "seeAlsos": [
+      "test.apidoc.methodWithExample()",
+      "test.apidoc.methodWithDeprecated()"
+    ]
+  },
   "multiParamMethod": {
     "name": "multiParamMethod",
     "title": "Multi Param Method",