docs: add TSDoc for payment processor + generate docs (#5917)

* added tsdocs for payment processor

* generated reference for payment processor

docs-util/packages/scripts/generate-reference.ts

@@ -12,7 +12,7 @@ const require = createRequire(import.meta.url)
 const referenceNames = process.argv.slice(2) || ["all"]
 const basePath = path.join(require.resolve("typedoc-config"), "..")
 let generatedCount = 0
-let totalCount = 0
+let totalCount = referenceNames.length
 let ranMerger = false
 
 if (!referenceNames.length) {
@@ -37,7 +37,6 @@ referenceNames.forEach((name) => {
   } else if (name === "merge") {
     runMerger()
   } else {
-    totalCount = 1
     generateReference(`${name}.js`)
   }
 })

docs-util/packages/typedoc-config/_merger.js

@@ -227,6 +227,27 @@ module.exports = {
       },
     },
 
+    // PAYMENT CONFIG
+    "^payment": {
+      frontmatterData: {
+        displayed_sidebar: "modules",
+      },
+      maxLevel: 2,
+    },
+    "^payment/.*AbstractPaymentProcessor": {
+      reflectionDescription: `In this document, you’ll learn how to create a Payment Processor in your Medusa backend. If you’re unfamiliar with the Payment architecture in Medusa, make sure to check out the [overview](https://docs.medusajs.com/modules/carts-and-checkout/payment) first.`,
+      frontmatterData: {
+        displayed_sidebar: "modules",
+        slug: "/modules/carts-and-checkout/backend/add-payment-provider",
+      },
+      reflectionTitle: {
+        fullReplacement: "How to Create a Payment Processor",
+      },
+      reflectionGroups: {
+        Properties: false,
+      },
+    },
+
     // PRICING CONFIG
     "^(pricing|IPricingModuleService)": {
       ...modulesOptions,

docs-util/packages/typedoc-config/fulfillment.js

@@ -5,5 +5,4 @@ module.exports = getConfig({
   entryPointPath: "packages/medusa/src/interfaces/fulfillment-service.ts",
   tsConfigName: "medusa.json",
   name: "fulfillment",
-  // enableInternalResolve: true,
 })

docs-util/packages/typedoc-config/payment.js

@@ -0,0 +1,8 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+const getConfig = require("./utils/get-config")
+
+module.exports = getConfig({
+  entryPointPath: "packages/medusa/src/interfaces/payment-processor.ts",
+  tsConfigName: "medusa.json",
+  name: "payment",
+})

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/declaration-title.ts

@@ -8,7 +8,7 @@ import {
 } from "typedoc"
 import { MarkdownTheme } from "../../theme"
 import { memberSymbol, stripComments } from "../../utils"
-import { escapeChars, stripLineBreaks } from "utils"
+import { escapeChars, stripLineBreaks, getType as getTypeUtils } from "utils"
 
 export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
@@ -25,10 +25,12 @@ export default function (theme: MarkdownTheme) {
         }
         return (
           (reflection.parent?.kindOf(ReflectionKind.Enum) ? " = " : ": ") +
-          Handlebars.helpers.type.call(
-            reflectionType ? reflectionType : reflection,
-            "object"
-          )
+          getTypeUtils({
+            reflectionType: reflectionType || reflection.type,
+            collapse: "object",
+            escape: true,
+            getRelativeUrlMethod: Handlebars.helpers.relativeURL,
+          })
         )
       }
 

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/signature-title.ts

@@ -66,7 +66,9 @@ export default function (theme: MarkdownTheme) {
       md.push(`(${getParameters(this.parameters, false)})`)
 
       if (this.type && !this.parent?.kindOf(ReflectionKind.Constructor)) {
-        md.push(`: ${Handlebars.helpers.type.call(this.type, "none", false)}`)
+        md.push(
+          `: ${Handlebars.helpers.type.call(this.type, "none", !expandMembers)}`
+        )
       }
 
       if (!expandMembers) {

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/type-declaration-object-literal.ts

@@ -19,7 +19,7 @@ export default function (theme: MarkdownTheme) {
 
       const properties = this.reduce(
         (acc: ReflectionParameterType[], current: ReflectionParameterType) =>
-          parseParams(current, acc),
+          parseParams(current, acc, false),
         []
       ) as DeclarationReflection[]
 

docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/params-utils.ts

@@ -23,13 +23,16 @@ export function flattenParams(
 
 export function parseParams(
   current: ReflectionParameterType,
-  acc: ReflectionParameterType[]
+  acc: ReflectionParameterType[],
+  flatten?: boolean
 ): ReflectionParameterType[] {
   const shouldFlatten =
-    current.type &&
-    "declaration" in current.type &&
-    current.type?.declaration?.kind === ReflectionKind.TypeLiteral &&
-    current.type?.declaration?.children
+    flatten !== undefined
+      ? flatten
+      : current.type &&
+        "declaration" in current.type &&
+        current.type?.declaration?.kind === ReflectionKind.TypeLiteral &&
+        current.type?.declaration?.children
   return shouldFlatten
     ? [...acc, current, ...flattenParams(current)]
     : [...acc, current]

docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts

@@ -128,12 +128,13 @@ export function reflectionComponentFormatter({
           reflectionType: reflection.type,
           collapse: "object",
           project: reflection.project,
+          escape: true,
           getRelativeUrlMethod: Handlebars.helpers.relativeURL,
         })
       : getReflectionType({
           reflectionType: reflection,
           collapse: "object",
-          wrapBackticks: true,
+          // escape: true,
           project: reflection.project,
           getRelativeUrlMethod: Handlebars.helpers.relativeURL,
         }),
@@ -153,15 +154,6 @@ export function reflectionComponentFormatter({
     (reflection.type || hasChildren) &&
     level + 1 <= (maxLevel || MarkdownTheme.MAX_LEVEL)
   ) {
-    // if (
-    //   reflection.name === "user" &&
-    //   reflection.type &&
-    //   "name" in reflection.type &&
-    //   reflection.type.name.startsWith("Omit") &&
-    //   "typeArguments" in reflection.type
-    // ) {
-    //   console.log(reflection)
-    // }
     const children = hasChildren
       ? reflection.children
       : getTypeChildren(reflection.type!, project || reflection.project)

docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/return-reflection-formatter.ts

@@ -34,14 +34,21 @@ export function returnReflectionComponentFormatter({
     reflectionType,
     collapse: "object",
     wrapBackticks: false,
+    escape: false,
     hideLink: true,
     project,
     getRelativeUrlMethod: Handlebars.helpers.relativeURL,
   })
+  // if (
+  //   typeName === "Record<string, unknown> \\| PaymentProcessorError"
+  // ) {
+  //   console.log(reflectionType)
+  // }
   const type = getType({
     reflectionType: reflectionType,
     collapse: "object",
     project,
+    escape: true,
     getRelativeUrlMethod: Handlebars.helpers.relativeURL,
   })
   const componentItem: Parameter[] = []

docs-util/packages/utils/src/get-type-str.ts

@@ -312,10 +312,9 @@ export function getReferenceType({
   getRelativeUrlMethod,
   ...options
 }: TypeOptions<ReferenceType>): string {
-  escape = getShouldEscape(wrapBackticks, escape)
-
   const shouldShowLink = !hideLink && model.name !== "Record"
   const wrappedInBackticks = wrapBackticks && !shouldShowLink
+  escape = getShouldEscape(wrappedInBackticks, escape)
   let modelReflection = model.reflection
   if (!modelReflection && project) {
     // try to load reflection