Support for opting out of jsdoc @typedef exports

Suggestion

🔍 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
    
    }
}

[andrewbranch]

Agreed this is not ideal. Not sure how best to indicate that it shouldn’t be exported. Maybe another JSDoc tag on the comment:

/**
 * @typedef {import("./FileA.js").Num} Num
 * @local
 */

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

[jespertheend]

I suppose this might be a duplicate of #22160 At least that would solve the same issue.