microsoft / microsoft/TypeScript

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

Open
#53,960 3 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Needs More Info
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.