docs: show deprecation message (#1889)

7 files changed, 36 insertions, 28 deletions

diff --git a/docs/.vitepress/components/api-docs/method.ts b/docs/.vitepress/components/api-docs/method.ts
index 52cb2495..562d1ecf 100644
--- a/docs/.vitepress/components/api-docs/method.ts
+++ b/docs/.vitepress/components/api-docs/method.ts
@@ -5,7 +5,7 @@ export interface Method {
   readonly parameters: MethodParameter[];
   readonly returns: string;
   readonly examples: string; // HTML
-  readonly deprecated: boolean;
+  readonly deprecated?: string; // HTML
   readonly since: string;
   readonly sourcePath: string; // URL-Suffix
   readonly seeAlsos: string[];
diff --git a/docs/.vitepress/components/api-docs/method.vue b/docs/.vitepress/components/api-docs/method.vue
index 8bff111f..6753cefd 100644
--- a/docs/.vitepress/components/api-docs/method.vue
+++ b/docs/.vitepress/components/api-docs/method.vue
@@ -17,6 +17,7 @@ function seeAlsoToUrl(see: string): string {
     <div v-if="props.method.deprecated" class="warning custom-block">
       <p class="custom-block-title">Deprecated</p>
       <p>This method is deprecated and will be removed in a future version.</p>
+      <span v-html="props.method.deprecated" />
     </div>
 
     <div v-html="props.method.description"></div>
diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts
index d9e1cc44..7403e492 100644
--- a/scripts/apidoc/signature.ts
+++ b/scripts/apidoc/signature.ts
@@ -20,11 +20,11 @@ import vitepressConfig from '../../docs/.vitepress/config';
 import { faker } from '../../src';
 import { formatTypescript } from './format';
 import {
+  extractDeprecated,
   extractRawExamples,
   extractSeeAlsos,
   extractSince,
   extractSourcePath,
-  isDeprecated,
   joinTagParts,
 } from './typedoc';
 import { pathOutputDir } from './utils';
@@ -178,7 +178,10 @@ export function analyzeSignature(
   const seeAlsos = extractSeeAlsos(signature).map((seeAlso) =>
     mdToHtml(seeAlso, true)
   );
-
+  const deprecatedMessage = extractDeprecated(signature);
+  const deprecated = deprecatedMessage
+    ? mdToHtml(deprecatedMessage)
+    : undefined;
   return {
     name: methodName,
     title: prettifyMethodName(methodName),
@@ -188,7 +191,7 @@ export function analyzeSignature(
     sourcePath: extractSourcePath(signature),
     returns: typeToText(signature.type),
     examples: mdToHtml(`${code}ts\n${examples}${code}`),
-    deprecated: isDeprecated(signature),
+    deprecated,
     seeAlsos,
   };
 }
diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts
index cc5132a9..43b2ac88 100644
--- a/scripts/apidoc/typedoc.ts
+++ b/scripts/apidoc/typedoc.ts
@@ -245,10 +245,13 @@ export function joinTagParts(parts?: CommentDisplayPart[]): string | undefined {
  *
  * @param signature The signature to check.
  *
- * @returns `true` if it is deprecated, otherwise `false`.
+ * @returns The message explaining the deprecation if deprecated, otherwise `undefined`.
  */
-export function isDeprecated(signature: SignatureReflection): boolean {
-  return extractTagContent('@deprecated', signature).length > 0;
+export function extractDeprecated(
+  signature: SignatureReflection
+): string | undefined {
+  const deprecated = extractTagContent('@deprecated', signature).join().trim();
+  return deprecated.length === 0 ? undefined : deprecated;
 }
 
 /**
diff --git a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap
index 23b3867a..8d7f4ca4 100644
--- a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap
+++ b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap
@@ -2,7 +2,7 @@
 
 exports[`signature > analyzeSignature() > complexArrayParameter 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Complex array parameter.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">complexArrayParameter</span><span style=\\"color:#89DDFF\\">&lt;</span><span style=\\"color:#FFCB6B\\">T</span><span style=\\"color:#89DDFF\\">&gt;</span><span style=\\"color:#A6ACCD\\">(array: readonly </span><span style=\\"color:#82AAFF\\">Array</span><span style=\\"color:#89DDFF\\">&lt;{</span></span>
@@ -51,7 +51,7 @@ exports[`signature > analyzeSignature() > complexArrayParameter 1`] = `
 
 exports[`signature > analyzeSignature() > defaultBooleanParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with a default parameter.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">defaultBooleanParamMethod</span><span style=\\"color:#A6ACCD\\">(c: boolean </span><span style=\\"color:#89DDFF\\">=</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#FF9CAC\\">true</span><span style=\\"color:#A6ACCD\\">): number</span></span>
@@ -100,7 +100,7 @@ exports[`signature > analyzeSignature() > expected and actual methods are equal
 
 exports[`signature > analyzeSignature() > functionParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with a function parameters.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">functionParamMethod</span><span style=\\"color:#A6ACCD\\">(fn: </span><span style=\\"color:#89DDFF\\">(</span><span style=\\"color:#A6ACCD;font-style:italic\\">a</span><span style=\\"color:#89DDFF\\">:</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#FFCB6B\\">string</span><span style=\\"color:#89DDFF\\">)</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#C792EA\\">=&gt;</span><span style=\\"color:#A6ACCD\\"> number): number</span></span>
@@ -126,7 +126,7 @@ exports[`signature > analyzeSignature() > functionParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > literalUnionParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with LiteralUnion.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">literalUnionParamMethod</span><span style=\\"color:#A6ACCD\\">(value: </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">a</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">b</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">,</span><span style=\\"color:#A6ACCD\\"> namedValue: AB </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">,</span><span style=\\"color:#A6ACCD\\"> array: readonly Array</span><span style=\\"color:#89DDFF\\">&lt;</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">a</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">b</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">&gt;,</span><span style=\\"color:#A6ACCD\\"> namedArray: readonly Array</span><span style=\\"color:#89DDFF\\">&lt;</span><span style=\\"color:#A6ACCD\\">AB </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">&gt;,</span><span style=\\"color:#A6ACCD\\"> mixed: </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">a</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">b</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> readonly Array</span><span style=\\"color:#89DDFF\\">&lt;</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">a</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">b</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">&gt;,</span><span style=\\"color:#A6ACCD\\"> namedMixed: AB </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> readonly Array</span><span style=\\"color:#89DDFF\\">&lt;</span><span style=\\"color:#A6ACCD\\">AB </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">&gt;</span><span style=\\"color:#A6ACCD\\">): string</span></span>
@@ -187,7 +187,8 @@ exports[`signature > analyzeSignature() > literalUnionParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > methodWithDeprecated 1`] = `
 {
-  "deprecated": true,
+  "deprecated": "<p>do something else</p>
+",
   "description": "<p>Test with deprecated and see marker.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">methodWithDeprecated</span><span style=\\"color:#A6ACCD\\">(): number</span></span>
@@ -207,7 +208,7 @@ exports[`signature > analyzeSignature() > methodWithDeprecated 1`] = `
 
 exports[`signature > analyzeSignature() > methodWithExample 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with example marker.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">methodWithExample</span><span style=\\"color:#A6ACCD\\">(): number</span></span>
@@ -226,7 +227,7 @@ exports[`signature > analyzeSignature() > methodWithExample 1`] = `
 
 exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with multiple see markers.</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\\" tabindex=\\"0\\"><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>
@@ -247,7 +248,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = `
 
 exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBackticks 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "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-theme-palenight\\" tabindex=\\"0\\"><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>
@@ -268,7 +269,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBacktic
 
 exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with since marker.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">methodWithSinceMarker</span><span style=\\"color:#A6ACCD\\">(): number</span></span>
@@ -286,7 +287,7 @@ exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = `
 
 exports[`signature > analyzeSignature() > multiParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with multiple parameters.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">multiParamMethod</span><span style=\\"color:#A6ACCD\\">(a: number</span><span style=\\"color:#89DDFF\\">,</span><span style=\\"color:#A6ACCD\\"> b</span><span style=\\"color:#89DDFF\\">?:</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">,</span><span style=\\"color:#A6ACCD\\"> c: boolean </span><span style=\\"color:#89DDFF\\">=</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#FF9CAC\\">true</span><span style=\\"color:#A6ACCD\\">): number</span></span>
@@ -326,7 +327,7 @@ exports[`signature > analyzeSignature() > multiParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > noParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with no parameters.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">noParamMethod</span><span style=\\"color:#A6ACCD\\">(): number</span></span>
@@ -344,7 +345,7 @@ exports[`signature > analyzeSignature() > noParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > optionalStringParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with an optional parameter.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">optionalStringParamMethod</span><span style=\\"color:#A6ACCD\\">(b</span><span style=\\"color:#89DDFF\\">?:</span><span style=\\"color:#A6ACCD\\"> string): number</span></span>
@@ -370,7 +371,7 @@ exports[`signature > analyzeSignature() > optionalStringParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > optionsInlineParamMethodWithDefaults 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with a function parameters (inline types) with defaults.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">optionsInlineParamMethodWithDefaults</span><span style=\\"color:#A6ACCD\\">(a: </span><span style=\\"color:#89DDFF\\">{</span></span>
@@ -439,7 +440,7 @@ It also has a more complex description.</p>
 
 exports[`signature > analyzeSignature() > optionsInterfaceParamMethodWithDefaults 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with a function parameters with defaults.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">optionsInterfaceParamMethodWithDefaults</span><span style=\\"color:#A6ACCD\\">(a: ParameterOptionsInterfaceA </span><span style=\\"color:#89DDFF\\">=</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">{</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#F07178\\">value</span><span style=\\"color:#89DDFF\\">:</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#F78C6C\\">1</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">},</span><span style=\\"color:#A6ACCD\\"> b: ParameterOptionsInterfaceB </span><span style=\\"color:#89DDFF\\">=</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">{</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#F07178\\">value</span><span style=\\"color:#89DDFF\\">:</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#F78C6C\\">1</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">},</span><span style=\\"color:#A6ACCD\\"> c: ParameterOptionsInterfaceC): number</span></span>
@@ -479,7 +480,7 @@ exports[`signature > analyzeSignature() > optionsInterfaceParamMethodWithDefault
 
 exports[`signature > analyzeSignature() > optionsParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with a function parameters.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">optionsParamMethod</span><span style=\\"color:#A6ACCD\\">(options: </span><span style=\\"color:#89DDFF\\">{</span></span>
@@ -538,7 +539,7 @@ exports[`signature > analyzeSignature() > optionsParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > optionsTypeParamMethodWithDefaults 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with a function parameters with defaults.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">optionsTypeParamMethodWithDefaults</span><span style=\\"color:#A6ACCD\\">(a: ParameterOptionsTypeA </span><span style=\\"color:#89DDFF\\">=</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">{</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#F07178\\">value</span><span style=\\"color:#89DDFF\\">:</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#F78C6C\\">1</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">},</span><span style=\\"color:#A6ACCD\\"> b: ParameterOptionsTypeB </span><span style=\\"color:#89DDFF\\">=</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">{</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#F07178\\">value</span><span style=\\"color:#89DDFF\\">:</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#F78C6C\\">1</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">},</span><span style=\\"color:#A6ACCD\\"> c: ParameterOptionsTypeC): number</span></span>
@@ -578,7 +579,7 @@ exports[`signature > analyzeSignature() > optionsTypeParamMethodWithDefaults 1`]
 
 exports[`signature > analyzeSignature() > requiredNumberParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with a required parameter.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">requiredNumberParamMethod</span><span style=\\"color:#A6ACCD\\">(a: number): number</span></span>
@@ -604,7 +605,7 @@ exports[`signature > analyzeSignature() > requiredNumberParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > stringUnionParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "<p>Test with string union.</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\\" tabindex=\\"0\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">stringUnionParamMethod</span><span style=\\"color:#A6ACCD\\">(value: </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">a</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">b</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\">): string</span></span>
diff --git a/test/scripts/apidoc/examplesAndDeprecations.spec.ts b/test/scripts/apidoc/examplesAndDeprecations.spec.ts
index 8d6124e0..d8fc7361 100644
--- a/test/scripts/apidoc/examplesAndDeprecations.spec.ts
+++ b/test/scripts/apidoc/examplesAndDeprecations.spec.ts
@@ -15,11 +15,11 @@ import {
   initMarkdownRenderer,
 } from '../../../scripts/apidoc/signature';
 import {
+  extractDeprecated,
   extractRawExamples,
   extractSeeAlsos,
   extractSince,
   extractTagContent,
-  isDeprecated,
 } from '../../../scripts/apidoc/typedoc';
 import { faker } from '../../../src';
 import { loadProjectModules } from './utils';
@@ -89,7 +89,7 @@ describe('examples and deprecations', () => {
         await import(path);
 
         // Verify logging
-        const deprecatedFlag = isDeprecated(signature);
+        const deprecatedFlag = extractDeprecated(signature) !== undefined;
         if (deprecatedFlag) {
           expect(consoleSpies[1]).toHaveBeenCalled();
           expect(
diff --git a/test/scripts/apidoc/signature.example.ts b/test/scripts/apidoc/signature.example.ts
index 26c35923..13372ffb 100644
--- a/test/scripts/apidoc/signature.example.ts
+++ b/test/scripts/apidoc/signature.example.ts
@@ -249,7 +249,7 @@ export class SignatureTest {
    *
    * @see test.apidoc.methodWithExample()
    *
-   * @deprecated
+   * @deprecated do something else
    */
   methodWithDeprecated(): number {
     return 0;