Description
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 @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 @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