From 662ec7430b493744fea29acdef5ec9b547c91bac Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 22 Dec 2025 17:52:24 +0200 Subject: [PATCH] docs: resolve example tag in DML properties (#14383) --- .../src/components/TypeList/Items/index.tsx | 7 ++++++- .../docs-ui/src/components/TypeList/index.tsx | 1 + .../docs-generator/src/classes/kinds/default.ts | 7 +++++++ .../docs-generator/src/classes/kinds/dml.ts | 8 +++++++- .../typedoc-plugin-custom/src/dml-json-parser.ts | 14 ++++++++++++++ .../typedoc-plugin-markdown-medusa/src/types.ts | 1 + .../src/utils/reflection-formatter.ts | 3 +++ www/utils/packages/types/lib/index.d.ts | 1 + 8 files changed, 40 insertions(+), 2 deletions(-) diff --git a/www/packages/docs-ui/src/components/TypeList/Items/index.tsx b/www/packages/docs-ui/src/components/TypeList/Items/index.tsx index 496f16f4b2..ad5958d790 100644 --- a/www/packages/docs-ui/src/components/TypeList/Items/index.tsx +++ b/www/packages/docs-ui/src/components/TypeList/Items/index.tsx @@ -133,7 +133,7 @@ const TypeListItem = ({ return ( {item.description && ( {item.defaultValue}

)} + {item.example && ( +
+ Example: {item.example} +
+ )} ) : undefined } diff --git a/www/packages/docs-ui/src/components/TypeList/index.tsx b/www/packages/docs-ui/src/components/TypeList/index.tsx index 1963150707..5eb41f4fbf 100644 --- a/www/packages/docs-ui/src/components/TypeList/index.tsx +++ b/www/packages/docs-ui/src/components/TypeList/index.tsx @@ -13,6 +13,7 @@ export type Type = { type: string optional?: boolean defaultValue?: string + example?: string description?: string featureFlag?: string expandable: boolean diff --git a/www/utils/packages/docs-generator/src/classes/kinds/default.ts b/www/utils/packages/docs-generator/src/classes/kinds/default.ts index d4e03f1633..3ba0779719 100644 --- a/www/utils/packages/docs-generator/src/classes/kinds/default.ts +++ b/www/utils/packages/docs-generator/src/classes/kinds/default.ts @@ -607,12 +607,14 @@ class DefaultKindGenerator { sinceTag: ts.JSDocTag | undefined featureFlagTag: ts.JSDocTag | undefined summary: string | undefined + example: ts.JSDocTag | undefined } { const nodeComments = ts.getJSDocCommentsAndTags(node) let deprecatedTag: ts.JSDocTag | undefined let sinceTag: ts.JSDocTag | undefined let featureFlagTag: ts.JSDocTag | undefined let summary: string | undefined + let example: ts.JSDocTag | undefined nodeComments.forEach((comment) => { if (!("tags" in comment)) { @@ -637,6 +639,10 @@ class DefaultKindGenerator { if (tag.tagName.getText() === "featureFlag") { featureFlagTag = tag } + + if (tag.tagName.getText() === "example") { + example = tag + } }) }) @@ -645,6 +651,7 @@ class DefaultKindGenerator { sinceTag, featureFlagTag, summary, + example, } } diff --git a/www/utils/packages/docs-generator/src/classes/kinds/dml.ts b/www/utils/packages/docs-generator/src/classes/kinds/dml.ts index f867c07d9a..d6bef069dc 100644 --- a/www/utils/packages/docs-generator/src/classes/kinds/dml.ts +++ b/www/utils/packages/docs-generator/src/classes/kinds/dml.ts @@ -243,7 +243,7 @@ class DmlKindGenerator extends DefaultKindGenerator { ) const isBoolean = propertyTypeStr.includes("BooleanProperty") const relationName = isRelation ? camelToWords(propertyName) : undefined - const { summary, sinceTag, deprecatedTag, featureFlagTag } = + const { summary, sinceTag, deprecatedTag, featureFlagTag, example } = this.getInformationFromTags(propertyNode) let propertyDescription = @@ -286,6 +286,12 @@ class DmlKindGenerator extends DefaultKindGenerator { }` } + if (example) { + propertyDescription += `\n\n@example ${ + this.formatJSDocTag(example) ?? "" + }` + } + properties[propertyName] = propertyDescription }) diff --git a/www/utils/packages/typedoc-plugin-custom/src/dml-json-parser.ts b/www/utils/packages/typedoc-plugin-custom/src/dml-json-parser.ts index 8225344ab4..cb0af81418 100644 --- a/www/utils/packages/typedoc-plugin-custom/src/dml-json-parser.ts +++ b/www/utils/packages/typedoc-plugin-custom/src/dml-json-parser.ts @@ -16,6 +16,7 @@ const FILE_NAME_REGEX = /packages\/modules\/(?[a-z-]+)/ const SINCE_REGEX = /@since\s+([\d.]+)/ const DEPRECATED_REGEX = /@deprecated\s+(.+)/ const FEATURE_FLAG_REGEX = /@featureFlag\s+(\S+)/ +const EXAMPLE_REGEX = /@example\s+([\s\S]+)/ export function load(app: Application) { app.converter.on( @@ -132,6 +133,7 @@ function getDescriptionsFromJson( const sinceMatch = description.match(SINCE_REGEX) const featureFlagMatch = description.match(FEATURE_FLAG_REGEX) const deprecatedMatch = description.match(DEPRECATED_REGEX) + const exampleMatch = description.match(EXAMPLE_REGEX) comment.summary.push({ kind: "text", @@ -140,6 +142,7 @@ function getDescriptionsFromJson( .replace(SINCE_REGEX, "") .replace(FEATURE_FLAG_REGEX, "") .replace(DEPRECATED_REGEX, "") + .replace(EXAMPLE_REGEX, "") .trim(), }) @@ -180,6 +183,17 @@ function getDescriptionsFromJson( ) } + if (exampleMatch) { + comment.blockTags.push( + new CommentTag("@example", [ + { + kind: "text", + text: exampleMatch[1], + }, + ]) + ) + } + propertyReflection.comment = comment } ) diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/types.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/types.ts index 888ab349f7..cacfd96cea 100644 --- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/types.ts +++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/types.ts @@ -30,6 +30,7 @@ export type Parameter = { type: string optional?: boolean defaultValue?: string + example?: string description?: string featureFlag?: string expandable: boolean diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts index edfaeb1399..7fbc099be8 100644 --- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts +++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts @@ -133,6 +133,7 @@ export function reflectionComponentFormatter({ reflection.flags.isOptional || reflection.kind === ReflectionKind.EnumMember const comments = getComments(reflection) + const example = comments?.blockTags.find((tag) => tag.tag === "@example") const deprecatedTag = comments?.blockTags.find( (tag) => tag.tag === "@deprecated" ) @@ -159,6 +160,8 @@ export function reflectionComponentFormatter({ : "", optional, defaultValue, + example: + example?.content?.map((c) => stripCode(c.text)).join("") || undefined, expandable: reflection.comment?.hasModifier(`@expandable`) || false, featureFlag: Handlebars.helpers.featureFlag(reflection.comment), children: [], diff --git a/www/utils/packages/types/lib/index.d.ts b/www/utils/packages/types/lib/index.d.ts index 3d766231aa..0536fbb394 100644 --- a/www/utils/packages/types/lib/index.d.ts +++ b/www/utils/packages/types/lib/index.d.ts @@ -313,6 +313,7 @@ export declare type DmlFile = { description?: string } featureFlag?: string + example?: string } }