Skip to content

feat: Add descriptions and deprecations to SDK - #947

Merged
razor-x merged 7 commits into
mainfrom
codex/generate-tsdoc-or-jsdoc-annotations
Jul 28, 2026
Merged

feat: Add descriptions and deprecations to SDK#947
razor-x merged 7 commits into
mainfrom
codex/generate-tsdoc-or-jsdoc-annotations

Conversation

@razor-x

@razor-x razor-x commented Jul 28, 2026

Copy link
Copy Markdown
Member

Motivation

  • Surface blueprint descriptions and deprecation metadata in the generated TypeScript so IDE hovers and docs include human-readable API documentation.
  • Provide a safe formatter for blueprint documentation that can be emitted from Handlebars templates without breaking generated comment blocks.
  • Ensure generated route and resource types contain TSDoc comments for parameters, properties, enum values, and endpoint methods to improve developer experience.

Description

  • Add a safe TSDoc formatter doc to the codegen helpers at codegen/lib/handlebars-helpers.ts that escapes */, emits @deprecated when appropriate, and returns a TSDoc comment block. (doc, escapeComment)
  • Extend the route layout context to carry endpoint documentation metadata (description, isDeprecated, deprecationMessage) in codegen/lib/layouts/route.ts and use it when rendering endpoints.
  • Update multiple Handlebars templates to emit documentation for generated artifacts: endpoint methods, request parameters, resource types, resource properties, list/enum items, and enum values (templates under codegen/layouts/partials/* and codegen/layouts/*).
  • Regenerate Seam Connect sources so the generated TypeScript under src/lib/seam/connect/* now includes the new TSDoc comments for resource types, routes, request/response types, and many route implementations.

Testing

  • Ran npm_config_force=true npm run generate to run the codegen and regenerate sources (used --force due to dev engine constraints), and the generation completed successfully.
  • Ran npm_config_force=true npm run typecheck (tsc) and the TypeScript type check completed successfully under the forced install.
  • Built documentation with npm_config_force=true npm run docs:build; Typedoc completed and produced ./docs with pre-existing warnings about some cross-references (non-fatal).
  • Attempted npm_config_force=true npm test; automated tests could not fully run in this environment because the installed Emittery relies on iterator helpers not present in the runtime Node 20 used here (project requires Node >= 22.11), so tests did not complete in this environment; git diff --check produced no whitespace/comment issues.

Codex Task

@razor-x
razor-x force-pushed the codex/generate-tsdoc-or-jsdoc-annotations branch from 9a83ddd to a3a82f9 Compare July 28, 2026 03:46
@razor-x razor-x changed the title Add blueprint descriptions to generated TypeScript documentation feat: Add descriptions and deprecations to SDK Jul 28, 2026
@razor-x
razor-x merged commit df584ac into main Jul 28, 2026
16 checks passed
@razor-x
razor-x deleted the codex/generate-tsdoc-or-jsdoc-annotations branch July 28, 2026 15:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants