"Overriding" JSDoc at re-exports mostly only results in propagation of added "@deprecated" JSDoc tag

[starball5]

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.

[RyanCavanaugh]

Can you include a full example please? The contents of exporter and reexporter aren't 100% apparent from this example.

[starball5]

Can you include a full example please? The contents of exporter and reexporter aren't 100% apparent from this example.

*facepalm. I made them and forgot to paste them. See edited comment.

[emqi]

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

// ./export/item/item.ts

/**
* Very important constant with a value of 12.
*/
export const IMPORTANT_CONST = 12;

Which I then export using the barrel file:

// ./export/index.ts

export { IMPORTANT_CONST } from './item/item.js';

Then under the re-export I'm simply re-exporting it with additional deprecation tag & comment explaining the deprecation reason:

export {
// re-export/index.ts

 /**
 * @deprecated This is deprecated re-export, It will be removed it in version 2.0.0
 *
 * Sadly you won't be able to see this message in your code :/
 */
 IMPORTANT_CONST,
} from 'node-starter/export';

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-export it 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.