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

docs: change from detecting version to since tag (#13127)

Browse Source 
* update everything from version to since

* update events

* regenerate oas
This commit is contained in:
Shahed Nasser
2025-08-01 18:22:42 +03:00
committed by GitHub
parent 57ad8fc755
commit 522fc12d7a
36 changed files with 94 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -600,16 +600,16 @@ class DefaultKindGenerator<T extends ts.Node = ts.Node> {
* Retrieve information from the tags of a node.
*
* @param node - The node to retrieve the information from.
* @returns An object containing the deprecated and version tags, if available.
* @returns An object containing the deprecated and since tags, if available.
*/
getInformationFromTags(node: ts.Node): {
deprecatedTag: ts.JSDocTag | undefined
versionTag: ts.JSDocTag | undefined
sinceTag: ts.JSDocTag | undefined
featureFlagTag: ts.JSDocTag | undefined
} {
const nodeComments = ts.getJSDocCommentsAndTags(node)
let deprecatedTag: ts.JSDocTag | undefined
let versionTag: ts.JSDocTag | undefined
let sinceTag: ts.JSDocTag | undefined
let featureFlagTag: ts.JSDocTag | undefined
nodeComments.forEach((comment) => {
@@ -622,8 +622,8 @@ class DefaultKindGenerator<T extends ts.Node = ts.Node> {
deprecatedTag = tag
}
if (tag.tagName.getText() === "version") {
versionTag = tag
if (tag.tagName.getText() === "since") {
sinceTag = tag
}
if (tag.tagName.getText() === "featureFlag") {
@@ -634,7 +634,7 @@ class DefaultKindGenerator<T extends ts.Node = ts.Node> {
return {
deprecatedTag,
versionTag,
sinceTag,
featureFlagTag,
}
}

8
www/utils/packages/docs-generator/src/classes/kinds/events.ts
View File

@@ -50,7 +50,7 @@ class EventsKindGenerator extends DefaultKindGenerator<ts.VariableDeclaration> {
const commentsAndTags = ts.getJSDocCommentsAndTags(propertyAssignment)
let payloadTag: ts.JSDocTag | undefined
let versionTag: ts.JSDocTag | undefined
let sinceTag: ts.JSDocTag | undefined
let deprecatedTag: ts.JSDocTag | undefined
let description: string | undefined
commentsAndTags.forEach((comment) => {
@@ -67,8 +67,8 @@ class EventsKindGenerator extends DefaultKindGenerator<ts.VariableDeclaration> {
payloadTag = tag
}
if (tag.tagName.getText() === "version") {
versionTag = tag
if (tag.tagName.getText() === "since") {
sinceTag = tag
}
if (tag.tagName.getText() === "deprecated") {
@@ -84,7 +84,7 @@ class EventsKindGenerator extends DefaultKindGenerator<ts.VariableDeclaration> {
payload: (payloadTag?.comment as string) ?? "",
description,
workflows,
version: versionTag?.comment as string,
since: sinceTag?.comment as string,
deprecated: deprecatedTag !== undefined,
deprecated_message: deprecatedTag?.comment as string,
}

20
www/utils/packages/docs-generator/src/classes/kinds/oas.ts
View File

@@ -448,7 +448,7 @@ class OasKindGenerator extends FunctionKindGenerator {
}
// check deprecation and version in tags
const { deprecatedTag, versionTag, featureFlagTag } =
const { deprecatedTag, sinceTag, featureFlagTag } =
this.getInformationFromTags(node)
if (deprecatedTag) {
@@ -458,9 +458,9 @@ class OasKindGenerator extends FunctionKindGenerator {
: undefined
}
if (versionTag) {
oas["x-version"] = versionTag.comment
? (versionTag.comment as string)
if (sinceTag) {
oas["x-since"] = sinceTag.comment
? (sinceTag.comment as string)
: undefined
}
@@ -804,7 +804,7 @@ class OasKindGenerator extends FunctionKindGenerator {
}
// check deprecation and version in tags
const { deprecatedTag, versionTag, featureFlagTag } =
const { deprecatedTag, sinceTag, featureFlagTag } =
this.getInformationFromTags(node)
if (deprecatedTag) {
@@ -817,12 +817,12 @@ class OasKindGenerator extends FunctionKindGenerator {
delete oas["x-deprecated_message"]
}
if (versionTag) {
oas["x-version"] = versionTag.comment
? (versionTag.comment as string)
if (sinceTag) {
oas["x-since"] = sinceTag.comment
? (sinceTag.comment as string)
: undefined
} else {
delete oas["x-version"]
delete oas["x-since"]
}
if (featureFlagTag) {
@@ -2807,7 +2807,7 @@ class OasKindGenerator extends FunctionKindGenerator {
description: event.description,
deprecated: event.deprecated,
deprecated_message: event.deprecated_message,
version: event.version,
since: event.since,
}))
)
}

4
www/utils/packages/docs-generator/src/types/index.d.ts vendored
View File

@@ -12,7 +12,7 @@ export declare type OpenApiOperation = Partial<OpenAPIV3.OperationObject> & {
"x-workflow"?: string
"x-events"?: OasEvent[]
"x-deprecated_message"?: string
"x-version"?: string
"x-since"?: string
"x-featureFlag"?: string
"x-ignoreCleanup"?: boolean
}
@@ -51,5 +51,5 @@ export declare type OasEvent = {
description?: string
deprecated?: boolean
deprecated_message?: string
version?: string
since?: string
}

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

@@ -7,7 +7,7 @@ const EXCLUDED_TAGS = [
"@featureFlag",
"@category",
"@typeParamDefinition",
"@version",
"@since",
"@tags",
"@summary",
"@workflowEvent",

30
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/events-listing.ts
View File

@@ -119,18 +119,18 @@ function formatEventsType(
}
}
const versionTag = event.comment?.blockTags.find(
(tag) => tag.tag === "@version"
const sinceTag = event.comment?.blockTags.find(
(tag) => tag.tag === "@since"
)
if (versionTag) {
if (sinceTag) {
eventName += `\n`
const versionText = versionTag.content
const sinceText = sinceTag.content
.map((content) => content.text)
.join("")
.trim()
eventName += `<Tooltip text="This event was added in version v${versionText}">`
eventName += `<Badge variant="blue">v${versionText}</Badge>`
eventName += `<Tooltip text="This event was added in version v${sinceText}">`
eventName += `<Badge variant="blue">v${sinceText}</Badge>`
eventName += `</Tooltip>`
}
@@ -166,8 +166,8 @@ function formatEventsType(
.join("")
.trim()
const versionTag = event.comment?.blockTags.find(
(tag) => tag.tag === "@version"
const sinceTag = event.comment?.blockTags.find(
(tag) => tag.tag === "@since"
)
content.push(
@@ -177,8 +177,8 @@ function formatEventsType(
payload: eventPayload || "",
deprecated: !!deprecatedTag,
deprecatedMessage,
version: versionTag
? versionTag.content
since: sinceTag
? sinceTag.content
.map((content) => content.text)
.join("")
.trim()
@@ -215,14 +215,14 @@ function getEventHeading({
payload,
deprecated = false,
deprecatedMessage,
version,
since,
}: {
titleLevel: number
eventName: string
payload: string
deprecated?: boolean
deprecatedMessage?: string
version?: string
since?: string
}) {
const heading = [eventName]
if (deprecated) {
@@ -236,12 +236,12 @@ function getEventHeading({
heading.push(`</Tooltip>`)
}
}
if (version) {
if (since) {
if (deprecated) {
heading.push(`\n`)
}
heading.push(`<Tooltip text="This event was added in version v${version}">`)
heading.push(`<Badge variant="blue">v${version}</Badge>`)
heading.push(`<Tooltip text="This event was added in version v${since}">`)
heading.push(`<Badge variant="blue">v${since}</Badge>`)
heading.push(`</Tooltip>`)
}
return `<EventHeader headerLvl="${titleLevel}" headerProps={{ id: "${getEventNameSlug(

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

@@ -3,17 +3,15 @@ import { Reflection } from "typedoc"
export default function () {
Handlebars.registerHelper("version", function (reflection: Reflection) {
const versionTag = reflection.comment?.blockTags.find(
(tag) => tag.tag === "@version"
const sinceTag = reflection.comment?.blockTags.find(
(tag) => tag.tag === "@since"
)
if (!versionTag) {
if (!sinceTag) {
return ""
}
const tagContent = versionTag.content
.map((content) => content.text)
.join("")
const tagContent = sinceTag.content.map((content) => content.text).join("")
return `:::note\n\nThis is only available after Medusa \`v${tagContent}\`.\n\n:::`
})

20
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-events.ts
View File

@@ -41,22 +41,18 @@ export default function () {
const eventPayloadFormatted = eventPayload
.replace("```ts\n", "")
.replace("\n```", "")
const isDeprecatedOrHasVersion = commentContent.length >= 4
const deprecatedIndex = isDeprecatedOrHasVersion
const isDeprecatedOrHasSince = commentContent.length >= 4
const deprecatedIndex = isDeprecatedOrHasSince
? commentContent.slice(3).findIndex((c) => c.trim() === "deprecated")
: -1
const isDeprecated = deprecatedIndex !== -1
const deprecatedText = (
isDeprecated ? commentContent[3 + deprecatedIndex] || "" : ""
).trim()
const version = isDeprecatedOrHasVersion
? commentContent
.slice(3)
.find((c) => c.trim().startsWith("version: "))
const since = isDeprecatedOrHasSince
? commentContent.slice(3).find((c) => c.trim().startsWith("since: "))
: undefined
const versionText = (
version ? version.replace("version: ", "") : ""
).trim()
const sinceText = (since ? since.replace("since: ", "") : "").trim()
if (isDeprecated) {
eventNameFormatted += `\n`
@@ -69,10 +65,10 @@ export default function () {
}
}
if (versionText) {
if (sinceText) {
eventNameFormatted += `\n\n`
eventNameFormatted += `<Tooltip text="This event was added in version v${versionText}">`
eventNameFormatted += `<Badge variant="blue">v${versionText}</Badge>`
eventNameFormatted += `<Tooltip text="This event was added in version v${sinceText}">`
eventNameFormatted += `<Badge variant="blue">v${sinceText}</Badge>`
eventNameFormatted += `</Tooltip>\n`
}

4
www/utils/packages/typedoc-plugin-workflows/src/plugin.ts
View File

@@ -928,8 +928,8 @@ class WorkflowsPlugin {
commentText += ` -- ${event.deprecated_message}`
}
}
if (event.version) {
commentText += ` -- version: ${event.version}`
if (event.since) {
commentText += ` -- since: ${event.since}`
}
return new CommentTag(`@workflowEvent`, [
{

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

@@ -344,8 +344,7 @@ export declare type MedusaEvent = {
payload: string
description?: string
workflows: string[]
version?: string
since?: string
deprecated?: boolean
deprecated_message?: string
version?: string
}