diff --git a/docs/.vitepress/components/api-docs/method-parameters.vue b/docs/.vitepress/components/api-docs/method-parameters.vue index ca3aef374fc..fbc28635f20 100644 --- a/docs/.vitepress/components/api-docs/method-parameters.vue +++ b/docs/.vitepress/components/api-docs/method-parameters.vue @@ -19,7 +19,13 @@ const props = defineProps<{ parameters: MethodParameter[] }>(); - {{ parameter.name }} + + {{ parameter.name }} + {{ parameter.type }} {{ parameter.default }} @@ -30,3 +36,9 @@ const props = defineProps<{ parameters: MethodParameter[] }>(); + + diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts index 7eb2e896fd6..109cd55d0ff 100644 --- a/scripts/apidoc/signature.ts +++ b/scripts/apidoc/signature.ts @@ -249,18 +249,22 @@ 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 deprecated = extractDeprecated(reflection); + return { + name: `${name}.${property.name}${isOptional(property) ? '?' : ''}`, + type: declarationTypeToText(property), + default: extractDefaultFromComment(comment), + description: mdToHtml( + toBlock(comment) + + (deprecated ? `\n\n**DEPRECATED:** ${deprecated}` : '') + ), + }; + }); } case 'typeOperator': diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts index b408b7ce0d4..0b19c1b4c24 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`. */ -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..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#L301", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L330", "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,59 @@ 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": "

Some deprecated option.

+

DEPRECATED: do something else.

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

Some other deprecated option.

+

DEPRECATED: do something else.

+", + "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#L272", + "title": "Method With Deprecated Option", +} +`; + exports[`signature > analyzeSignature() > methodWithExample 1`] = ` { "deprecated": undefined, @@ -241,7 +295,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#L299", "title": "Method With Multiple See Markers", } `; @@ -262,7 +316,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#L309", "title": "Method With Multiple See Markers And Backticks", } `; @@ -280,7 +334,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#L318", "title": "Method With Since Marker", } `; diff --git a/test/scripts/apidoc/signature.example.ts b/test/scripts/apidoc/signature.example.ts index 2d3010ae7bb..1013365f4eb 100644 --- a/test/scripts/apidoc/signature.example.ts +++ b/test/scripts/apidoc/signature.example.ts @@ -261,6 +261,35 @@ export class SignatureTest { return 0; } + /** + * Test with deprecated option. + * + * @param option The options. + * @param option.a Some deprecated option. + * @param option.b Some other deprecated option. + * @param option.c Some other option. + */ + 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. *