Support for opting out of jsdoc @typedef exports
See original GitHub issueSuggestion
🔍 Search Terms
jsdoc typedef export #43207 #23692
✅ 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
Currently when using /** @typedef {Number} Num */
the type Num
is automatically exported when the comment is in the root scope. I’d like to prevent this from happening.
📃 Motivating Example 💻 Use Cases
My problem:
FileA.js
declares /** @typedef {Number} Num */
FileB.js
uses this type a bunch of times, so instead of using /** @type {import("./FileA.js").Num} */
everywhere, it declares it once at the top of the file: /** @typedef {import("./FileA.js").Num} Num */
and then uses Num
everywhere in the file.
The problem is that doing it this way in all files creates a lot of exports of the same type and it’s not always clear which one is the original export. This creates a rather big list with Intellisense:
A woraround is to wrap the type in parentheses, this causes the typedef to be limited to that scope, but this is not always feasible. I.e:
{
/** @typedef {import("./FileA.js").Num} Num */
/**
* @param {Num}
*/
export default function foo(x) { // <-- error, export needs to be top level
}
}
Issue Analytics
- State:
- Created 2 years ago
- Reactions:16
- Comments:6 (3 by maintainers)
Agreed this is not ideal. Not sure how best to indicate that it shouldn’t be exported. Maybe another JSDoc tag on the comment:
@local
isn’t something listed on https://jsdoc.app.@private
or something? We kind of try not to just make up JSDoc things willy nilly, but this feels like a problem we made so the solution will probably have to be made by us too. /cc @sandersn?I suppose this might be a duplicate of #22160 At least that would solve the same issue.