chore: added TSDocs to product module service interface (#5341)

* added tsdocs for product module service

* general fixes

* added generate github action

* fix typedoc configurations

* update comments

* change configurations

* address PR feedback

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

@@ -52,14 +52,4 @@ module.exports = modulesConfig({
       },
     },
   ],
-  extraOptions: {
-    // frontmatterData: {
-    //   displayed_sidebar: "modules",
-    //   badge: {
-    //     variant: "orange",
-    //     text: "Beta",
-    //   },
-    //   // hide_table_of_contents: true,
-    // },
-  },
 })

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

@@ -0,0 +1,55 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+const modulesConfig = require("./modules")
+
+module.exports = modulesConfig({
+  entryPointPath: "packages/types/src/product/service.ts",
+  outPath: "www/apps/docs/content/references/product",
+  moduleName: "Product Module Reference",
+  documentsToFormat: [
+    {
+      pattern: "IProductModuleService.md",
+      additionalFormatting: {
+        reflectionDescription:
+          "This section of the documentation provides a reference to the `IProductModuleService` interface’s methods. This is the interface developers use to use the functionalities provided by the Product Module.",
+        frontmatterData: {
+          displayed_sidebar: "productReference",
+          badge: {
+            variant: "orange",
+            text: "Beta",
+          },
+          slug: "/references/product",
+        },
+      },
+    },
+    {
+      pattern: "IProductModuleService/methods",
+      additionalFormatting: {
+        reflectionDescription:
+          "This documentation provides a reference to the {{alias}} {{kind}}. This belongs to the Product Module.",
+        frontmatterData: {
+          displayed_sidebar: "productReference",
+          badge: {
+            variant: "orange",
+            text: "Beta",
+          },
+          slug: "/references/product/{{alias}}",
+          sidebar_label: "{{alias}}",
+        },
+        reflectionTitle: {
+          kind: false,
+          typeParameters: false,
+          suffix: "- Product Module Reference",
+        },
+      },
+    },
+    {
+      pattern: "*",
+      useDefaults: true,
+      additionalFormatting: {
+        frontmatterData: {
+          displayed_sidebar: "productReference",
+        },
+      },
+    },
+  ],
+})

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

@@ -1,6 +1,7 @@
 import {
   Comment,
   DeclarationReflection,
+  ReflectionKind,
   ProjectReflection,
   ReflectionType,
   SomeType,
@@ -36,8 +37,13 @@ export function reflectionListFormatter(
   const prefix = `${Array(level - 1)
     .fill("\t")
     .join("")}-`
-  let item = `${prefix} \`${reflection.name}\`: `
+  let item = `${prefix} \`${reflection.name}\``
   const defaultValue = getDefaultValue(reflection)
+  const comments = getComments(reflection)
+
+  if (defaultValue || reflection.flags.isOptional || comments) {
+    item += ": "
+  }
 
   if (defaultValue || reflection.flags.isOptional) {
     item += `(${reflection.flags.isOptional ? "optional" : ""}${
@@ -45,8 +51,6 @@ export function reflectionListFormatter(
     }${defaultValue ? `default: ${defaultValue}` : ""}) `
   }
 
-  const comments = getComments(reflection)
-
   if (comments) {
     item += stripLineBreaks(Handlebars.helpers.comments(comments))
   }
@@ -58,17 +62,18 @@ export function reflectionListFormatter(
       ? reflection.children
       : getTypeChildren(reflection.type!, reflection.project)
     const itemChildren: string[] = []
+    let itemChildrenKind: ReflectionKind | null = null
     children?.forEach((childItem) => {
+      if (!itemChildrenKind) {
+        itemChildrenKind = childItem.kind
+      }
       itemChildren.push(reflectionListFormatter(childItem, level + 1))
     })
     if (itemChildren.length) {
-      // TODO maybe we should check the type of the reflection and replace
-      // `properties` with the text that makes sense for the type.
-      item += ` ${
-        reflection.type?.type === "array"
-          ? "Its items accept the following properties"
-          : "It accepts the following properties"
-      }:\n${itemChildren.join("\n")}`
+      item += ` ${getItemExpandText(
+        reflection.type?.type,
+        itemChildrenKind
+      )}:\n${itemChildren.join("\n")}`
     }
   }
 
@@ -223,6 +228,24 @@ export function getComments(
   return parameter.comment
 }
 
+// TODO we should add check for more types as necessary
+function getItemExpandText(
+  reflectionType?: string,
+  childrenKind?: ReflectionKind | null
+): string {
+  switch (childrenKind) {
+    case ReflectionKind.EnumMember:
+      return "It can be one of the following values"
+  }
+
+  switch (reflectionType) {
+    case "array":
+      return "Its items accept the following properties"
+    default:
+      return "It accepts the following properties"
+  }
+}
+
 export function getTypeChildren(
   reflectionType: SomeType,
   project: ProjectReflection