docs: fixes to workflow reference tooling (medusajs#10931)

Stars1233 · Jan 13, 2025 · 2a9ca1d · 2a9ca1d
1 parent 1ba2fad
commit 2a9ca1d
Show file tree

Hide file tree

Showing 9 changed files with 75 additions and 45 deletions.
diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts
@@ -9,6 +9,7 @@ const EXCLUDED_TAGS = [
   "@typeParamDefinition",
   "@version",
   "@tags",
+  "@summary",
 ]
 
 export default function () {

diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-examples.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-examples.ts
@@ -1,9 +1,7 @@
 import Handlebars from "handlebars"
 import { DeclarationReflection, SignatureReflection } from "typedoc"
 import { getReflectionTypeFakeValueStr, getStepInputType } from "utils"
-import pkg from "js-beautify"
-
-const { js_beautify } = pkg
+import beautifyCode from "../../utils/beautify-code.js"
 
 export default function () {
   Handlebars.registerHelper(
@@ -39,22 +37,15 @@ function generateStepExample(stepReflection: DeclarationReflection): string {
   // generate example
   return `
 \`\`\`ts title="src/workflows/my-workflow.ts"
-${js_beautify(
-  `import { createWorkflow } from "@medusajs/framework/workflows-sdk"
+${beautifyCode(`import { createWorkflow } from "@medusajs/framework/workflows-sdk"
 import { ${stepReflection.name} } from "@medusajs/medusa/core-flows"
 
 const myWorkflow = createWorkflow(
   "my-workflow",
   () => {
     const data = ${stepReflection.name}(${inputStr})
   }
-)`,
-  {
-    indent_size: 2,
-    brace_style: "preserve-inline",
-    wrap_line_length: 80,
-  }
-)}
+)`)}
 \`\`\`
   `
 }
diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-examples.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-examples.ts
@@ -1,9 +1,7 @@
 import Handlebars from "handlebars"
-import pkg from "js-beautify"
 import { DeclarationReflection, SignatureReflection } from "typedoc"
 import { getReflectionTypeFakeValueStr, getWorkflowInputType } from "utils"
-
-const { js_beautify } = pkg
+import beautifyCode from "../../utils/beautify-code.js"
 
 export default function () {
   Handlebars.registerHelper(
@@ -54,18 +52,12 @@ function getExecutionCodeTabs({
   workflowName: string
 }): string {
   exampleCode = exampleCode.replace("```ts\n", "").replace("\n```", "")
-  const beautifyOptions: pkg.JSBeautifyOptions = {
-    indent_size: 2,
-    brace_style: "preserve-inline",
-    wrap_line_length: 80,
-  }
 
   return `<CodeTabs group="workflow-exection">
     <CodeTab label="Another Workflow" value="another-workflow">
     
 \`\`\`ts title="src/workflows/my-workflow.ts"
-${js_beautify(
-  `import { createWorkflow } from "@medusajs/framework/workflows-sdk"
+${beautifyCode(`import { createWorkflow } from "@medusajs/framework/workflows-sdk"
 import { ${workflowName} } from "@medusajs/medusa/core-flows"
 
 const myWorkflow = createWorkflow(
@@ -74,19 +66,17 @@ const myWorkflow = createWorkflow(
     ${exampleCode
       .replace(`{ result }`, "result")
       .replace(`await `, "")
-      .replace(`(container)\n\t.run(`, ".runAsStep(")}
+      .replace(`(container)`, "")
+      .replace(".run(", ".runAsStep(")}
   }
-)`,
-  beautifyOptions
-)}
+)`)}
 \`\`\`
 
     </CodeTab>
     <CodeTab label="API Route" value="api-route">
     
 \`\`\`ts title="src/api/workflow/route.ts"
-${js_beautify(
-  `import type {
+${beautifyCode(`import type {
   MedusaRequest,
   MedusaResponse,
 } from "@medusajs/framework/http"
@@ -100,17 +90,14 @@ export async function POST(
 
   res.send(result)
 }
-`,
-  beautifyOptions
-)}
+`)}
 \`\`\`
 
     </CodeTab>
     <CodeTab label="Subscriber" value="subscriber">
     
 \`\`\`ts title="src/subscribers/order-placed.ts"
-${js_beautify(
-  `import {
+${beautifyCode(`import {
   type SubscriberConfig,
   type SubscriberArgs,
 } from "@medusajs/framework"
@@ -127,17 +114,14 @@ export default async function handleOrderPlaced({
 
 export const config: SubscriberConfig = {
   event: "order.placed",
-}`,
-  beautifyOptions
-)}
+}`)}
 \`\`\`
 
     </CodeTab>
     <CodeTab label="Scheduled Job" value="scheduled-job">
     
 \`\`\`ts title="src/jobs/message-daily.ts"
-${js_beautify(
-  `import { MedusaContainer } from "@medusajs/framework/types"
+${beautifyCode(`import { MedusaContainer } from "@medusajs/framework/types"
 import { ${workflowName} } from "@medusajs/medusa/core-flows"
 
 export default async function myCustomJob(
@@ -151,9 +135,7 @@ export default async function myCustomJob(
 export const config = {
   name: "run-once-a-day",
   schedule: "0 0 * * *",
-}`,
-  beautifyOptions
-)}
+}`)}
 \`\`\`
 
     </CodeTab>

diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts
@@ -2,6 +2,7 @@ import { MarkdownTheme } from "../../theme.js"
 import Handlebars from "handlebars"
 import { SignatureReflection } from "typedoc"
 import { cleanUpHookInput, getProjectChild } from "utils"
+import beautifyCode from "../../utils/beautify-code.js"
 
 export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
@@ -19,7 +20,7 @@ export default function (theme: MarkdownTheme) {
         return ""
       }
 
-      let str = `${Handlebars.helpers.titleLevel()} Hooks`
+      let str = `${Handlebars.helpers.titleLevel()} Hooks\n\nHooks allow you to inject custom functionalities into the workflow. You'll receive data from the workflow, as well as additional data sent through an HTTP request.\n\nLearn more about [Hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks) and [Additional Data](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data).\n\n`
 
       Handlebars.helpers.incrementCurrentTitleLevel()
 
@@ -39,14 +40,20 @@ export default function (theme: MarkdownTheme) {
 
         str += `\n\n${hooksTitleLevel} ${hook.name}\n\n`
 
+        if (hookReflection.comment?.summary) {
+          str += `${Handlebars.helpers.comment(
+            hookReflection.comment.summary
+          )}\n\n`
+        }
+
         const hookExample = hookReflection.comment?.getTag(`@example`)
 
         if (hookExample) {
           Handlebars.helpers.incrementCurrentTitleLevel()
           const innerTitleLevel = Handlebars.helpers.titleLevel()
 
-          str += `${innerTitleLevel} Example\n\n\`\`\`ts\n${Handlebars.helpers.comment(
-            hookExample.content
+          str += `${innerTitleLevel} Example\n\n\`\`\`ts\n${beautifyCode(
+            Handlebars.helpers.comment(hookExample.content)
           )}\n\`\`\`\n\n${innerTitleLevel} Input\n\n`
 
           Handlebars.helpers.decrementCurrentTitleLevel()

diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-input.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-input.ts
@@ -25,6 +25,7 @@ export default function (theme: MarkdownTheme) {
         project: this.project || options.data.theme.project,
         maxLevel,
         wrapObject: true,
+        isReturn: false,
       })
 
       if (!input.length) {

diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-output.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-output.ts
@@ -25,6 +25,7 @@ export default function (theme: MarkdownTheme) {
         project: this.project || options.data.theme.project,
         maxLevel,
         wrapObject: true,
+        isReturn: false,
       })
 
       if (!output.length) {

diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/beautify-code.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/beautify-code.ts
@@ -0,0 +1,13 @@
+import pkg from "js-beautify"
+
+const { js_beautify } = pkg
+
+export default function beautifyCode(code: string): string {
+  const beautifyOptions: pkg.JSBeautifyOptions = {
+    indent_size: 2,
+    brace_style: "preserve-inline",
+    wrap_line_length: 80,
+  }
+
+  return js_beautify(code, beautifyOptions)
+}
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
@@ -19,6 +19,7 @@ import {
 } from "utils"
 import { MarkdownTheme } from "../theme.js"
 import { getDmlProperties, isDmlEntity } from "utils"
+import { loadComment } from "./reflection-type-parameters.js"
 
 const ALLOWED_KINDS: ReflectionKind[] = [
   ReflectionKind.EnumMember,
@@ -338,6 +339,18 @@ export function getComments(
       return parameter.type?.declaration?.signatures[0]?.comment
     }
   }
+  if (!parameter.comment && parameter.type?.type === "reference") {
+    // try to load comment
+    const commentContent = loadComment(parameter.type.name, parameter.project)
+    if (commentContent) {
+      return new Comment([
+        {
+          kind: "text",
+          text: commentContent,
+        },
+      ])
+    }
+  }
   return parameter.comment
 }
 

diff --git a/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts b/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts
@@ -207,6 +207,7 @@ class WorkflowsPlugin {
           workflow,
           workflowVarName: parentReflection.name,
           workflowReflection,
+          workflowComments: parentReflection.comment?.blockTags,
         })
 
         if (!steps.length) {
@@ -246,12 +247,14 @@ class WorkflowsPlugin {
     workflow,
     workflowVarName,
     workflowReflection,
+    workflowComments = [],
   }: {
     initializer: ts.CallExpression
     context: Context
     workflow?: WorkflowDefinition
     workflowVarName: string
     workflowReflection: SignatureReflection
+    workflowComments?: CommentTag[]
   }): ParsedStep[] {
     const steps: ParsedStep[] = []
     const initializerName = this.helper.normalizeName(
@@ -292,6 +295,7 @@ class WorkflowsPlugin {
           context,
           inputSymbol: initializer.arguments[1].symbol as ts.Symbol,
           workflowName: workflowVarName,
+          workflowComments,
         })
       } else {
         const initializerReflection = findReflectionInNamespaces(
@@ -478,11 +482,13 @@ class WorkflowsPlugin {
     context,
     inputSymbol,
     workflowName,
+    workflowComments,
   }: {
     stepId: string
     context: Context
     inputSymbol: ts.Symbol
     workflowName: string
+    workflowComments?: CommentTag[]
   }): DeclarationReflection {
     const declarationReflection = context.createDeclarationReflection(
       ReflectionKind.Function,
@@ -492,7 +498,12 @@ class WorkflowsPlugin {
     )
 
     declarationReflection.comment = new Comment()
-    declarationReflection.comment.summary = [
+
+    const hookComment = workflowComments?.find(
+      (tag) => tag.tag === `@property` && tag.name === `hooks.${stepId}`
+    )
+
+    declarationReflection.comment.summary = hookComment?.content || [
       {
         kind: "text",
         text: "This step is a hook that you can inject custom functionality into.",
@@ -515,6 +526,16 @@ class WorkflowsPlugin {
     if (parameter.type.name === "__object") {
       parameter.type.name = "object"
       parameter.type.qualifiedName = "object"
+
+      if (!parameter.comment?.summary) {
+        parameter.comment = new Comment()
+        parameter.comment.summary = [
+          {
+            kind: "text",
+            text: "The input data for the hook.",
+          },
+        ]
+      }
     }
 
     signatureReflection.parameters = []