asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: support since, deprecated, and feature flag tags in dml reference (#13741)

Browse Source
This commit is contained in:
Shahed Nasser
2025-10-13 13:31:48 +03:00
committed by GitHub
parent 958b003a11
commit 9a5ca86b76
16 changed files with 274 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
www/packages/docs-ui/src/components/Notices/DeprecatedNotice/index.tsx Normal file
View File

@@ -0,0 +1,32 @@
import React from "react"
import { Badge, Tooltip } from "@/components"
export type DeprecatedNoticeProps = {
description?: string
tooltipTextClassName?: string
badgeClassName?: string
badgeContent?: React.ReactNode
}
export const DeprecatedNotice = ({
description,
tooltipTextClassName,
badgeClassName,
badgeContent = `Deprecated`,
}: DeprecatedNoticeProps) => {
return (
<Tooltip
tooltipChildren={
<span className={tooltipTextClassName}>
{description ||
"This feature is deprecated and may be removed in future releases."}
</span>
}
clickable
>
<Badge variant="neutral" className={badgeClassName}>
{badgeContent}
</Badge>
</Tooltip>
)
}

0
www/packages/docs-ui/src/components/ExpandableNotice/index.tsx → www/packages/docs-ui/src/components/Notices/ExpandableNotice/index.tsx
View File

0
www/packages/docs-ui/src/components/FeatureFlagNotice/index.tsx → www/packages/docs-ui/src/components/Notices/FeatureFlagNotice/index.tsx
View File

37
www/packages/docs-ui/src/components/Notices/VersionNotice/index.tsx Normal file
View File

@@ -0,0 +1,37 @@
import React from "react"
import { Badge, Tooltip } from "@/components"
export type VersionNoticeProps = {
version: string
tooltipTextClassName?: string
badgeClassName?: string
badgeContent?: React.ReactNode
}
export const VersionNotice = ({
version,
tooltipTextClassName,
badgeClassName,
badgeContent = `v${version}`,
}: VersionNoticeProps) => {
return (
<Tooltip
tooltipChildren={
<span className={tooltipTextClassName}>
This is available starting from
<br />
<a
href={`https://github.com/medusajs/medusa/releases/tag/${version}`}
>
Medusa v{version}
</a>
</span>
}
clickable
>
<Badge variant="blue" className={badgeClassName}>
{badgeContent}
</Badge>
</Tooltip>
)
}

11
www/packages/docs-ui/src/components/TypeList/Items/index.tsx
View File

@@ -22,6 +22,8 @@ import {
import { decodeStr, isInView } from "@/utils"
import { usePathname } from "next/navigation"
import { useIsBrowser, useSiteConfig } from "../../.."
import { VersionNotice } from "../../Notices/VersionNotice"
import { DeprecatedNotice } from "../../Notices/DeprecatedNotice"
type CommonProps = ParentCommonProps & {
level?: number
@@ -236,6 +238,15 @@ const TypeListItem = ({
badgeContent={<ArrowsPointingOutMini />}
/>
)}
{item.since && (
<VersionNotice
version={item.since}
badgeClassName="!p-0 leading-none"
/>
)}
{item.deprecated?.is_deprecated && (
<DeprecatedNotice description={item.deprecated?.description} />
)}
</div>
</div>
</DetailsSummary>

5
www/packages/docs-ui/src/components/TypeList/index.tsx
View File

@@ -17,6 +17,11 @@ export type Type = {
featureFlag?: string
expandable: boolean
children?: Type[]
deprecated?: {
is_deprecated: boolean
description?: string
}
since?: string
}
type ParameterTypesType = {

6
www/packages/docs-ui/src/components/index.ts
View File

@@ -22,8 +22,10 @@ export * from "./Details/Summary"
export * from "./DetailsList"
export * from "./DottedSeparator"
export * from "./EditButton"
export * from "./ExpandableNotice"
export * from "./FeatureFlagNotice"
export * from "./Notices/ExpandableNotice"
export * from "./Notices/FeatureFlagNotice"
export * from "./Notices/DeprecatedNotice"
export * from "./Notices/VersionNotice"
export * from "./Feedback"
export * from "./Feedback/Solutions"
export * from "./Footer"

21
www/utils/packages/docs-generator/src/classes/kinds/default.ts
View File

@@ -606,14 +606,22 @@ class DefaultKindGenerator<T extends ts.Node = ts.Node> {
deprecatedTag: ts.JSDocTag | undefined
sinceTag: ts.JSDocTag | undefined
featureFlagTag: ts.JSDocTag | undefined
summary: string | undefined
} {
const nodeComments = ts.getJSDocCommentsAndTags(node)
let deprecatedTag: ts.JSDocTag | undefined
let sinceTag: ts.JSDocTag | undefined
let featureFlagTag: ts.JSDocTag | undefined
let summary: string | undefined
nodeComments.forEach((comment) => {
if (!("tags" in comment)) {
if (ts.isJSDoc(comment) && comment.comment) {
summary =
typeof comment.comment === "string"
? comment.comment
: comment.comment.map((part) => part.text).join(" ")
}
return
}
@@ -636,9 +644,22 @@ class DefaultKindGenerator<T extends ts.Node = ts.Node> {
deprecatedTag,
sinceTag,
featureFlagTag,
summary,
}
}
formatJSDocTag(tag: ts.JSDocTag | undefined): string | undefined {
if (!tag) {
return undefined
}
if (typeof tag.comment === "string") {
return tag.comment
}
return tag.comment?.map((part) => part.text).join(" ")
}
/**
* Check if a node is ignored.
*

35
www/utils/packages/docs-generator/src/classes/kinds/dml.ts
View File

@@ -101,10 +101,24 @@ class DmlKindGenerator extends DefaultKindGenerator<ts.CallExpression> {
dataModelName,
})
/**
* Use parent to get tags like since, deprecated, featureFlag
*/
const parent = node.parent?.parent?.parent
const { sinceTag, deprecatedTag, featureFlagTag } =
this.getInformationFromTags(parent)
const dmlFile: DmlFile = {
[dataModelName]: {
filePath: getBasePath(node.getSourceFile().fileName),
properties,
since: this.formatJSDocTag(sinceTag),
deprecated: {
is_deprecated: !!deprecatedTag,
description: this.formatJSDocTag(deprecatedTag),
},
featureFlag: this.formatJSDocTag(featureFlagTag),
},
}
@@ -229,8 +243,11 @@ class DmlKindGenerator extends DefaultKindGenerator<ts.CallExpression> {
)
const isBoolean = propertyTypeStr.includes("BooleanProperty")
const relationName = isRelation ? camelToWords(propertyName) : undefined
const { summary, sinceTag, deprecatedTag, featureFlagTag } =
this.getInformationFromTags(propertyNode)
let propertyDescription =
summary ||
this.knowledgeBaseFactory.tryToGetObjectPropertySummary({
retrieveOptions: {
str: propertyName,
@@ -251,6 +268,24 @@ class DmlKindGenerator extends DefaultKindGenerator<ts.CallExpression> {
propertyDescription += `\n\n@expandable`
}
if (sinceTag) {
propertyDescription += `\n\n@since ${
this.formatJSDocTag(sinceTag) ?? ""
}`
}
if (featureFlagTag) {
propertyDescription += `\n\n@featureFlag ${
this.formatJSDocTag(featureFlagTag) ?? ""
}`
}
if (deprecatedTag) {
propertyDescription += `\n\n@deprecated ${
this.formatJSDocTag(deprecatedTag) ?? ""
}`
}
properties[propertyName] = propertyDescription
})

82
www/utils/packages/typedoc-plugin-custom/src/dml-json-parser.ts
View File

@@ -3,6 +3,7 @@ import path from "path"
import {
Application,
Comment,
CommentTag,
Context,
Converter,
DeclarationReflection,
@@ -12,6 +13,9 @@ import { getDirname, getDmlProperties, isDmlEntity } from "utils"
import { DmlFile } from "types"
const FILE_NAME_REGEX = /packages\/modules\/(?<module>[a-z-]+)/
const SINCE_REGEX = /@since\s+([\d.]+)/
const DEPRECATED_REGEX = /@deprecated\s+(.+)/
const FEATURE_FLAG_REGEX = /@featureFlag\s+(\S+)/
export function load(app: Application) {
app.converter.on(
@@ -76,6 +80,41 @@ function getDescriptionsFromJson(
if (!jsonFileContent[reflection.name]) {
return
}
const comment = reflection.comment || new Comment()
if (jsonFileContent[reflection.name].since) {
comment.blockTags.push(
new CommentTag("@since", [
{
kind: "text",
text: jsonFileContent[reflection.name].since!,
},
])
)
}
if (jsonFileContent[reflection.name].deprecated?.is_deprecated) {
comment.blockTags.push(
new CommentTag("@deprecated", [
{
kind: "text",
text: jsonFileContent[reflection.name].deprecated!.description || "",
},
])
)
}
if (jsonFileContent[reflection.name].featureFlag) {
comment.blockTags.push(
new CommentTag("@featureFlag", [
{
kind: "text",
text: jsonFileContent[reflection.name].featureFlag!,
},
])
)
}
reflection.comment = comment
Object.entries(jsonFileContent[reflection.name].properties).forEach(
([propertyName, description]) => {
@@ -90,16 +129,57 @@ function getDescriptionsFromJson(
const comment = propertyReflection.comment || new Comment()
const isExpandable = description.includes("@expandable")
const sinceMatch = description.match(SINCE_REGEX)
const featureFlagMatch = description.match(FEATURE_FLAG_REGEX)
const deprecatedMatch = description.match(DEPRECATED_REGEX)
comment.summary.push({
kind: "text",
text: description.replace("@expandable", "").trim(),
text: description
.replace("@expandable", "")
.replace(SINCE_REGEX, "")
.replace(FEATURE_FLAG_REGEX, "")
.replace(DEPRECATED_REGEX, "")
.trim(),
})
if (isExpandable) {
comment.modifierTags.add("@expandable")
}
if (sinceMatch) {
comment.blockTags.push(
new CommentTag("@since", [
{
kind: "text",
text: sinceMatch[1],
},
])
)
}
if (featureFlagMatch) {
comment.blockTags.push(
new CommentTag("@featureFlag", [
{
kind: "text",
text: featureFlagMatch[1],
},
])
)
}
if (deprecatedMatch) {
comment.blockTags.push(
new CommentTag("@deprecated", [
{
kind: "text",
text: deprecatedMatch[1],
},
])
)
}
propertyReflection.comment = comment
}
)

2
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/version.ts
View File

@@ -13,6 +13,6 @@ export default function () {
const tagContent = sinceTag.content.map((content) => content.text).join("")
return `:::note\n\nThis is available starting from Medusa \`v${tagContent}\`.\n\n:::`
return `:::note\n\nThis is available starting from [Medusa v${tagContent}](https://github.com/medusajs/medusa/releases/tag/v${tagContent}).\n\n:::`
})
}

2
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.dml.hbs
View File

@@ -4,6 +4,8 @@
{{/if}}
{{{version this}}}
{{{sourceCodeLink}}}
{{{dmlProperties}}}

5
www/utils/packages/typedoc-plugin-markdown-medusa/src/types.ts
View File

@@ -34,4 +34,9 @@ export type Parameter = {
featureFlag?: string
expandable: boolean
children?: Parameter[]
since?: string
deprecated?: {
is_deprecated: boolean
description?: string
}
}

15
www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts
View File

@@ -133,6 +133,10 @@ export function reflectionComponentFormatter({
reflection.flags.isOptional ||
reflection.kind === ReflectionKind.EnumMember
const comments = getComments(reflection)
const deprecatedTag = comments?.blockTags.find(
(tag) => tag.tag === "@deprecated"
)
const sinceTag = comments?.blockTags.find((tag) => tag.tag === "@since")
const componentItem: Parameter = {
name: reflection.name,
type: reflection.type
@@ -160,6 +164,17 @@ export function reflectionComponentFormatter({
children: [],
}
if (sinceTag) {
componentItem.since = sinceTag.content.map((c) => c.text).join("")
}
if (deprecatedTag) {
componentItem.deprecated = {
is_deprecated: true,
description: deprecatedTag?.content.map((c) => c.text).join(""),
}
}
if (level + 1 > (maxLevel || MarkdownTheme.MAX_LEVEL)) {
return componentItem
}

20
www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-type-parameters.ts
View File

@@ -66,7 +66,12 @@ export function getReflectionTypeParameters({
description = loadComment(typeName, project)
}
return {
const deprecatedTag = comment?.blockTags.find(
(tag) => tag.tag === "@deprecated"
)
const sinceTag = comment?.blockTags.find((tag) => tag.tag === "@since")
const parameter: Parameter = {
name: "name" in reflectionType ? reflectionType.name : typeName,
type,
optional:
@@ -84,6 +89,19 @@ export function getReflectionTypeParameters({
featureFlag: Handlebars.helpers.featureFlag(comment),
children: [],
}
if (sinceTag) {
parameter.since = sinceTag.content.map((c) => c.text).join("")
}
if (deprecatedTag) {
parameter.deprecated = {
is_deprecated: true,
description: deprecatedTag?.content.map((c) => c.text).join(""),
}
}
return parameter
}
const componentItem: Parameter[] = []

6
www/utils/packages/types/lib/index.d.ts vendored
View File

@@ -307,6 +307,12 @@ export declare type DmlFile = {
[k: string]: {
filePath: string
properties: DmlObject
since?: string
deprecated?: {
is_deprecated: boolean
description?: string
}
featureFlag?: string
}
}