Microsoft/TypeScript

Mapped keys do not preserve JSDoc documentation

Open

#50,715 opened on Sep 11, 2022

View on GitHub
 (16 comments) (37 reactions) (0 assignees)TypeScript (48,455 stars) (6,726 forks)batch import
Experience EnhancementHelp WantedSuggestion

Description

Bug Report

🔎 Search Terms

mapping types with docs; preserve docs on mapped types

🕗 Version & Regression Information

  • This is the behavior in every version I tried, and I reviewed the FAQ for entries about this

⏯ Playground Link

Playground link with relevant code

💻 Code

All relevant code can be found in the example links.

Why doesn't TypeScript/Vscode preserve documentation / JSDoc for mapped types?

Using this example that appears in the TypeScript documentation itself, which you can quickly reproduce in Vscode locally, you can see the problem.

It is expected that when remapping the keys of a type object, the documentation would remain what was defined in the original/previous keys, but this does not happen. Nothing is preserved.

This sucks in the development context, because it requires us to have to repeat the documentation of a property or method, for example, in multiple places, thousands of times. This can lead to consistency issues as the code grows and loses the point of automating things.

Another directly related problem is in Index Signatures. Even if documentation is added, nothing is preserved. This also includes Union Types. An example can be seen here.

🙁 Actual behavior

JSDoc documentation is not preserved in mapped keys.

🙂 Expected behavior

Mapped keys must have JSDoc documentation of their original/previous names.

Contributor guide

Tech stack
typescript
Domain
developer experiencedocumentation
Issue type
bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
4
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
TypeScriptMapped typesJSDoc
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
35
Research direction
Begin by examining how mapped types are processed in the TypeScript compiler, specifically in src/compiler/checker.ts. Look for functions like checkMappedType or getPropertiesOfType that handle property generation for mapped types. Investigate whether JSDoc annotations are attached to the original property symbols and if they are copied to the resulting mapped type properties. The playground link in the issue provides a concrete example. Check existing logic for preserving other property attributes (like flags) to see if JSDoc is missing. There are no linked pull requests, so this is a new fix. Consult comments in the issue for any additional insights from maintainers.