microsoft / microsoft/TypeScript

JSDoc comments emitted a second time even after commenrs on type are emitted

Open
#62,453 0 comments 3 reactions 0 assignees View on GitHub
Bug Domain: Comment Emit Help Wanted
Dominant language
Go
Stars
111k
Forks
14.3k
Avg merge
2d 4h
Merged PRs (30d)
132

Description

### 🔎 Search Terms

JSDoc, emit, comments

### 🕗 Version & Regression Information

v5.9.2
- I was unable to test this on prior versions because I was not using TS.

### ⏯ Playground Link

_No response_

### 💻 Code

```js
/**
* The template passed to generate messages
*
* @callback Template
* @param {...*} args - Arguments to the template
* @returns {any} The generated message
*/

/**
* The arguments sent with notify become the input parameters for the template.
*
* @typedef {Parameters} TemplateParams
*/

/**
* The return value from the template is yielded as the message generated from
* the subscription. The following types help define this relationship.
*
* @typedef {ReturnType} Message
*/
```

### 🙁 Actual behavior

Typescript, when emitting from JSDoc, seems to want to emit the same comments for a type declaration twice:
+ once for the export (good) and
+ once just copying over the JSDoc comment (bad).

```ts
/**
* The template passed to generate messages
*/
export type Template = (...args: any[]) => any;
/**
* The arguments sent with notify become the input parameters for the template.
*/
export type TemplateParams = Parameters;
/**
* The return value from the template is yielded as the message generated from
* the subscription. The following types help define this relationship.
*/
export type Message = ReturnType;
/**
* The template passed to generate messages
*
* @callback Template
* @param {...*} args Arguments to the template
* @returns {any} The generated message
*/
/**
* The arguments sent with notify become the input parameters for the template.
*
* @typedef {Parameters} TemplateParams
*/
/**
* The return value from the template is yielded as the message generated from
* the subscription. The following types help define this relationship.
*
* @typedef {ReturnType} Message
*/
```

### 🙂 Expected behavior

It should emit the comment just once:

```ts
/**
* The template passed to generate messages
*/
export type Template = (...args: any[]) => any;
/**
* The arguments sent with notify become the input parameters for the template.
*/
export type TemplateParams = Parameters;
/**
* The return value from the template is yielded as the message generated from
* the subscription. The following types help define this relationship.
*/
export type Message = ReturnType;
```

or even better (See #61664)

```ts
/**
* The template passed to generate messages
*
* @param Arguments to the template
* @returns The generated message
*/
export type Template = (...args: any[]) => any;
/**
* The arguments sent with notify become the input parameters for the template.
*/
export type TemplateParams = Parameters;
/**
* The return value from the template is yielded as the message generated from
* the subscription. The following types help define this relationship.
*/
export type Message = ReturnType;
```

### Additional information about the issue

_No response_

Contributor guide

Open the contributing guide

Research direction

Reproduce the report with TypeScript v5.9.2 using the supplied JavaScript/JSDoc snippet, then trace the declaration-emission path responsible for the duplicate comments. Add a regression test for the emitted declarations and verify that each comment appears once, while checking the related #61664 behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
compilers
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.