From 859292878b55c572e5b841e67aee5e9da660989e Mon Sep 17 00:00:00 2001 From: Matt Mayer Date: Sun, 5 Mar 2023 03:48:49 +0700 Subject: [PATCH] docs: show deprecation message (#1889) --- docs/.vitepress/components/api-docs/method.ts | 2 +- .../.vitepress/components/api-docs/method.vue | 1 + scripts/apidoc/signature.ts | 9 +++-- scripts/apidoc/typedoc.ts | 9 +++-- .../__snapshots__/signature.spec.ts.snap | 37 ++++++++++--------- .../apidoc/examplesAndDeprecations.spec.ts | 4 +- test/scripts/apidoc/signature.example.ts | 2 +- 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 52cb24957bf..562d1ecf8d9 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 8bff111f36a..6753cefd733 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 {

Deprecated

This method is deprecated and will be removed in a future version.

+
diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts index d9e1cc440cb..7403e492638 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 cc5132a9a07..43b2ac88c86 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 23b3867a4ca..8d7f4ca4f2e 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": "

Complex array parameter.

", "examples": "
ts
faker.complexArrayParameter<T>(array: readonly Array<{
@@ -51,7 +51,7 @@ exports[`signature > analyzeSignature() > complexArrayParameter 1`] = `
 
 exports[`signature > analyzeSignature() > defaultBooleanParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with a default parameter.

 ",
   "examples": "
ts
faker.defaultBooleanParamMethod(c: boolean = true): number
@@ -100,7 +100,7 @@ exports[`signature > analyzeSignature() > expected and actual methods are equal
 
 exports[`signature > analyzeSignature() > functionParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with a function parameters.

 ",
   "examples": "
ts
faker.functionParamMethod(fn: (a: string) => number): number
@@ -126,7 +126,7 @@ exports[`signature > analyzeSignature() > functionParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > literalUnionParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with LiteralUnion.

 ",
   "examples": "
ts
faker.literalUnionParamMethod(value: 'a' | 'b' | string, namedValue: AB | string, array: readonly Array<'a' | 'b' | string>, namedArray: readonly Array<AB | string>, mixed: 'a' | 'b' | string | readonly Array<'a' | 'b' | string>, namedMixed: AB | string | readonly Array<AB | string>): string
@@ -187,7 +187,8 @@ exports[`signature > analyzeSignature() > literalUnionParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > methodWithDeprecated 1`] = `
 {
-  "deprecated": true,
+  "deprecated": "
do something else

+",
   "description": "
Test with deprecated and see marker.

 ",
   "examples": "
ts
faker.methodWithDeprecated(): number
@@ -207,7 +208,7 @@ exports[`signature > analyzeSignature() > methodWithDeprecated 1`] = `
 
 exports[`signature > analyzeSignature() > methodWithExample 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with example marker.

 ",
   "examples": "
ts
faker.methodWithExample(): number
@@ -226,7 +227,7 @@ exports[`signature > analyzeSignature() > methodWithExample 1`] = `
 
 exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with multiple see markers.

 ",
   "examples": "
ts
faker.methodWithMultipleSeeMarkers(): number
@@ -247,7 +248,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = `
 
 exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBackticks 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with multiple see markers and backticks.

 ",
   "examples": "
ts
faker.methodWithMultipleSeeMarkersAndBackticks(): number
@@ -268,7 +269,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBacktic
 
 exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with since marker.

 ",
   "examples": "
ts
faker.methodWithSinceMarker(): number
@@ -286,7 +287,7 @@ exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = `
 
 exports[`signature > analyzeSignature() > multiParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with multiple parameters.

 ",
   "examples": "
ts
faker.multiParamMethod(a: number, b?: string, c: boolean = true): number
@@ -326,7 +327,7 @@ exports[`signature > analyzeSignature() > multiParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > noParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with no parameters.

 ",
   "examples": "
ts
faker.noParamMethod(): number
@@ -344,7 +345,7 @@ exports[`signature > analyzeSignature() > noParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > optionalStringParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with an optional parameter.

 ",
   "examples": "
ts
faker.optionalStringParamMethod(b?: string): number
@@ -370,7 +371,7 @@ exports[`signature > analyzeSignature() > optionalStringParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > optionsInlineParamMethodWithDefaults 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with a function parameters (inline types) with defaults.

 ",
   "examples": "
ts
faker.optionsInlineParamMethodWithDefaults(a: {
@@ -439,7 +440,7 @@ It also has a more complex description.

 
 exports[`signature > analyzeSignature() > optionsInterfaceParamMethodWithDefaults 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with a function parameters with defaults.

 ",
   "examples": "
ts
faker.optionsInterfaceParamMethodWithDefaults(a: ParameterOptionsInterfaceA = { value: 1 }, b: ParameterOptionsInterfaceB = { value: 1 }, c: ParameterOptionsInterfaceC): number
@@ -479,7 +480,7 @@ exports[`signature > analyzeSignature() > optionsInterfaceParamMethodWithDefault
 
 exports[`signature > analyzeSignature() > optionsParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with a function parameters.

 ",
   "examples": "
ts
faker.optionsParamMethod(options: {
@@ -538,7 +539,7 @@ exports[`signature > analyzeSignature() > optionsParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > optionsTypeParamMethodWithDefaults 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with a function parameters with defaults.

 ",
   "examples": "
ts
faker.optionsTypeParamMethodWithDefaults(a: ParameterOptionsTypeA = { value: 1 }, b: ParameterOptionsTypeB = { value: 1 }, c: ParameterOptionsTypeC): number
@@ -578,7 +579,7 @@ exports[`signature > analyzeSignature() > optionsTypeParamMethodWithDefaults 1`]
 
 exports[`signature > analyzeSignature() > requiredNumberParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with a required parameter.

 ",
   "examples": "
ts
faker.requiredNumberParamMethod(a: number): number
@@ -604,7 +605,7 @@ exports[`signature > analyzeSignature() > requiredNumberParamMethod 1`] = `
 
 exports[`signature > analyzeSignature() > stringUnionParamMethod 1`] = `
 {
-  "deprecated": false,
+  "deprecated": undefined,
   "description": "
Test with string union.

 ",
   "examples": "
ts
faker.stringUnionParamMethod(value: 'a' | 'b'): string
diff --git a/test/scripts/apidoc/examplesAndDeprecations.spec.ts b/test/scripts/apidoc/examplesAndDeprecations.spec.ts
index 8d6124e0321..d8fc7361918 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 26c35923c6e..13372ffb159 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;