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/api-reference/app/_mdx/admin.mdx

@@ -1096,17 +1096,12 @@ export default Products`,
 
 
 In the response of listing API Routes, aside from the entities retrieved,
-there are three pagination-related fields returned: `count`, `limit`, and
-`offset`.
+there are three pagination-related fields returned:
 
 
-Similar to the query parameters, `limit` is the maximum number of items that
-can be returned in the response, and `field` is the number of items that
-were skipped before the entities in the result.
-
-
-`count` is the total number of available items of this entity. It can be
-used to determine how many pages are there.
+- `limit`: the maximum number of items that can be returned in the response.
+- `offset`: the number of items that were skipped before the entities in the result.
+- `count`: the total number of available items of this entity. It can be used to determine how many pages are there.
 
 
 For example, if the `count` is 100 and the `limit` is 50, you can divide the

www/apps/api-reference/app/_mdx/store.mdx

@@ -155,7 +155,7 @@ You can learn more about publishable API keys and how to use them in [this docum
 ### How to Create a Publishable API Key
 
 You can create a publishable API key either using the [admin REST APIs](https://docs.medusajs.com/development/publishable-api-keys/admin/manage-publishable-api-keys),
-or using the [Medusa admin](https://docs.medusajs.com/user-guide/settings/publishable-api-keys).
+or using the [Medusa admin dashboard](https://docs.medusajs.com/user-guide/settings/publishable-api-keys).
 
 ### How to Use a Publishable API Key
 
@@ -1038,17 +1038,12 @@ export default Products`,
 
 
 In the response of listing API Routes, aside from the entities retrieved,
-there are three pagination-related fields returned: `count`, `limit`, and
-`offset`.
+there are three pagination-related fields returned:
 
 
-Similar to the query parameters, `limit` is the maximum number of items that
-can be returned in the response, and `field` is the number of items that
-were skipped before the entities in the result.
-
-
-`count` is the total number of available items of this entity. It can be
-used to determine how many pages are there.
+- `limit`: the maximum number of items that can be returned in the response.
+- `offset`: the number of items that were skipped before the entities in the result.
+- `count`: the total number of available items of this entity. It can be used to determine how many pages are there.
 
 
 For example, if the `count` is 100 and the `limit` is 50, you can divide the

www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx

@@ -7,9 +7,8 @@ import type { TagsOperationDescriptionSectionResponsesProps } from "./Responses"
 import dynamic from "next/dynamic"
 import TagsOperationDescriptionSectionParameters from "./Parameters"
 import MDXContentClient from "@/components/MDXContent/Client"
-import type { TagsOperationFeatureFlagNoticeProps } from "../FeatureFlagNotice"
 import { useArea } from "../../../../providers/area"
-import { Feedback, Badge, NextLink } from "docs-ui"
+import { Feedback, Badge, NextLink, FeatureFlagNotice } from "docs-ui"
 import { usePathname } from "next/navigation"
 import formatReportLink from "../../../../utils/format-report-link"
 
@@ -27,12 +26,6 @@ const TagsOperationDescriptionSectionResponses =
   dynamic<TagsOperationDescriptionSectionResponsesProps>(
     async () => import("./Responses")
   ) as React.FC<TagsOperationDescriptionSectionResponsesProps>
-
-const TagsOperationFeatureFlagNotice =
-  dynamic<TagsOperationFeatureFlagNoticeProps>(
-    async () => import("../FeatureFlagNotice")
-  ) as React.FC<TagsOperationFeatureFlagNoticeProps>
-
 type TagsOperationDescriptionSectionProps = {
   operation: Operation
 }
@@ -52,7 +45,7 @@ const TagsOperationDescriptionSection = ({
           </Badge>
         )}
         {operation["x-featureFlag"] && (
-          <TagsOperationFeatureFlagNotice
+          <FeatureFlagNotice
             featureFlag={operation["x-featureFlag"]}
             tooltipTextClassName="font-normal text-medusa-fg-subtle"
             badgeClassName="ml-0.5"

www/apps/api-reference/components/Tags/Operation/Parameters/Name/index.tsx

@@ -1,18 +1,12 @@
 import type { SchemaObject } from "@/types/openapi"
 import dynamic from "next/dynamic"
 import type { TooltipProps } from "docs-ui"
-import type { TagsOperationFeatureFlagNoticeProps } from "../../FeatureFlagNotice"
-import { Badge, NextLink } from "docs-ui"
+import { Badge, ExpandableNotice, FeatureFlagNotice, NextLink } from "docs-ui"
 
 const Tooltip = dynamic<TooltipProps>(
   async () => (await import("docs-ui")).Tooltip
 ) as React.FC<TooltipProps>
 
-const TagsOperationFeatureFlagNotice =
-  dynamic<TagsOperationFeatureFlagNoticeProps>(
-    async () => import("../../FeatureFlagNotice")
-  ) as React.FC<TagsOperationFeatureFlagNoticeProps>
-
 export type TagOperationParametersNameProps = {
   name: string
   isRequired?: boolean
@@ -35,25 +29,13 @@ const TagOperationParametersName = ({
       {schema["x-expandable"] && (
         <>
           <br />
-          <Tooltip
-            tooltipChildren={
-              <>
-                If this request accepts an <code>expand</code> parameter,
-                <br /> this field can be{" "}
-                <NextLink href="#expanding-fields">expanded</NextLink> into an
-                object.
-              </>
-            }
-            clickable
-          >
-            <Badge variant="blue">expandable</Badge>
-          </Tooltip>
+          <ExpandableNotice type="request" link="#expanding-fields" />
         </>
       )}
       {schema["x-featureFlag"] && (
         <>
           <br />
-          <TagsOperationFeatureFlagNotice
+          <FeatureFlagNotice
             featureFlag={schema["x-featureFlag"]}
             type="parameter"
           />