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

Nobody has claimed this yet.

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

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

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.