Override JSDoc for re-exported types / enum / classes / interfaces

[plohoj]

Suggestion

🔍 Search Terms

• Override JSDoc
• JSDoc for re-export

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

Add the ability to define / override documentation(JSDoc) for re-exported types / enum / classes / interfaces, etc.

📃 Motivating Example

In the case when the library developer decided to change the name of the type / enum / class / interface, etc., it would be useful to have two copies of the declaration with different names and the old name would be marked as Daniel Edeling (@deprecated).
This refactoring practice is adopted for class methods, when a new method is created and the body of the old method is transferred into it, and a call to the new method is placed in the old method. The old method is then marked as Daniel Edeling (@deprecated) so that the library user has time to replace the name of the called method.

💻 Use Cases

An example of overriding JSDoc to mark a enum / interface as deprecated

// file: core/newFeature.ts
/** Some enum description **/
export enum NewFeatureEnum {
 // ...
}
/** Some interface description **/
export enum INewFeature<T extends NewFeatureEnum> {
 // ...
}

// file: index.ts
export {
 NewFeatureEnum,
 /** @deprecated use NewFeatureEnum */
 NewFeatureEnum as OldFeatureEnum,
 INewFeature,
 /** @deprecated use INewFeature */
 INewFeature as IOldFeature,
 // ...
} from 'core/newFeature';

At the moment, the JSDoc comment added to the re-export construct will not affect the final result in any way

[starball5]

Is it supposed to be the case that imports of the re-export don't show the overridden JSDoc, but only show the original export's JSDoc with any additional @deprecated tag from the re-export? Note that the site of the re-export itself does show the overridden JSDoc.

[starball5]

Related question on Stack Overflow: How can I make VS Code recognize an overridden JSDoc for a re-export?

[sandersn]

starball (@starball5) it would be better to open a new bug for this (and it does sound buggy).

[starball5]

starball (@starball5) it would be better to open a new bug for this (and it does sound buggy).

Done: #53960