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

chore: added and improved TSDoc of pricing module (#5335)

Browse Source 
* adjusted tsdoc of methods and types in pricing module

* finished adding tsdocs

* small fixes

* remove reference files

* added github action

* fix typo in outPath

* Update packages/types/src/shared-context.ts

Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>

* fix sharedContext description

* changed branch name of action

* added ignore for is_dynamic

* added private remark

---------

Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>
This commit is contained in:
Shahed Nasser
2023-10-10 13:23:54 +03:00
committed by GitHub
parent 4ebcd3af6a
commit 57bd38bb4b
22 changed files with 2774 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs-util/packages/typedoc-config/pricing.js Normal file
View File

@@ -0,0 +1,18 @@
/* eslint-disable @typescript-eslint/no-var-requires */
const modulesConfig = require("./modules")
module.exports = modulesConfig({
entryPointPath: "packages/types/src/pricing/service.ts",
outPath: "www/apps/docs/content/references/pricing",
moduleName: "Pricing Module Reference",
documentsToFormat: ["IPricingModuleService"],
additionalFormatting: {
reflectionDescription:
"This document provides a reference to the `IPricingModuleService` interface’s methods. This is the interface developers use to use the functionalities provided by the Pricing Module.",
},
extraOptions: {
frontmatterData: {
displayed_sidebar: "modules",
},
},
})

3
docs-util/packages/typedoc-config/tsconfig.json
View File

@@ -1,7 +1,4 @@
{
"extends": "../../tsconfig",
"compilerOptions": {
"outDir": "./dist"
},
"include": ["*.js"]
}

2
docs-util/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts
View File

@@ -34,6 +34,7 @@ import typeParameterListHelper from "./resources/helpers/type-parameter-list"
import typeParameterHelper from "./resources/helpers/type-parameter"
import parameterListHelper from "./resources/helpers/parameter-list"
import parameterHelper from "./resources/helpers/parameter"
import debugHelper from "./resources/helpers/debug"
import { MarkdownTheme } from "./theme"
const TEMPLATE_PATH = path.join(__dirname, "resources", "templates")
@@ -96,4 +97,5 @@ export function registerHelpers(theme: MarkdownTheme) {
typeParameterHelper(theme)
parameterListHelper()
parameterHelper(theme)
debugHelper()
}

8
docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts
View File

@@ -10,7 +10,8 @@ export default function (theme: MarkdownTheme) {
comment: Comment,
showSummary = true,
showTags = true,
commentLevel = 4
commentLevel = 4,
parent = null
) {
const { showCommentsAsHeader } = theme.getFormattingOptionsForLocation()
const md: string[] = []
@@ -27,7 +28,10 @@ export default function (theme: MarkdownTheme) {
const tags = filteredTags.map((tag) => {
return `${
showCommentsAsHeader
? `${Handlebars.helpers.titleLevel(commentLevel)} `
? `${Handlebars.helpers.titleLevel.call(
parent || comment,
commentLevel
)} `
: "**`"
}${camelToTitleCase(tag.tag.substring(1))}${
showCommentsAsHeader ? "" : "`**"

7
docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/debug.ts Normal file
View File

@@ -0,0 +1,7 @@
import * as Handlebars from "handlebars"
export default function () {
Handlebars.registerHelper("debug", function (...data: unknown[]) {
console.log(...data)
})
}

46
docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/signature-title.ts
View File

@@ -11,6 +11,14 @@ export default function (theme: MarkdownTheme) {
Handlebars.registerHelper(
"signatureTitle",
function (this: SignatureReflection, accessor?: string, standalone = true) {
const { sections, expandMembers = false } =
theme.getFormattingOptionsForLocation()
if (sections && sections.member_signature_title === false) {
// only show title if there are more than one signatures
if (!this.parent.signatures || this.parent.signatures?.length <= 1) {
return ""
}
}
const md: string[] = []
if (standalone && !theme.hideMembersSymbol) {
@@ -18,26 +26,52 @@ export default function (theme: MarkdownTheme) {
}
if (this.parent && this.parent.flags?.length > 0) {
md.push(this.parent.flags.map((flag) => `\`${flag}\``).join(" ") + " ")
md.push(
this.parent.flags
.map(
(flag) =>
`${!expandMembers ? "`" : ""}${flag}${
!expandMembers ? "`" : ""
}`
)
.join(" ") + " "
)
}
if (accessor) {
md.push(`\`${accessor}\` **${this.name}**`)
md.push(
`${!expandMembers ? "`" : ""}${accessor}${
!expandMembers ? "`" : ""
} ${expandMembers ? `${Handlebars.helpers.titleLevel(4)} ` : "**"}${
this.name
}${!expandMembers ? "**" : ""}`
)
} else if (this.name !== "__call" && this.name !== "__type") {
md.push(`**${this.name}**`)
md.push(
`${expandMembers ? `${Handlebars.helpers.titleLevel(4)} ` : "**"}${
this.name
}${!expandMembers ? "**" : ""}`
)
}
if (this.typeParameters) {
md.push(
`<${this.typeParameters
.map((typeParameter) => `\`${typeParameter.name}\``)
.map(
(typeParameter) =>
`${!expandMembers ? "`" : ""}${typeParameter.name}${
!expandMembers ? "`" : ""
}`
)
.join(", ")}\\>`
)
}
md.push(`(${getParameters(this.parameters)})`)
md.push(`(${getParameters(this.parameters, !expandMembers)})`)
if (this.type && !this.parent?.kindOf(ReflectionKind.Constructor)) {
md.push(`: ${Handlebars.helpers.type.call(this.type, "object")}`)
md.push(
`: ${Handlebars.helpers.type.call(this.type, "none", !expandMembers)}`
)
}
return md.join("") + (standalone ? "\n" : "")
}

29
docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/title-level.ts
View File

@@ -1,12 +1,31 @@
import { MarkdownTheme } from "../../theme"
import * as Handlebars from "handlebars"
import { SignatureReflection, Reflection } from "typedoc"
export default function (theme: MarkdownTheme) {
Handlebars.registerHelper("titleLevel", function (originalLevel = 3): string {
const { expandMembers } = theme.getFormattingOptionsForLocation()
Handlebars.registerHelper(
"titleLevel",
function (this: Reflection, originalLevel = 3): string {
const { expandMembers, sections } =
theme.getFormattingOptionsForLocation()
const level = expandMembers ? originalLevel - 1 : originalLevel
let isSignatureChild = false
if (
sections &&
sections.member_signature_title === false &&
(this instanceof SignatureReflection || this.variant === "signature")
) {
// only show title if there are more than one signatures
isSignatureChild =
this.parent !== undefined &&
"signatures" in this.parent &&
(this.parent.signatures as SignatureReflection[]).length > 1
}
return Array(level).fill("#").join("")
})
const level =
expandMembers && !isSignatureChild ? originalLevel - 1 : originalLevel
return Array(level).fill("#").join("")
}
)
}

20
docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/type.ts
View File

@@ -196,21 +196,27 @@ export function getReferenceType(model: ReferenceType, emphasis: boolean) {
if (model.reflection?.url) {
reflection.push(
`[${`\`${model.reflection.name}\``}](${Handlebars.helpers.relativeURL(
model.reflection.url
)})`
emphasis
? `[${`\`${model.reflection.name}\``}](${Handlebars.helpers.relativeURL(
model.reflection.url
)})`
: model.reflection.name
)
} else {
reflection.push(
model.externalUrl
? `[${`\`${model.name}\``}]( ${model.externalUrl} )`
: `\`${model.name}\``
emphasis
? model.externalUrl
? `[${`\`${model.name}\``}]( ${model.externalUrl} )`
: `\`${model.name}\``
: model.name
)
}
if (model.typeArguments && model.typeArguments.length > 0) {
reflection.push(
`<${model.typeArguments
.map((typeArgument) => Handlebars.helpers.type.call(typeArgument))
.map((typeArgument) =>
Handlebars.helpers.type.call(typeArgument, "none", emphasis)
)
.join(", ")}\\>`
)
}

14
docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.signature.hbs
View File

@@ -1,9 +1,5 @@
{{#if (sectionEnabled "member_signature_title")}}
{{{signatureTitle accessor}}}
{{/if}}
{{#if (sectionEnabled "member_signature_comment")}}
{{#with comment}}
@@ -38,11 +34,11 @@
{{#if showSources}}
{{titleLevel 4}} Parameters
{{{titleLevel 4}}} Parameters
{{else}}
{{titleLevel 5}} Parameters
{{{titleLevel 5}}} Parameters
{{/if}}
@@ -62,11 +58,11 @@
{{#if showSources}}
{{titleLevel 4}} Returns
{{{titleLevel 4}}} Returns
{{else}}
{{titleLevel 5}} Returns
{{{titleLevel 5}}} Returns
{{/if}}
@@ -128,7 +124,7 @@
{{#if hasVisibleComponent}}
{{{comments this false true 4}}}
{{{comments this false true 4 ..}}}
{{/if}}

14
docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts
View File

@@ -28,9 +28,9 @@ export default function reflectionFomatter(
const itemChildren: string[] = []
comments.summary.forEach((commentSummary) => {
if ("target" in commentSummary) {
const reflection = commentSummary.target as DeclarationReflection
if (reflection.children && level + 1 < MAX_LEVEL) {
reflection.children.forEach((childItem) => {
const targetReflection = commentSummary.target as DeclarationReflection
if (targetReflection.children && level + 1 <= MAX_LEVEL) {
targetReflection.children.forEach((childItem) => {
itemChildren.push(reflectionFomatter(childItem, level + 1))
})
}
@@ -39,9 +39,11 @@ export default function reflectionFomatter(
if (itemChildren.length) {
// TODO maybe we should check the type of the reflection and replace
// `properties` with the text that makes sense for the type.
item += ` It accepts the following properties:\n${itemChildren.join(
"\n"
)}`
item += ` ${
reflection.type?.type === "array"
? "Its items accept the following properties"
: "It accepts the following properties"
}:\n${itemChildren.join("\n")}`
}
}