writing-tsdocs

在 Medusa 程式碼庫中為 TypeScript 原始檔新增和更新 TypeDoc (TSDoc) 註解。涵蓋 HTTP 類型、API 路由、UI 元件、資料模型、服務…

npx skills add https://github.com/medusajs/medusa --skill writing-tsdocs

Writing Medusa TSDocs

Adds TypeDoc (TSDoc) comments to Medusa TypeScript source files. Follows TypeDoc conventions and uses custom tags defined in www/utils/packages/typedoc-config/tsdoc.json.

Constraints

CRITICAL: Violating these produces incorrect or broken documentation.

Never document unexported items — only exported interfaces, types, functions, classes
Never add TSDocs to test files — skip *.spec.ts, *.test.ts, __tests__/
Never fabricate @since version numbers — only use the version passed in the prompt
Never remove or modify existing TSDocs — only add where missing
Never modify logic — only add/edit comment blocks
For Medusa-specific custom tags, only use those defined in tsdoc.json: @expandable, @featureFlag, @since, @apiIgnore, @schema, @tags, @version, @keep, @customNamespace, @namespaceMember

Load Reference Files When Needed

Load the reference file for the file type you're documenting before writing any TSDocs.

Path pattern	Load
`packages/core/types/src/http/`	`reference/http-types.md`
`packages/medusa/src/api/admin/` or `/store/`	`reference/api-routes.md`
`packages/design-system/ui/src/components/`	`reference/ui-components.md`
`packages/modules/*/src/models/`	`reference/data-models.md`
`packages/core/types/src/` (non-http)	`reference/service-interfaces.md`
`packages/core/js-sdk/src/`	`reference/service-interfaces.md`
`packages/core/utils/src/` (abstract providers)	`reference/service-interfaces.md`
`packages/core/workflows-sdk/src/utils/composer/`	`reference/service-interfaces.md`
`packages/core/core-flows/src/` (workflows)	`reference/workflows-steps.md`
`packages/core/core-flows/src/` (steps)	`reference/workflows-steps.md`
`packages/core/utils/src/core-flows/events.ts`	`reference/events.md`

Quick Reference

TSDoc block format

/**
 * Brief description.
 */
export interface Foo {
  /**
   * The foo's ID.
   */
  id: string
}

Per-type depth guide

File type	What to document	Key Medusa tags
HTTP types	Every exported interface/type + all properties	`@expandable` on nested objects
API routes	Exported handlers only (minimal)	`@featureFlag`, `@since`
UI components	Component + all props	Plain descriptions
Data models	Model + each property	`@since` on new items
Service interfaces	Every method in full	`@param`, `@returns`, `@example`
JS SDK	Every public method	`@param`, `@returns`, `@example`, `@tags`
Providers	Class + every abstract method	`@param`, `@returns`, `@example`
Workflow SDK	Every exported function	`@param`, `@returns`, `@example`
core-flows workflows	Workflow export + hooks	`@summary`, `@featureFlag`, `@since`
core-flows steps	Step export + input type	`@featureFlag`, `@since`, `@example`
Events	Every event constant	`@eventPayload`, `@featureFlag`, `@since`

Medusa custom tags (from `www/utils/packages/typedoc-config/tsdoc.json`)

Tag	Kind	Use when
`@featureFlag <name>`	block	Export requires a feature flag to be enabled
`@expandable`	modifier	Nested object expandable in API queries
`@since <version>`	block	Export was added in this version (prompt-provided only)
`@apiIgnore`	modifier	Exclude from API docs output
`@tags <name>`	block	SDK categorization
`@schema`	block	Custom schema documentation
`@keep`	modifier	Preserve during doc generation
`@customNamespace`	block	Assign to custom doc namespace

Standard TypeDoc/JSDoc tags (@param, @returns, @example, @deprecated, @remarks, etc.) are always allowed.

Common Mistakes

Documenting unexported or private items
Using @since without a version being provided in the prompt
Writing property descriptions longer than 2 sentences
Adding @param/@returns to non-method exports (interfaces, types)
Documenting an id field without specifying what resource it belongs to

Reference Files

reference/http-types.md          - HTTP type interfaces: properties, @expandable
reference/api-routes.md          - API routes: @featureFlag, @since, minimal docs
reference/ui-components.md       - UI components: component + inline prop pattern
reference/data-models.md         - DML models: @since, property descriptions
reference/service-interfaces.md  - Methods, SDK, providers, workflow SDK: full JSDoc
reference/workflows-steps.md     - core-flows workflows and steps: @summary, hooks, @example
reference/events.md              - Event constants: @eventPayload, @featureFlag, @since