docs: show deprecation message (#1889)

faker-js · Mar 4, 2023 · 8592928 · 8592928
1 parent 8a97cac
commit 8592928
Show file tree

Hide file tree

Showing 7 changed files with 36 additions and 28 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
diff --git 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
@@ -249,7 +249,7 @@ export class SignatureTest {
    *
    * @see test.apidoc.methodWithExample()
    *
-   * @deprecated
+   * @deprecated do something else
    */
   methodWithDeprecated(): number {
     return 0;