docs: mark deprecated parameter options (#1962)

5 files changed, 133 insertions, 36 deletions

diff --git a/docs/.vitepress/components/api-docs/method-parameters.vue b/docs/.vitepress/components/api-docs/method-parameters.vue
index ca3aef37..fbc28635 100644
--- a/docs/.vitepress/components/api-docs/method-parameters.vue
+++ b/docs/.vitepress/components/api-docs/method-parameters.vue
@@ -19,7 +19,13 @@ const props = defineProps<{ parameters: MethodParameter[] }>();
       </thead>
       <tbody>
         <tr v-for="parameter of props.parameters" :key="parameter.name">
-          <td>{{ parameter.name }}</td>
+          <td
+            :class="{
+              deprecated: parameter.description.includes('DEPRECATED'),
+            }"
+          >
+            {{ parameter.name }}
+          </td>
           <td>{{ parameter.type }}</td>
           <td>
             <code v-if="parameter.default">{{ parameter.default }}</code>
@@ -30,3 +36,9 @@ const props = defineProps<{ parameters: MethodParameter[] }>();
     </table>
   </div>
 </template>
+
+<style scoped>
+td.deprecated {
+  text-decoration: line-through;
+}
+</style>
diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts
index 7eb2e896..109cd55d 100644
--- a/scripts/apidoc/signature.ts
+++ b/scripts/apidoc/signature.ts
@@ -249,18 +249,22 @@ function analyzeParameterOptions(
 
     case 'reflection': {
       const properties = parameterType.declaration.children ?? [];
-      return properties.map((property) => ({
-        name: `${name}.${property.name}${isOptional(property) ? '?' : ''}`,
-        type: declarationTypeToText(property),
-        default: extractDefaultFromComment(property.comment),
-        description: mdToHtml(
-          toBlock(
-            property.comment ??
-              (property.type as ReflectionType)?.declaration?.signatures?.[0]
-                .comment
-          )
-        ),
-      }));
+      return properties.map((property) => {
+        const reflection = property.comment
+          ? property
+          : (property.type as ReflectionType)?.declaration?.signatures?.[0];
+        const comment = reflection?.comment;
+        const deprecated = extractDeprecated(reflection);
+        return {
+          name: `${name}.${property.name}${isOptional(property) ? '?' : ''}`,
+          type: declarationTypeToText(property),
+          default: extractDefaultFromComment(comment),
+          description: mdToHtml(
+            toBlock(comment) +
+              (deprecated ? `\n\n**DEPRECATED:** ${deprecated}` : '')
+          ),
+        };
+      });
     }
 
     case 'typeOperator':
diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts
index b408b7ce..0b19c1b4 100644
--- a/scripts/apidoc/typedoc.ts
+++ b/scripts/apidoc/typedoc.ts
@@ -185,23 +185,23 @@ export function extractSourcePath(reflection: Reflection): string {
  * Extracts the text (md) from a jsdoc tag.
  *
  * @param tag The tag to extract the text from.
- * @param signature The signature to extract the text from.
+ * @param reflection The reflection to extract the text from.
  */
 export function extractTagContent(
   tag: `@${string}`,
-  signature?: SignatureReflection,
+  reflection?: Reflection,
   tagProcessor: (tag: CommentTag) => string[] = joinTagContent
 ): string[] {
-  return signature?.comment?.getTags(tag).flatMap(tagProcessor) ?? [];
+  return reflection?.comment?.getTags(tag).flatMap(tagProcessor) ?? [];
 }
 
 /**
  * Extracts the examples from the jsdocs without the surrounding md code block.
  *
- * @param signature The signature to extract the examples from.
+ * @param reflection The reflection to extract the examples from.
  */
-export function extractRawExamples(signature?: SignatureReflection): string[] {
-  return extractTagContent('@example', signature).map((tag) =>
+export function extractRawExamples(reflection?: Reflection): string[] {
+  return extractTagContent('@example', reflection).map((tag) =>
     tag.replace(/^```ts\n/, '').replace(/\n```$/, '')
   );
 }
@@ -209,10 +209,10 @@ 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.
+ * @param reflection The reflection to extract the see also references from.
  */
-export function extractSeeAlsos(signature?: SignatureReflection): string[] {
-  return extractTagContent('@see', signature, (tag) =>
+export function extractSeeAlsos(reflection?: Reflection): string[] {
+  return extractTagContent('@see', reflection, (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)
@@ -243,26 +243,24 @@ export function joinTagParts(parts?: CommentDisplayPart[]): string | undefined {
 }
 
 /**
- * Checks if the given signature is deprecated.
+ * Checks if the given reflection is deprecated.
  *
- * @param signature The signature to check.
+ * @param reflection The reflection to check.
  *
  * @returns The message explaining the deprecation if deprecated, otherwise `undefined`.
  */
-export function extractDeprecated(
-  signature: SignatureReflection
-): string | undefined {
-  const deprecated = extractTagContent('@deprecated', signature).join().trim();
+export function extractDeprecated(reflection?: Reflection): string | undefined {
+  const deprecated = extractTagContent('@deprecated', reflection).join().trim();
   return deprecated.length === 0 ? undefined : deprecated;
 }
 
 /**
  * Extracts the "since" tag from the provided signature.
  *
- * @param signature The signature to check.
+ * @param reflection The signature to check.
  *
- * @returns the contents of the @since tag
+ * @returns The contents of the `@since` tag.
  */
-export function extractSince(signature: SignatureReflection): string {
-  return extractTagContent('@since', signature).join().trim();
+export function extractSince(reflection: Reflection): string {
+  return extractTagContent('@since', reflection).join().trim();
 }
diff --git a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap
index e7add7c6..533d13da 100644
--- a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap
+++ b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap
@@ -44,7 +44,7 @@ exports[`signature > analyzeSignature() > complexArrayParameter 1`] = `
   "returns": "T",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L301",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L330",
   "title": "Complex Array Parameter",
 }
 `;
@@ -82,6 +82,7 @@ exports[`signature > analyzeSignature() > expected and actual methods are equal
   "functionParamMethod",
   "literalUnionParamMethod",
   "methodWithDeprecated",
+  "methodWithDeprecatedOption",
   "methodWithExample",
   "methodWithMultipleSeeMarkers",
   "methodWithMultipleSeeMarkersAndBackticks",
@@ -206,6 +207,59 @@ exports[`signature > analyzeSignature() > methodWithDeprecated 1`] = `
 }
 `;
 
+exports[`signature > analyzeSignature() > methodWithDeprecatedOption 1`] = `
+{
+  "deprecated": undefined,
+  "description": "<p>Test with deprecated option.</p>
+",
+  "examples": "<div class=\\"language-ts\\"><button title=\\"Copy Code\\" class=\\"copy\\"></button><span class=\\"lang\\">ts</span><pre v-pre class=\\"shiki material-theme-palenight\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">methodWithDeprecatedOption</span><span style=\\"color:#A6ACCD\\">(option: </span><span style=\\"color:#89DDFF\\">{</span></span>
+<span class=\\"line\\"><span style=\\"color:#A6ACCD\\">  </span><span style=\\"color:#F07178\\">a</span><span style=\\"color:#89DDFF\\">:</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">,</span></span>
+<span class=\\"line\\"><span style=\\"color:#A6ACCD\\">  </span><span style=\\"color:#82AAFF\\">b</span><span style=\\"color:#89DDFF\\">:</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">()</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#C792EA\\">=&gt;</span><span style=\\"color:#A6ACCD\\"> number</span><span style=\\"color:#89DDFF\\">,</span></span>
+<span class=\\"line\\"><span style=\\"color:#A6ACCD\\">  </span><span style=\\"color:#F07178\\">c</span><span style=\\"color:#89DDFF\\">:</span><span style=\\"color:#A6ACCD\\"> number</span></span>
+<span class=\\"line\\"><span style=\\"color:#89DDFF\\">}</span><span style=\\"color:#A6ACCD\\">): number</span></span>
+<span class=\\"line\\"></span></code></pre>
+</div>",
+  "name": "methodWithDeprecatedOption",
+  "parameters": [
+    {
+      "default": undefined,
+      "description": "<p>The options.</p>
+",
+      "name": "option",
+      "type": "{ ... }",
+    },
+    {
+      "default": undefined,
+      "description": "<p>Some deprecated option.</p>
+<p><strong>DEPRECATED:</strong> do something else.</p>
+",
+      "name": "option.a",
+      "type": "string",
+    },
+    {
+      "default": undefined,
+      "description": "<p>Some other deprecated option.</p>
+<p><strong>DEPRECATED:</strong> do something else.</p>
+",
+      "name": "option.b",
+      "type": "() => number",
+    },
+    {
+      "default": undefined,
+      "description": "<p>Some other option.</p>
+",
+      "name": "option.c",
+      "type": "number",
+    },
+  ],
+  "returns": "number",
+  "seeAlsos": [],
+  "since": "",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L272",
+  "title": "Method With Deprecated Option",
+}
+`;
+
 exports[`signature > analyzeSignature() > methodWithExample 1`] = `
 {
   "deprecated": undefined,
@@ -241,7 +295,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = `
     "test.apidoc.methodWithDeprecated()",
   ],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L270",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L299",
   "title": "Method With Multiple See Markers",
 }
 `;
@@ -262,7 +316,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBacktic
     "test.apidoc.methodWithDeprecated() with parameter <code>bar</code> and <code>baz</code>.",
   ],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L280",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L309",
   "title": "Method With Multiple See Markers And Backticks",
 }
 `;
@@ -280,7 +334,7 @@ exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "1.0.0",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L289",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L318",
   "title": "Method With Since Marker",
 }
 `;
diff --git a/test/scripts/apidoc/signature.example.ts b/test/scripts/apidoc/signature.example.ts
index 2d3010ae..1013365f 100644
--- a/test/scripts/apidoc/signature.example.ts
+++ b/test/scripts/apidoc/signature.example.ts
@@ -262,6 +262,35 @@ export class SignatureTest {
   }
 
   /**
+   * Test with deprecated option.
+   *
+   * @param option The options.
+   * @param option.a Some deprecated option.
+   * @param option.b Some other deprecated option.
+   * @param option.c Some other option.
+   */
+  methodWithDeprecatedOption(option: {
+    /**
+     * Some deprecated option.
+     *
+     * @deprecated do something else.
+     */
+    a: string;
+    /**
+     * Some other deprecated option.
+     *
+     * @deprecated do something else.
+     */
+    b: () => number;
+    /**
+     * Some other option.
+     */
+    c: number;
+  }): number {
+    return option.c;
+  }
+
+  /**
    * Test with multiple see markers.
    *
    * @see test.apidoc.methodWithExample()