Show every JSDoc comment on an alias chain in hover and completions

[patrick kettner (patrickkettner)]

Fixes #64655

Analysis

// @filename: lib.ts
/** Doc on impl */
export function foo() {}

// @filename: main.ts
import * as lib from "./lib.js";
/** Doc on export import alias */
export import bar = lib.foo

// @filename: use.ts
import { /** Doc on import alias */ bar } from "./main.js"
bar()  // Doc on impl
bar    // Doc on impl

getDocumentationForSymbol shows one declaration's comment and which one depends on the reference site. The import x = a.x comment is attached by the parser and never read, and a comment on an import specifier is never attached at all (6.0 does not attach one either).

Fix

Every alias on the chain contributes the JSDoc on its own declaration, outermost first, and the implementation contributes what it did before (the resolved signature, root symbols, the picked declaration, the alias target). Descriptions are joined with a newline, then the tag sections follow in the same order, exact duplicates dropped. The reference site only decides which implementation declaration is picked, so bar and bar() show the same lines.

The parser attaches JSDoc to import specifiers the way it does to export specifiers, including the same-line form inside the braces. import { /** @deprecated */ x } now deprecates x, so checkAliasSymbol skips the suggestion a specifier would raise on itself.

quickInfoAlias and quickInfoAliasVS change because the specifier comment in that test (Doc 3) now shows ahead of the target's.

Copilot Checklist

I successfully ran the applicable command at the end of my session, and it completed without error:

• npx hereby validate
• npx hereby validate --api (for TypeScript API changes)

I used Claude Code to write the patch and the tests, and I have read and reviewed both.

[Copilot]

Copilot review overview

🟡 Changes recommended

Merged alias symbols may read JSDoc from a non-alias declaration.

Review effort: Balanced
Findings: 1

Open (1)

• Select the actual alias declaration instead of Declarations[0] · New

What changed in this PR

Restores alias-authored JSDoc in hover and completion details.

Changes:

• Adds alias declaration documentation lookup with call-site precedence.
• Adds fourslash coverage and hover baseline.

File	Description
tsc/​internal/​ls/​hover.go	Resolves documentation from alias declarations.
tsc/​internal/​fourslash/​tests/​hoverImportEqualsAliasJSDoc_test.go	Tests hover and completions.
tsc/​testdata/​baselines/​reference/​fourslash/​quickInfo/​hoverImportEqualsAliasJSDoc.baseline	Records expected hover output.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[patrick kettner (patrickkettner)]

@microsoft-github-policy-service agree

[Wesley Wigham (weswigham)]

Honestly, I think the whole a.fn and a.fn() yielding different documentation comment sources thing is weird. It's not our TS 6.0 behavior - AFAIK we just used the implementation docs everywhere.

Take this example:

// @filename: src/lib.ts
/**
 * Doc on impl
 */
export function foo() {}

// @filename: src/main.ts
import * as lib from "./lib.js";

/**
 * Doc on export import alias
 */
export import bar = lib.foo

// @filename: src/use.ts
import {
    /**
     * Doc on import alias
     */
    bar
} from "./main.js"

bar()
bar

It's subjective, but IMHO, if we wanna improve things, quickinfo documentation on both bar refs (the call and the bare ref) should be

Doc on import alias
Doc on export import alias
Doc on impl

anything only looking at a single declaration in an alias chain is gonna potentially miss something otherwise.

[patrick kettner (patrickkettner)]

yeah, that would be my preference too. I kept this at 6.0 parity to keep it small (on 6.0.3 the bare ref shows the alias comment and the call shows the impl's, same with import * as m and m.bar on your example), but showing the whole chain on both refs is the version id actually want. happy to widen this PR to do that if youd prefer?

[Wesley Wigham (weswigham)]

Yeah, if we're gonna change anything here, I'd wanna make it consistent across reference site kinds and include all the docs possible, for sure.

[patrick kettner (patrickkettner)]

what about tags? like if the alias and the impl have the same description but the tags are different

/** Does the thing.
 * @since 2.0 */
export function doThing(): void

/** Does the thing.
 * @since 1.0 */
export import doThing = lib.doThing

should hover show both @since lines, or does the alias win for tags it sets? I read "all the docs possible" as both, but wanted to check before building it that way.

[Wesley Wigham (weswigham)]

I read "all the docs possible" as both, but wanted to check before building it that way.

The only "semantic" tags are the type-providing ones, and those only work on the implementation anyway. Any other tag is basically just docs anyway, so I'd imagine they're shown inline.