Repository navigation
"Overriding" JSDoc at re-exports mostly only results in propagation of added "@deprecated" JSDoc tag #53960
Description
Bug Report
🔎 Search Terms
JSDoc, Daniel Edeling (@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 #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.
Reacted by Matt Robinson and François Best
Activity
RyanCavanaugh commentedon Apr 25, 2023
Can you include a full example please? The contents of
exporterandreexporteraren't 100% apparent from this example.starball5 commentedon Apr 25, 2023
*facepalm. I made them and forgot to paste them. See edited comment.
emqi commentedon Apr 14, 2024
Since I've just recently run into this issue, I've prepared simple StackBlitz examples replicating it - one with TypeScript and another one with JavaScript.
Both examples are pretty much identical, first I create a simple variable with a JSDoc comment
Which I then export using the barrel file:
Then under the
re-exportI'm simply re-exporting it with additional deprecation tag & comment explaining the deprecation reason:In the root index file I import both original export and re-export. Here you can see the behavior described by the starball (@starball5).
Re-exports are striken through as expected:
However as you hover over the variable from
re-exportit mentions the deprecation but there's no sign of the additional comment included in the barrel file:Interestingly if one imports the variable using the import alias and hover over the original name, it's the only case where both comments are displayed:
But if you hover over the alias, it's once again missing:
I'd honestly expect tsserver to display both comments like in my 3rd screenshot under every circumstance. I quite often need to handle code changes in a backward compatible way and this "re-export with deprecation comment" pattern is my way to go when it comes to moving some code between entry points. It's just recently that I realized my deprecation reason is not displayed to the other devs which is quite disappointing.