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/packages/docs-ui/src/components/Details/Summary/index.tsx

@@ -10,6 +10,7 @@ export type DetailsSummaryProps = {
   open?: boolean
   className?: string
   titleClassName?: string
+  hideExpandableIcon?: boolean
 } & Omit<React.HTMLAttributes<HTMLElement>, "title">
 
 export const DetailsSummary = ({
@@ -21,6 +22,7 @@ export const DetailsSummary = ({
   open = false,
   className,
   titleClassName,
+  hideExpandableIcon = false,
   ...rest
 }: DetailsSummaryProps) => {
   return (
@@ -54,7 +56,7 @@ export const DetailsSummary = ({
       {(badge || expandable) && (
         <span className="flex gap-docs_0.5">
           {badge}
-          {expandable && (
+          {expandable && !hideExpandableIcon && (
             <PlusMini
               className={clsx("transition-transform", open && "rotate-45")}
             />

www/packages/docs-ui/src/components/ExpandableNotice/index.tsx

@@ -0,0 +1,34 @@
+import React from "react"
+import { Badge, Link, Tooltip } from "@/components"
+
+export type ExpandableNoticeProps = {
+  type: "request" | "method"
+  link: string
+  badgeContent?: React.ReactNode
+  badgeClassName?: string
+}
+
+export const ExpandableNotice = ({
+  type = "request",
+  link,
+  badgeContent = "expendable",
+  badgeClassName,
+}: ExpandableNoticeProps) => {
+  return (
+    <Tooltip
+      tooltipChildren={
+        <>
+          If this {type} accepts an <code>expand</code>{" "}
+          {type === "request" ? "parameter" : "property or option"},
+          <br /> this field can be <Link href={link}>expanded</Link> into an
+          object.
+        </>
+      }
+      clickable
+    >
+      <Badge variant="blue" className={badgeClassName}>
+        {badgeContent}
+      </Badge>
+    </Tooltip>
+  )
+}

www/packages/docs-ui/src/components/FeatureFlagNotice/index.tsx

@@ -0,0 +1,40 @@
+import React from "react"
+import { Badge, Link, Tooltip } from "@/components"
+
+export type FeatureFlagNoticeProps = {
+  featureFlag: string
+  type?: "endpoint" | "parameter"
+  tooltipTextClassName?: string
+  badgeClassName?: string
+  badgeContent?: React.ReactNode
+}
+
+export const FeatureFlagNotice = ({
+  featureFlag,
+  type = "endpoint",
+  tooltipTextClassName,
+  badgeClassName,
+  badgeContent = "feature flag",
+}: FeatureFlagNoticeProps) => {
+  return (
+    <Tooltip
+      tooltipChildren={
+        <span className={tooltipTextClassName}>
+          To use this {type}, make sure to
+          <br />
+          <Link
+            href="https://docs.medusajs.com/development/feature-flags/toggle"
+            target="__blank"
+          >
+            enable its feature flag: <code>{featureFlag}</code>
+          </Link>
+        </span>
+      }
+      clickable
+    >
+      <Badge variant="green" className={badgeClassName}>
+        {badgeContent}
+      </Badge>
+    </Tooltip>
+  )
+}

www/packages/docs-ui/src/components/index.ts

@@ -11,6 +11,8 @@ export * from "./CodeTabs"
 export * from "./CopyButton"
 export * from "./Details"
 export * from "./Details/Summary"
+export * from "./ExpandableNotice"
+export * from "./FeatureFlagNotice"
 export * from "./Feedback"
 export * from "./Feedback/Solutions"
 export * from "./Icons"