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

docs-util/packages/utils/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "utils",
+  "private": true,
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "version": "0.0.0",
+  "scripts": {
+    "build": "yarn clean && tsc",
+    "lint": "eslint --ext .ts src",
+    "clean": "rimraf dist"
+  },
+  "peerDependencies": {
+    "typedoc": "0.25.x"
+  },
+  "devDependencies": {
+    "@types/node": "^16.11.10",
+    "typescript": "^4.6"
+  },
+  "dependencies": {
+    "rimraf": "^5.0.5"
+  }
+}

docs-util/packages/utils/src/get-project-child.ts

@@ -0,0 +1,43 @@
+import {
+  DeclarationReflection,
+  ProjectReflection,
+  ReflectionKind,
+} from "typedoc"
+
+export function getProjectChild(
+  project: ProjectReflection,
+  childName: string
+): DeclarationReflection | undefined {
+  let reflection: DeclarationReflection | undefined = project.getChildByName(
+    childName
+  ) as DeclarationReflection
+  const splitChildName = childName.split(".")
+
+  if (!reflection && splitChildName.length > 1) {
+    reflection = getProjectChild(
+      project,
+      splitChildName[splitChildName.length - 1]
+    )
+  }
+
+  if (
+    !reflection &&
+    project.parent &&
+    project.parent instanceof ProjectReflection
+  ) {
+    reflection = getProjectChild(project.parent, childName)
+  }
+
+  if (!reflection) {
+    const modules = project.getChildrenByKind(ReflectionKind.Module)
+    for (const module of modules) {
+      reflection = module.getChildByName(childName) as DeclarationReflection
+
+      if (reflection) {
+        break
+      }
+    }
+  }
+
+  return reflection
+}

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

@@ -0,0 +1,76 @@
+import { DeclarationReflection, ProjectReflection, SomeType } from "typedoc"
+import { getProjectChild } from "./get-project-child"
+
+export function getTypeChildren(
+  reflectionType: SomeType,
+  project: ProjectReflection | undefined
+): DeclarationReflection[] {
+  let children: DeclarationReflection[] = []
+
+  switch (reflectionType.type) {
+    case "intersection":
+      reflectionType.types.forEach((intersectionType) => {
+        children.push(...getTypeChildren(intersectionType, project))
+      })
+      break
+    case "reference":
+      // eslint-disable-next-line no-case-declarations
+      const referencedReflection =
+        reflectionType.reflection && "children" in reflectionType.reflection
+          ? reflectionType.reflection
+          : project
+          ? getProjectChild(project, reflectionType.name)
+          : undefined
+
+      if (referencedReflection instanceof DeclarationReflection) {
+        if (referencedReflection.children) {
+          children = referencedReflection.children
+        } else if (reflectionType.typeArguments?.length) {
+          reflectionType.typeArguments.forEach((typeArgument, index) => {
+            if (reflectionType.name === "Omit" && index > 0) {
+              switch (typeArgument.type) {
+                case "literal":
+                  removeChild(typeArgument.value?.toString(), children)
+                  break
+                case "union":
+                  typeArgument.types.forEach((childItem) => {
+                    if (childItem.type === "literal") {
+                      removeChild(childItem.value?.toString(), children)
+                    } else {
+                      getTypeChildren(childItem, project).forEach((child) => {
+                        removeChild(child.name, children)
+                      })
+                    }
+                  })
+              }
+            } else {
+              const typeArgumentChildren = getTypeChildren(
+                typeArgument,
+                project
+              )
+              children.push(...typeArgumentChildren)
+            }
+          })
+        } else if (referencedReflection.type) {
+          children = getTypeChildren(referencedReflection.type, project)
+        }
+      }
+      break
+    case "reflection":
+      children = reflectionType.declaration.children || [
+        reflectionType.declaration,
+      ]
+      break
+    case "array":
+      children = getTypeChildren(reflectionType.elementType, project)
+  }
+
+  return children
+}
+
+function removeChild(name: unknown, children: DeclarationReflection[]) {
+  const childIndex = children.findIndex((child) => child.name === name)
+  if (childIndex !== -1) {
+    children.splice(childIndex, 1)
+  }
+}

docs-util/packages/utils/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./get-type-children"
+export * from "./get-project-child"

docs-util/packages/utils/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true
+  },
+  "include": ["src"]
+}