fix(declarations): keep JSDoc @typedef/@callback comments with their type

[Eugene Kalinin (ekalinin)]

Fixes #63958

A JSDoc @typedef/@callback preceded by another top-level declaration loses its comment to the next statement:

export function noop() {}

/**
 * @typedef {Object} Point
 * @property {number} x
 */

/** @param {Point} p */
export function dist(p) { return p.x; }

export declare function noop(): void;
export type Point = { x: number; };              // undocumented
/**
 * @typedef {Object} Point
 * @property {number} x
 */
/** @param {Point} p */
export declare function dist(p: Point): number;  // documented with Point's docs

`reparseUnhosted` gives the synthesized alias the range of the tag, a position inside the comment, so the printer's leading-comment scan starts past the `/**` and finds nothing. Nothing marks the comment as taken either, so the next statement's scan, which starts at the end of the previous statement, sweeps it up. Hence it only reproduces with a preceding declaration: when the `@typedef` is first in the file the following statement sits at position `0`, and the file-start detached-comment path prints the block and advances that scan past it, so the output happens to come out right.

`EmitContext` gains comment ownership: a claimed comment is emitted by its owner and skipped by anything else scanning across it, and the owner emits nothing else. The declaration transformer claims a comment for the first declaration reparsed out of it, but only when every tag in it reparses into a declaration of its own (`@typedef, @callback, @import, @overload`). A block mixing `@typedef` with `@param` documents the host too and is left alone.

The baseline churn is that comment moving in front of its alias. Nine files also gain comments that were dropped before: `typedefOnStatements` and friends hang typedefs off statements that get elided from the `.d.ts` (`;, debugger;, if (false) {}`), so there was nothing left to print them with.

Unlike 5.9 the alias is no longer hoisted to end of file, it keeps its source position, so both repros in the issue are the same misplaced comment.

[Copilot]

🟡 Changes recommended

Two moderate comment-ownership gaps remain for generic aliases and standalone @import declarations.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Introduces comment ownership so JSDoc @typedef and @callback documentation remains attached to generated declarations.

Changes:

• Adds ownership tracking and printer filtering for claimed comments.
• Claims eligible JSDoc comments during declaration transformation.
• Adds placement tests and updates affected baselines.

Review findings:

• Moderate (1 vote): transform.go:477 excludes @template from declaration-only blocks, leaving generic @typedef/@callback aliases separated from their documentation.
• Moderate (1 vote): transform.go:507 cannot claim standalone @import comments because reparsed imports lack JSDoc metadata; this path needs correction and standalone regression coverage.

File summaries

File	Description
tsc/testdata/tests/cases/conformance/jsdoc/declarations/jsDeclarationsTypedefCommentPlacement.ts	Adds comment-placement scenarios.
tsc/testdata/baselines/reference/tsbuild/javascriptProjectEmit/loads-js-based-projects-and-emits-them-correctly.js	Updates build output.
tsc/testdata/baselines/reference/conformance/typedefOnStatements.js	Preserves comments from elided statements.
tsc/testdata/baselines/reference/conformance/typedefOnSemicolonClassElement.js	Preserves a class-element typedef comment.
tsc/testdata/baselines/reference/conformance/typedefModuleExportsIndirect3.js	Repositions typedef comments.
tsc/testdata/baselines/reference/conformance/typedefModuleExportsIndirect2.js	Repositions typedef comments.
tsc/testdata/baselines/reference/conformance/typedefModuleExportsIndirect1.js	Repositions typedef comments.
tsc/testdata/baselines/reference/conformance/templateInsideCallback.js	Updates callback/type comment placement.
tsc/testdata/baselines/reference/conformance/recursiveTypeReferences2.js	Associates recursive-type comments.
tsc/testdata/baselines/reference/conformance/linkTagEmit1.js	Associates linked typedef comments.
tsc/testdata/baselines/reference/conformance/jsDeclarationsUniqueSymbolUsage.js	Repositions typedef documentation.
tsc/testdata/baselines/reference/conformance/jsDeclarationsTypedefPropertyAndExportAssignment.js	Associates exported type comments.
tsc/testdata/baselines/reference/conformance/jsDeclarationsTypedefDescriptionsPreserved.js	Preserves description placement.
tsc/testdata/baselines/reference/conformance/jsDeclarationsTypedefCommentPlacement.types	Adds the type baseline.
tsc/testdata/baselines/reference/conformance/jsDeclarationsTypedefCommentPlacement.symbols	Adds the symbol baseline.
tsc/testdata/baselines/reference/conformance/jsDeclarationsTypedefCommentPlacement.js	Adds the emit baseline.
tsc/testdata/baselines/reference/conformance/jsDeclarationsTypedefAndImportTypes.js	Updates import-related comment placement.
tsc/testdata/baselines/reference/conformance/jsDeclarationsTypeAliases.js	Updates type-alias comment placement.
tsc/testdata/baselines/reference/conformance/jsDeclarationsParameterTagReusesInputNodeInEmit1.js	Repositions callback/type comments.
tsc/testdata/baselines/reference/conformance/jsDeclarationsImportNamespacedType.js	Moves documentation into the generated namespace.
tsc/testdata/baselines/reference/conformance/jsDeclarationsImportAliasExposedWithinNamespaceCjs.js	Associates namespace alias comments.
tsc/testdata/baselines/reference/conformance/jsDeclarationsImportAliasExposedWithinNamespace.js	Associates namespace alias comments.
tsc/testdata/baselines/reference/conformance/jsDeclarationsFunctionPrototypeStatic(target=es2015).js	Repositions callback documentation.
tsc/testdata/baselines/reference/conformance/jsDeclarationsFunctionClassesCjsExportAssignment(target=es2015).js	Associates generated type comments.
tsc/testdata/baselines/reference/conformance/jsDeclarationsDefaultsErr(target=es2015).js	Repositions default alias comments.
tsc/testdata/baselines/reference/conformance/jsDeclarationsDefault(target=es2015).js	Repositions default alias comments.
tsc/testdata/baselines/reference/conformance/jsDeclarationsClassStatic(target=es2015).js	Associates options documentation.
tsc/testdata/baselines/reference/conformance/checkJsdocSatisfiesTag15.js	Repositions typedef documentation.
tsc/testdata/baselines/reference/conformance/callbackOnConstructor.js	Moves callback documentation to its alias.
tsc/testdata/baselines/reference/compiler/typedefHoisting.js	Associates hoisted typedef comments.
tsc/testdata/baselines/reference/compiler/reuseTypeAnnotationImportTypeInGlobalThisTypeArgument.js	Repositions typedef documentation.
tsc/testdata/baselines/reference/compiler/jsTypedefMergedWithModuleExportProperty.js	Associates merged typedef comments.
tsc/testdata/baselines/reference/compiler/jsdocNonIdentifierPropertiesAndParams.js	Repositions callback documentation.
tsc/testdata/baselines/reference/compiler/jsdocMultilineUnion.js	Associates a multiline typedef comment.
tsc/testdata/baselines/reference/compiler/jsDocCallbackExport2.js	Repositions exported callback documentation.
tsc/testdata/baselines/reference/compiler/jsDocCallbackExport1.js	Repositions callback documentation.
tsc/testdata/baselines/reference/compiler/jsDeclarationsInheritedTypes.js	Associates inherited-type documentation.
tsc/testdata/baselines/reference/compiler/jsDeclarationEmitExportAssignedFunctionWithExtraTypedefsMembers.js	Moves typedef documentation to the exported alias.
tsc/testdata/baselines/reference/compiler/jsDeclarationEmitDoesNotRenameImport.js	Associates options typedef documentation.
tsc/testdata/baselines/reference/compiler/exportAssignmentMerging6.js	Repositions merged typedef comments.
tsc/testdata/baselines/reference/compiler/exportAssignmentMerging5.js	Repositions merged typedef comments.
tsc/internal/transformers/declarations/transform.go	Claims JSDoc comments for reparsed declarations.
tsc/internal/printer/printer.go	Restricts claimed-comment emission to owners.
tsc/internal/printer/emitcontext.go	Tracks claimed-comment ownership.

Review details

• Files reviewed: 44/44 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

A critical diagnostic regression and three unresolved comment-ownership issues must be fixed.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

tsc/internal/transformers/declarations/transform.go:522

• For a block containing both @import and @typedef, the generated import appears first and wins the claim, so the typedef comment is still not attached to its type. The new imported.d.ts baseline places “Imports and defines in one comment” before import type { Point }, leaving Path with no JSDoc and therefore no type hover documentation. Prefer the typedef/callback declaration as owner when a block also generates imports, or attach the relevant documentation to each declared type.

		if loc, ok := tx.commentRangeOfJSDoc(jsdoc, file); ok {
			tx.EmitContext().ClaimComment(statement, jsdoc.Pos(), loc)

• Files reviewed: 55/55 changed files
• Comments generated: 3
• Review effort level: Balanced