docs: resolve example tag in DML properties (#14383)

www/packages/docs-ui/src/components/TypeList/Items/index.tsx

@@ -133,7 +133,7 @@ const TypeListItem = ({
     return (
       <DetailsSummary
         subtitle={
-          item.description || item.defaultValue ? (
+          item.description || item.defaultValue || item.example ? (
             <>
               {item.description && (
                 <MarkdownContent
@@ -176,6 +176,11 @@ const TypeListItem = ({
                   Default: <InlineCode>{item.defaultValue}</InlineCode>
                 </p>
               )}
+              {item.example && (
+                <div className="mt-0.5">
+                  Example: <InlineCode>{item.example}</InlineCode>
+                </div>
+              )}
             </>
           ) : undefined
         }

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

www/utils/packages/docs-generator/src/classes/kinds/default.ts

@@ -607,12 +607,14 @@ class DefaultKindGenerator<T extends ts.Node = ts.Node> {
     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<T extends ts.Node = ts.Node> {
         if (tag.tagName.getText() === "featureFlag") {
           featureFlagTag = tag
         }
+
+        if (tag.tagName.getText() === "example") {
+          example = tag
+        }
       })
     })
 
@@ -645,6 +651,7 @@ class DefaultKindGenerator<T extends ts.Node = ts.Node> {
       sinceTag,
       featureFlagTag,
       summary,
+      example,
     }
   }
 

www/utils/packages/docs-generator/src/classes/kinds/dml.ts

@@ -243,7 +243,7 @@ class DmlKindGenerator extends DefaultKindGenerator<ts.CallExpression> {
       )
       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<ts.CallExpression> {
         }`
       }
 
+      if (example) {
+        propertyDescription += `\n\n@example ${
+          this.formatJSDocTag(example) ?? ""
+        }`
+      }
+
       properties[propertyName] = propertyDescription
     })
 

www/utils/packages/typedoc-plugin-custom/src/dml-json-parser.ts

@@ -16,6 +16,7 @@ const FILE_NAME_REGEX = /packages\/modules\/(?<module>[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
     }
   )

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

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: [],

www/utils/packages/types/lib/index.d.ts

@@ -313,6 +313,7 @@ export declare type DmlFile = {
       description?: string
     }
     featureFlag?: string
+    example?: string
   }
 }