microsoft / microsoft/TypeScript
JSDoc present in mapped types is not output in generated type literals in declaration files
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 111k
- Forks
- 14.3k
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 132
Description
### 🔎 Search Terms
generated declaration files mapped types jsdoc missing
### 🕗 Version & Regression Information
- This is the behavior in every version I tried, and I reviewed the FAQ for entries about: I don't believe the FAQ contains anything applicable to this.
### ⏯ Playground Link
https://www.typescriptlang.org/play/?#code/JYWwDg9gTgLgBALzgMyhEcDkCIBNMBQBApgB6SxwDGEAdgM7z1UAWxIAhnALyIB0EAEYArYlRgAKAN4E4cAPQAqRbLmK4AZXTE4tYFR0ApDQBEIVVXEXzVyCBABc-RlGC0A5hICUAGgIBfLyIaBnhSHjhmNk4+MA4oemJpO0csDkxAvhTLOVy8-ILCuXl5OAA9CrgWCAA3YlcPFHtI6oB3ejgYNjhjMwsgA
### 💻 Code
This is not the same issue as https://github.com/microsoft/typescript/issues/50715, that issue is about type mappings that lose the JSDoc period.
I'm talking about what happens in the `.d.ts` file generated for source like this where JSDoc does survive type mapping:
```ts
import z from 'zod'
export const schema = z.object({
/**
* Some nice JSDoc
*/
foo: z.string(),
})
const x = schema.parse({foo: 'a'}).foo
// ^^^ hovering foo shows the JSDoc
```
### 🙁 Actual behavior
Hovering the parsed `.foo` in the source file displays the JSDoc for the property:
But if I consume the same type from the generated `.d.ts` file, I don't get the JSDoc:
### 🙂 Expected behavior
We should get the same JSDoc when consuming the `.d.ts` file as we do when consuming the source file it was generated from.
### Additional information about the issue
If we look at the generated `.d.ts` the problem is clear: `tsc` isn't outputting JSDoc it has in memory for mapped type properties to the generated type literals:
```ts
import z from 'zod';
export declare const schema: z.ZodObject<{
/**
* Some nice JSDoc
*/
foo: z.ZodString;
}, "strip", z.ZodTypeAny, {
foo: string; // (tsc should have copied the JSDoc to this property)
}, {
foo: string; // (and to this one)
}>;
//# sourceMappingURL=Schema.d.ts.map
```
It would at least be nice to have an option to output these copies of JSDoc, even though it would make the declaration file bigger.
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
Reproduce the mapped-type declaration output using the linked TypeScript Playground and compare the generated .d.ts with the source JSDoc. Trace the declaration emitter and mapped-type property handling, then add coverage showing that generated type literals preserve the JSDoc and verify the expected declarations.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- compilers
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100