docs-util: support @tags comments (#10627)

* support tags in tsdocs + add them in frontmatter

* fixes

www/utils/packages/typedoc-config/tsdoc.json

@@ -53,6 +53,10 @@
     {
       "tagName": "@version",
       "syntaxKind": "block"
+    },
+    {
+      "tagName": "@tags",
+      "syntaxKind": "block"
     }
   ]
 }

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts

@@ -8,6 +8,7 @@ const EXCLUDED_TAGS = [
   "@category",
   "@typeParamDefinition",
   "@version",
+  "@tags",
 ]
 
 export default function () {

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/frontmatter.ts

@@ -3,6 +3,8 @@ import { MarkdownTheme } from "../../theme"
 import { stringify } from "yaml"
 import { replaceTemplateVariables } from "../../utils/reflection-template-strings"
 import { Reflection } from "typedoc"
+import { FrontmatterData } from "types"
+import { getTagComments, getTagsAsArray } from "utils"
 
 export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper("frontmatter", function (this: Reflection) {
@@ -13,34 +15,39 @@ export default function (theme: MarkdownTheme) {
     }
 
     // format frontmatter data in case it has any template variables
+    const resolvedFrontmatter = resolveFrontmatterVariables(
+      frontmatterData,
+      this
+    )
 
-    return `---\n${stringify(
+    // check if reflection has an `@tags` tag
-      resolveFrontmatterVariables(frontmatterData, this)
+    const tagsComment = getTagComments(this)
-    ).trim()}\n---\n\n`
+    if (tagsComment?.length && !("tags" in resolvedFrontmatter)) {
+      resolvedFrontmatter["tags"] = []
+    }
+    tagsComment?.forEach((tag) => {
+      const tagContent = getTagsAsArray(tag)
+      resolvedFrontmatter["tags"]?.push(...tagContent)
+    })
+
+    return `---\n${stringify(resolvedFrontmatter).trim()}\n---\n\n`
   })
 }
 
 function resolveFrontmatterVariables(
-  frontmatterData: Record<string, unknown>,
+  frontmatterData: FrontmatterData,
   reflection: Reflection
-): Record<string, unknown> {
+): FrontmatterData {
-  const tempFrontmatterData = Object.assign({}, frontmatterData)
+  const tempFrontmatterData: FrontmatterData = JSON.parse(
+    JSON.stringify(frontmatterData)
+  )
   Object.keys(tempFrontmatterData).forEach((key) => {
     const value = tempFrontmatterData[key]
-    if (!value) {
+    if (!value || typeof value !== "string") {
       return
     }
 
-    switch (typeof value) {
-      case "object":
-        tempFrontmatterData[key] = resolveFrontmatterVariables(
-          value as Record<string, unknown>,
-          reflection
-        )
-        break
-      case "string":
     tempFrontmatterData[key] = replaceTemplateVariables(reflection, value)
-    }
   })
 
   return tempFrontmatterData

www/utils/packages/types/lib/index.d.ts

@@ -50,6 +50,14 @@ export type FormattingOptionsType = {
   [k: string]: FormattingOptionType
 }
 
+export type FrontmatterData = {
+  slug?: string
+  sidebar_label?: string
+  displayed_sidebar?: string
+  tags?: string[]
+  [k: string]: unknown
+}
+
 export type FormattingOptionType = {
   sections?: Sections
   reflectionGroups?: {
@@ -74,7 +82,7 @@ export type FormattingOptionType = {
   showCommentsAsHeader?: boolean
   showCommentsAsDetails?: boolean
   parameterStyle?: ParameterStyle
-  frontmatterData?: Record<string, unknown>
+  frontmatterData?: FrontmatterData
   parameterComponent?: string
   parameterComponentExtraProps?: Record<string, unknown>
   mdxImports?: string[]

www/utils/packages/utils/src/index.ts

@@ -6,4 +6,5 @@ export * from "./hooks-util"
 export * from "./step-utils"
 export * from "./str-formatting"
 export * from "./str-utils"
+export * from "./tag-utils"
 export * from "./workflow-utils"

www/utils/packages/utils/src/tag-utils.ts

@@ -0,0 +1,25 @@
+import { CommentTag, DeclarationReflection, Reflection } from "typedoc"
+
+export const getTagsAsArray = (tag: CommentTag): string[] => {
+  return tag.content
+    .map((content) => content.text)
+    .join("")
+    .split(",")
+    .map((value) => value.trim())
+}
+
+export const getTagComments = (reflection: Reflection): CommentTag[] => {
+  const tagComments: CommentTag[] = []
+
+  reflection.comment?.blockTags
+    .filter((tag) => tag.tag === `@tags`)
+    .forEach((tag) => tagComments.push(tag))
+
+  if (reflection instanceof DeclarationReflection) {
+    reflection.signatures?.forEach((signature) =>
+      tagComments.push(...getTagComments(signature))
+    )
+  }
+
+  return tagComments
+}