[el-j (el-j)]

Fixes #65057

Implements canonical JSDoc block and tag emission, including parameter types and inline links. Adds printer tests for direct JSDoc printing and JSDoc attached to declarations.

Also adds synthetic leading/trailing comment support to the JS API's printNode/printFile, so JSDoc can be attached to synthesized nodes and printed without a source file:

• JS: addSyntheticLeadingComment/addSyntheticTrailingComment (and getters/setters) are exported from @typescript/typescript/ast; the encoder sends them as an optional comments field on printNode.
• Go: printNode applies them to an EmitContext, validating node indices and comment kinds. A new opt-in printer option, EmitSyntheticCommentsWithoutSourceFile, emits them when no source file is present; it is only enabled by printNode, so other printing paths are unchanged.
• Tests: Go printer and API tests, plus async/sync JS API tests.

Validation: npx hereby validate --api passed (974 API tests, 0 lint issues; requires Node 24).

AI disclosure: This PR was created with assistance from GitHub Copilot (Copilot SDK in VS Code). Automated validation passed; author review and Microsoft CLA agreement remain pending.

Note: My GitHub account lacks permission to assign issue #65057 to the Backlog milestone, so that required checklist item remains unchecked.

Related issues and PRs

Issues

• Native printer panics when printing JSDoc AST nodes #65057 — native printer panics on JSDoc nodes (fixed by this PR)
• [api] Add back missing: setEmitFlags and addSynthetic*Comment #64429 — [api] Add back missing: setEmitFlags and addSynthetic*Comment. The synthetic-comment half is covered here (addSyntheticLeadingComment/addSyntheticTrailingComment and their getters/setters). setEmitFlags/EmitFlags is not, and is tracked by Add support for setting emit flags and synthetic comments #64500, so this PR does not close it.
• [API] Printer attaches source comments to synthesized nodes because the node encoder sends pos -1 as 0 #64859 — printer attaches source comments to synthesized nodes because the encoder sends pos -1 as 0. Not changed here, but both touch the printNode/encoder path.
• EFNoLeadingComments suppresses synthesized leading comments in tsgo; Strada only suppresses source comments #64453 — EFNoLeadingComments suppresses synthesized leading comments. Not changed here, but relevant to how synthetic comments interact with emit flags.

Pull requests

• Add support for setting emit flags and synthetic comments #64500 — Add support for setting emit flags and synthetic comments (fixes [api] Add back missing: setEmitFlags and addSynthetic*Comment #64429). Overlaps with this PR in encoder.ts, proto.go/proto.generated.ts, session.go, decoder.go and the API tests. Whichever lands first, the other will need a rebase, and the synthetic-comment transport may be deduplicated.
• Preserve synthesized node ranges across API serialization #64903 — Preserve synthesized node ranges across API serialization (encoder.ts, decoder.go; related to [API] Printer attaches source comments to synthesized nodes because the node encoder sends pos -1 as 0 #64859).
• Fix synthesized comment emission with comment flags #64488 — Fix synthesized comment emission with comment flags (printer.go; related to EFNoLeadingComments suppresses synthesized leading comments in tsgo; Strada only suppresses source comments #64453).
• Preserve single-line emit hints for nodes returned by the API #65062 — Preserve single-line emit hints for nodes returned by the API (session.go; fixes typescript/sync: tuples and type literals from checker.typeToTypeNode print multi-line (SingleLine flag lost) #64991).

[Copilot]

🟡 Changes recommended

Unresolved JSDoc printer defects cause panics and invalid or lossy output, including broken signature handling, malformed imports, and dropped template parameter defaults and modifiers.

9 open issues

• Add precedence support for the new JSDoc node kinds · New
• Emit JSDoc signatures without standard parameter and return casts · New
• Preserve template modifiers and default types · New
• Emit callback and overload child tags instead of function annotations · New
• Emit JSDoc imports with bindings and a from clause · New
• Preserve optionality and use the final segment of nested property names · New
• Unwrap JSDoc type expressions in record properties · New
• Emit dotted typedef names without treating them as namespaces · New
• Preserve indentation in JSDoc comments and tag content · New

What changed in this PR

This PR adds JSDoc AST emission to the native TypeScript printer, addressing the unimplemented printing path reported in #65057.

Changes:

• Adds emission for JSDoc blocks, tags, type expressions, names, and inline links.
• Introduces helpers for comment formatting and JSDoc type literals.
• Adds printer tests for direct JSDoc emission and preservation of comments attached to declarations.

File	Description
tsc/​internal/​printer/​printer.go	Implements JSDoc dispatch, formatting, and tag emission.
tsc/​internal/​printer/​printer_test.go	Adds coverage for JSDoc blocks, parameter types, links, and attached comments.

_{Review effort: Balanced}

[el-j (el-j)]

@microsoft-github-policy-service agree

[el-j (el-j)]

I have addressed all nine review threads and pushed the update to release-7.1; npx hereby validate and the focused printer tests pass locally. The branch protection rules show one approving review and a required required status check in addition to the passing CLA check. The upstream CI and CodeQL runs for this fork PR are currently action_required, so they need approval from someone with repository permissions. Could a maintainer approve the pending workflows and review the updated PR?

[Copilot]

🟡 Changes recommended

The JSDoc printer still drops documentation and qualified-name components, emits invalid optional-property syntax, and orders generic template tags in a way the parser rejects.

5 open issues

• Preserve continuation lines when a tag comment starts with a newline · New
• Preserve child-tag documentation when emitting typedefs and parameters · New
• Emit optional JSDoc properties with optional types correctly · New
• Emit template tags before callback and overload tags · New
• Preserve the final component of namespaced JSDoc declarations · New

9 resolved since last review

• Emit dotted typedef names without treating them as namespaces
• Unwrap JSDoc type expressions in record properties
• Preserve optionality and use the final segment of nested property names
• Emit JSDoc imports with bindings and a from clause
• Emit callback and overload child tags instead of function annotations
• Preserve template modifiers and default types
• Emit JSDoc signatures without standard parameter and return casts
• Add precedence support for the new JSDoc node kinds
• Preserve indentation in JSDoc comments and tag content

_{Review effort: Balanced}

[el-j (el-j)]

Follow-up: I addressed the five new review comments in 4c2c6fa, including preserving nested property comments and links, optional JSDoc properties, generic callback/overload tag ordering, and namespaced typedef names. All 14 review threads are resolved, and go -C ./tsc test ./internal/printer plus npx hereby validate pass locally. The updated SHA has no upstream CI runs/statuses yet, and the PR still needs an approving review. Could a maintainer re-review and enable the required CI checks?