From 09312ff21309b65bd26d7c7da57ddbc299a81953 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 22 Mar 2023 21:14:58 +0100 Subject: [PATCH 1/6] docs: mark deprecated parameter options --- scripts/apidoc/signature.ts | 27 +++++---- scripts/apidoc/typedoc.ts | 38 ++++++------ .../__snapshots__/signature.spec.ts.snap | 60 +++++++++++++++++-- test/scripts/apidoc/signature.example.ts | 28 +++++++++ 4 files changed, 117 insertions(+), 36 deletions(-) diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts index 7eb2e896fd6..39d75e6214b 100644 --- a/scripts/apidoc/signature.ts +++ b/scripts/apidoc/signature.ts @@ -249,18 +249,21 @@ 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 isDeprecated = !!extractDeprecated(reflection); + return { + name: `${name}.${property.name}${isOptional(property) ? '?' : ''}`, + type: declarationTypeToText(property), + default: extractDefaultFromComment(comment), + description: mdToHtml( + (isDeprecated ? 'DEPRECATED: ' : '') + toBlock(comment) + ), + }; + }); } case 'typeOperator': diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts index b408b7ce0d4..d7957ed7884 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`. + * @returns The message explaining the deprecation message 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 e7add7c692e..08e24736099 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#L329", "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,57 @@ exports[`signature > analyzeSignature() > methodWithDeprecated 1`] = ` } `; +exports[`signature > analyzeSignature() > methodWithDeprecatedOption 1`] = ` +{ + "deprecated": undefined, + "description": "

Test with deprecated option.

+", + "examples": "
ts
faker.methodWithDeprecatedOption(option: {
+  a: string,
+  b: () => number,
+  c: number
+}): number
+
+
", + "name": "methodWithDeprecatedOption", + "parameters": [ + { + "default": undefined, + "description": "

The options.

+", + "name": "option", + "type": "{ ... }", + }, + { + "default": undefined, + "description": "

DEPRECATED: Some deprecated option.

+", + "name": "option.a", + "type": "string", + }, + { + "default": undefined, + "description": "

DEPRECATED: Some other deprecated option.

+", + "name": "option.b", + "type": "() => number", + }, + { + "default": undefined, + "description": "

Some other option.

+", + "name": "option.c", + "type": "number", + }, + ], + "returns": "number", + "seeAlsos": [], + "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L271", + "title": "Method With Deprecated Option", +} +`; + exports[`signature > analyzeSignature() > methodWithExample 1`] = ` { "deprecated": undefined, @@ -241,7 +293,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#L298", "title": "Method With Multiple See Markers", } `; @@ -262,7 +314,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBacktic "test.apidoc.methodWithDeprecated() with parameter bar and baz.", ], "since": "", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L280", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L308", "title": "Method With Multiple See Markers And Backticks", } `; @@ -280,7 +332,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#L317", "title": "Method With Since Marker", } `; diff --git a/test/scripts/apidoc/signature.example.ts b/test/scripts/apidoc/signature.example.ts index 2d3010ae7bb..94ce2ac0733 100644 --- a/test/scripts/apidoc/signature.example.ts +++ b/test/scripts/apidoc/signature.example.ts @@ -261,6 +261,34 @@ export class SignatureTest { return 0; } + /** + * Test with deprecated option. + * + * @param option The options. + * @param option.a Some deprecated option. + * @param option.b Some other options. + */ + 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. * From 1acd8ecc3bba9b351c801bfc309245a42e32dc55 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 22 Mar 2023 21:40:15 +0100 Subject: [PATCH 2/6] chore: revert docs change --- scripts/apidoc/typedoc.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts index d7957ed7884..0b19c1b4c24 100644 --- a/scripts/apidoc/typedoc.ts +++ b/scripts/apidoc/typedoc.ts @@ -247,7 +247,7 @@ export function joinTagParts(parts?: CommentDisplayPart[]): string | undefined { * * @param reflection The reflection to check. * - * @returns The message explaining the deprecation message if deprecated, otherwise `undefined`. + * @returns The message explaining the deprecation if deprecated, otherwise `undefined`. */ export function extractDeprecated(reflection?: Reflection): string | undefined { const deprecated = extractTagContent('@deprecated', reflection).join().trim(); From 1454b5bfe33580a9e8619bcacfbc48e44cfd1da4 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 22 Mar 2023 22:29:33 +0100 Subject: [PATCH 3/6] chore: apply suggestion --- test/scripts/apidoc/signature.example.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/test/scripts/apidoc/signature.example.ts b/test/scripts/apidoc/signature.example.ts index 94ce2ac0733..1013365f4eb 100644 --- a/test/scripts/apidoc/signature.example.ts +++ b/test/scripts/apidoc/signature.example.ts @@ -266,7 +266,8 @@ export class SignatureTest { * * @param option The options. * @param option.a Some deprecated option. - * @param option.b Some other options. + * @param option.b Some other deprecated option. + * @param option.c Some other option. */ methodWithDeprecatedOption(option: { /** From 70f4186982e98fcde9c69cf5935e97b37573999f Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 22 Mar 2023 23:01:29 +0100 Subject: [PATCH 4/6] docs: change deprecated message --- scripts/apidoc/signature.ts | 5 +++-- .../apidoc/__snapshots__/signature.spec.ts.snap | 16 +++++++++------- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts index 39d75e6214b..109cd55d0ff 100644 --- a/scripts/apidoc/signature.ts +++ b/scripts/apidoc/signature.ts @@ -254,13 +254,14 @@ function analyzeParameterOptions( ? property : (property.type as ReflectionType)?.declaration?.signatures?.[0]; const comment = reflection?.comment; - const isDeprecated = !!extractDeprecated(reflection); + const deprecated = extractDeprecated(reflection); return { name: `${name}.${property.name}${isOptional(property) ? '?' : ''}`, type: declarationTypeToText(property), default: extractDefaultFromComment(comment), description: mdToHtml( - (isDeprecated ? 'DEPRECATED: ' : '') + toBlock(comment) + toBlock(comment) + + (deprecated ? `\n\n**DEPRECATED:** ${deprecated}` : '') ), }; }); diff --git a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap index 08e24736099..533d13daec0 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#L329", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L330", "title": "Complex Array Parameter", } `; @@ -230,14 +230,16 @@ exports[`signature > analyzeSignature() > methodWithDeprecatedOption 1`] = ` }, { "default": undefined, - "description": "

DEPRECATED: Some deprecated option.

+ "description": "

Some deprecated option.

+

DEPRECATED: do something else.

", "name": "option.a", "type": "string", }, { "default": undefined, - "description": "

DEPRECATED: Some other deprecated option.

+ "description": "

Some other deprecated option.

+

DEPRECATED: do something else.

", "name": "option.b", "type": "() => number", @@ -253,7 +255,7 @@ exports[`signature > analyzeSignature() > methodWithDeprecatedOption 1`] = ` "returns": "number", "seeAlsos": [], "since": "", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L271", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L272", "title": "Method With Deprecated Option", } `; @@ -293,7 +295,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = ` "test.apidoc.methodWithDeprecated()", ], "since": "", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L298", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L299", "title": "Method With Multiple See Markers", } `; @@ -314,7 +316,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBacktic "test.apidoc.methodWithDeprecated() with parameter bar and baz.", ], "since": "", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L308", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L309", "title": "Method With Multiple See Markers And Backticks", } `; @@ -332,7 +334,7 @@ exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = ` "returns": "number", "seeAlsos": [], "since": "1.0.0", - "sourcePath": "test/scripts/apidoc/signature.example.ts#L317", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L318", "title": "Method With Since Marker", } `; From 3060fa1323255477e62b2ed49e1f3542bf793dc8 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Thu, 23 Mar 2023 10:29:35 +0100 Subject: [PATCH 5/6] docs: strike-through parameter name --- .../components/api-docs/method-parameters.vue | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/.vitepress/components/api-docs/method-parameters.vue b/docs/.vitepress/components/api-docs/method-parameters.vue index ca3aef374fc..6e206bba743 100644 --- a/docs/.vitepress/components/api-docs/method-parameters.vue +++ b/docs/.vitepress/components/api-docs/method-parameters.vue @@ -1,4 +1,5 @@