Merge remote-tracking branch 'origin/next' into refactor/remove-locale-changing

Author: ST-DDT

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[];

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>

netlify.toml

@@ -29,7 +29,7 @@
 
 [[redirects]]
   from = "/chat"
-  to = "https://discord.gg/faker-js"
+  to = "https://discord.gg/wq78qyhdSZ"
   status = 301
   force = true
 

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,
   };
 }

scripts/apidoc/typedoc.ts

@@ -247,10 +247,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;
 }
 
 /**

test/scripts/apidoc/__snapshots__/signature.spec.ts.snap

@@ -15,11 +15,11 @@ import {
   initMarkdownRenderer,
 } from '../../../scripts/apidoc/signature';
 import {
+  extractDeprecated,
   extractRawExamples,
   extractSeeAlsos,
   extractSince,
   extractTagContent,
-  isDeprecated,
 } from '../../../scripts/apidoc/typedoc';
 import { loadProjectModules } from './utils';
 
@@ -79,7 +79,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(

test/scripts/apidoc/examplesAndDeprecations.spec.ts

@@ -249,7 +249,7 @@ export class SignatureTest {
    *
    * @see test.apidoc.methodWithExample()
    *
-   * @deprecated
+   * @deprecated do something else
    */
   methodWithDeprecated(): number {
     return 0;