microsoft / microsoft/TypeScript
"Overriding" JSDoc at re-exports mostly only results in propagation of added "@deprecated" JSDoc tag
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 111k
- Forks
- 14.3k
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 117
Description
Bug Report
🔎 Search Terms
JSDoc, @deprecated, override, re-export.
Related on Stack Overflow: How can I make VS Code recognize an overridden JSDoc for a re-export?.
🕗 Version & Regression Information
I tried this with TypeScript 5.0.4 and 4.6.4. I tried 4.6.4 because I noticed that https://github.com/microsoft/TypeScript/pull/47293 happened just a bit before the release of 4.6. I witnessed the same behaviour for both versions I tried. I have described that behaviour below.
💻 Code
exporter.js:
/**
* JSDoc from original export.
* A thing that is definitely not deprecated.
*/
export const thing = 123;
reexporter.js:
export {
/**
* JSDoc from re-export.
* A thing that is deprecated.
* @deprecated reasons.
*/
thing
} from "./exporter";
importer.js:
// ✅ means expected behaviour
// ❌ means unexpected behaviour
import {
thing // ✅ not crossed out. ✅ hover info: "JSDoc from original export. A thing that is definitely not deprecated."
as originalThing // ✅ not crossed out. ✅ hover info: "JSDoc from original export. A thing that is definitely not deprecated."
} from "./exporter"
import {
thing // ✅ crossed out. ✅ hover info: "JSDoc from re-export. A thing that is deprecated. @deprecated — reasons." off. even this comment is crossed out.
as reexportedThing // ✅ crossed out. ❌ hover info: "JSDoc from original export. A thing that is definitely not deprecated."
} from "./reexporter";
reexportedThing(); // ✅ crossed out. ❌ hover info: "JSDoc from original export. A thing that is definitely not deprecated."
import {
thing // ✅ crossed out. ❌ hover info: "JSDoc from original export. A thing that is definitely not deprecated."
} from "./reexporter"
thing(); // ✅ crossed out. ❌ hover info: "JSDoc from original export. A thing that is definitely not deprecated."
🙁 Actual behavior
see the above code.
🙂 Expected behavior
see the above code. Everywhere with a "❌", I expected to see the overridden JSDoc in the VS Code hover info backed by tsserver.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the exporter.js, reexporter.js, and importer.js reproduction and test it with TypeScript 5.0.4 or the nightly build through VS Code and tsserver. Trace how JSDoc on a re-export is propagated versus how the original symbol is resolved; done means hover information consistently shows the re-export JSDoc and applies its @deprecated behavior to the re-exported name.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, typescript, vscode
- Domain
- compilers, developer-experience
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100