Writing Tsdocs Agent Skill

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