chore: improve JS Client TSDoc comments (#5582)

* add oas schema to tsdoc parser

* add tsdoc (part 1)

* Finished tsdoc in js client

* general fixes

* added tsdoc in core medusa package

* parse schema tags in model files

* added maxlevel option

* added more tsdoc

* added tsdoc in core

* added TSDoc in core package

* generated client types

* support featureFlag and expandable tags

* added support for resource feature flag note

* fix api ignore plugin

* added eslint plugin

* support feature flag and expandable badges

* adjusted overview page + generated reference

* revert generated files

* added changeset

* add details about new typedoc options

* fix broken link

www/apps/docs/src/components/ParameterTypes/Items/index.tsx

@@ -1,8 +1,21 @@
-import { DetailsSummary, InlineCode, MarkdownContent } from "docs-ui"
+import {
+  Badge,
+  DetailsSummary,
+  ExpandableNotice,
+  FeatureFlagNotice,
+  InlineCode,
+  MarkdownContent,
+} from "docs-ui"
 import React from "react"
 import Details from "../../../theme/Details"
 import clsx from "clsx"
 import { Parameter } from ".."
+import {
+  ArrowDownLeftMini,
+  ArrowsPointingOutMini,
+  TriangleRightMini,
+} from "@medusajs/icons"
+import IconFlagMini from "../../../theme/Icon/FlagMini"
 
 type ParameterTypesItemsProps = {
   parameters: Parameter[]
@@ -13,17 +26,48 @@ const ParameterTypesItems = ({
   parameters,
   level = 1,
 }: ParameterTypesItemsProps) => {
+  function getGroupName() {
+    switch (level) {
+      case 1:
+        return "group/parameterOne"
+      case 2:
+        return "group/parameterTwo"
+      case 3:
+        return "group/parameterThree"
+      case 4:
+        return "group/parameterFour"
+    }
+  }
+  function getBorderForGroupName() {
+    switch (level) {
+      case 1:
+        return "group-open/parameterOne:border-solid group-open/parameterOne:border-0 group-open/parameterOne:border-b"
+      case 2:
+        return "group-open/parameterTwo:border-solid group-open/parameterTwo:border-0 group-open/parameterTwo:border-b"
+      case 3:
+        return "group-open/parameterThree:border-solid group-open/parameterThree:border-0 group-open/parameterThree:border-b"
+      case 4:
+        return "group-open/parameterFour:border-solid group-open/parameterFour:border-0 group-open/parameterFour:border-b"
+    }
+  }
+  function getRotateForGroupName() {
+    switch (level) {
+      case 1:
+        return "group-open/parameterOne:rotate-90"
+      case 2:
+        return "group-open/parameterTwo:rotate-90"
+      case 3:
+        return "group-open/parameterThree:rotate-90"
+      case 4:
+        return "group-open/parameterFour:rotate-90"
+    }
+  }
   function getItemClassNames(details = true) {
     return clsx(
-      level < 3 && [
-        "odd:[&:not(:first-child):not(:last-child)]:!border-y last:not(:first-child):!border-t",
-        "first:!border-t-0 first:not(:last-child):!border-b last:!border-b-0 even:!border-y-0",
-      ],
-      details && level == 1 && `group/parameter`,
-      !details &&
-        level == 1 &&
-        `group-open/parameter:border-solid group-open/parameter:border-0 group-open/parameter:border-b`,
-      level >= 3 && "!border-0"
+      "odd:[&:not(:first-child):not(:last-child)]:!border-y last:not(:first-child):!border-t",
+      "first:!border-t-0 first:not(:last-child):!border-b last:!border-b-0 even:!border-y-0",
+      details && getGroupName(),
+      !details && getBorderForGroupName()
     )
   }
   function getSummary(parameter: Parameter, key: number, nested = true) {
@@ -48,16 +92,15 @@ const ParameterTypesItems = ({
           ) : undefined
         }
         expandable={parameter.children?.length > 0}
+        hideExpandableIcon={true}
         className={clsx(
           getItemClassNames(false),
-          level < 3 && "!p-1",
-          !nested && "cursor-default",
-          level >= 3 && [
-            "pl-1 mt-1",
-            "mx-1 relative before:content-[''] before:h-full before:w-0.25",
-            "before:absolute before:top-0 before:left-0",
-            "before:bg-medusa-fg-muted before:rounded-full",
-          ]
+          "py-1 pr-1",
+          level === 1 && "pl-1",
+          level === 2 && "pl-3",
+          level === 3 && "pl-[120px]",
+          level === 4 && "pl-[160px]",
+          !nested && "cursor-default"
         )}
         onClick={(e) => {
           const targetElm = e.target as HTMLElement
@@ -68,35 +111,63 @@ const ParameterTypesItems = ({
           }
         }}
       >
-        <div className="flex gap-0.75">
-          <InlineCode>{parameter.name}</InlineCode>
-          <span className="font-monospace text-compact-small-plus text-medusa-fg-subtle">
-            <MarkdownContent allowedElements={["a"]} unwrapDisallowed={true}>
-              {parameter.type}
-            </MarkdownContent>
-          </span>
-          {parameter.optional === false && (
-            <span
+        <div className="flex gap-0.5">
+          {nested && (
+            <TriangleRightMini
               className={clsx(
-                "text-compact-x-small-plus uppercase",
-                "text-medusa-fg-error"
+                "text-medusa-fg-subtle transition-transform",
+                getRotateForGroupName()
               )}
-            >
-              Required
-            </span>
+            />
           )}
+          {!nested && level > 1 && (
+            <ArrowDownLeftMini
+              className={clsx("text-medusa-fg-subtle flip-y")}
+            />
+          )}
+          <div className="flex gap-0.75 flex-wrap">
+            <InlineCode>{parameter.name}</InlineCode>
+            <span className="font-monospace text-compact-small-plus text-medusa-fg-subtle">
+              <MarkdownContent allowedElements={["a"]} unwrapDisallowed={true}>
+                {parameter.type}
+              </MarkdownContent>
+            </span>
+            {parameter.optional === false && (
+              <span
+                className={clsx(
+                  "text-compact-x-small-plus uppercase",
+                  "text-medusa-fg-error"
+                )}
+              >
+                Required
+              </span>
+            )}
+            {parameter.featureFlag && (
+              <FeatureFlagNotice
+                featureFlag={parameter.featureFlag}
+                type="parameter"
+                badgeClassName="!p-0 leading-none"
+                badgeContent={
+                  <IconFlagMini className="!text-medusa-tag-green-text" />
+                }
+              />
+            )}
+            {parameter.expandable && (
+              <ExpandableNotice
+                type="method"
+                link="#"
+                badgeClassName="!p-0 leading-none"
+                badgeContent={<ArrowsPointingOutMini />}
+              />
+            )}
+          </div>
         </div>
       </DetailsSummary>
     )
   }
 
   return (
-    <div
-      className={clsx(
-        level > 1 && "bg-docs-bg-surface rounded",
-        level >= 3 && "mb-1"
-      )}
-    >
+    <div>
       {parameters.map((parameter, key) => {
         return (
           <>

www/apps/docs/src/components/ParameterTypes/index.tsx

@@ -8,6 +8,8 @@ export type Parameter = {
   optional?: boolean
   defaultValue?: string
   description?: string
+  featureFlag?: string
+  expandable: boolean
   children?: Parameter[]
 }
 
@@ -22,7 +24,7 @@ const ParameterTypes = ({
 }: ParameterTypesType) => {
   return (
     <div
-      className={clsx("bg-docs-bg shadow-card-rest rounded", className)}
+      className={clsx("bg-docs-bg-surface shadow-card-rest rounded", className)}
       {...props}
     >
       <ParameterTypesItems parameters={parameters} />

www/apps/docs/src/theme/Icon/FlagMini/index.tsx

@@ -0,0 +1,27 @@
+import { IconProps } from "@medusajs/icons/dist/types"
+import clsx from "clsx"
+import React from "react"
+
+const IconFlagMini = (props: IconProps) => {
+  return (
+    <svg
+      width={props.width || 20}
+      height={props.height || 20}
+      viewBox="0 0 20 20"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+      className={clsx("text-ui-fg-subtle", props.className)}
+    >
+      <path
+        d="M5 4V5.51664M5 5.51664L6.51482 5.05445C7.65471 4.70701 8.85891 4.86835 9.90977 5.5093L9.96883 5.54531C10.9985 6.1731 12.1759 6.34089 13.2965 6.0195L14.9973 5.53131C14.7905 7.8586 14.7914 10.2064 15 12.5334L13.2971 13.0216C12.1764 13.3434 10.9987 13.1758 9.96883 12.5481L9.90977 12.5121C8.85891 11.8711 7.65471 11.7098 6.51482 12.0572L5 12.5194M5 5.51664V12.5194M5 16V12.5194"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+export default IconFlagMini

www/apps/docs/src/theme/Icon/index.tsx

@@ -101,6 +101,7 @@ import {
 } from "@medusajs/icons"
 import IconPuzzleSolid from "./PuzzleSolid"
 import IconNextjs from "./Nextjs"
+import IconFlagMini from "./FlagMini"
 
 export default {
   "academic-cap-solid": AcademicCapSolid,
@@ -159,6 +160,7 @@ export default {
   "folder-open": FolderOpen,
   gatsby: Gatsby,
   "gift-solid": GiftSolid,
+  "flag-mini": IconFlagMini,
   github: Github,
   "globe-europe": GlobeEurope,
   "globe-europe-solid": GlobeEuropeSolid,