remcohaszing commented 2 years ago

Suggestion

🔍 Search Terms

jsdoc internal jsdoc internal stripinternal

✅ Viability Checklist

My suggestion meets these guidelines:

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

⭐ Suggestion

Currently, if "stripInternal": true is set in the compiler options, the @internal JSDoc annotation can be used to prevent it from ending up in the generated type definitions.

When using types in JSDoc, a type can be defined using:

/**
 * @typedef {object} MyType
 * Description of `MyType`.
 */

It would be great of @internal could also be applied to types in JSDoc.

📃 Motivating Example

The @internal annotation now also works for types defined in JSDoc if the "stripInternal" option is enabled.

/**
 * @typedef {object} MyType
 * @internal
 */

💻 Use Cases

These typedefs are always exported, but often they are only defined to import a type. This means that packages often need to add a dependency on packages only for their types, even if the intention isn’t to re-export them.

/**
 * @typedef {import('my-package').MyType} MyType
 * @internal
 */

A lot of practical use cases exist in the unified ecosystem.

For example remark-rehype.

swingingtom commented 2 years ago

@remcohaszing Did you succeed to have it working?

remcohaszing commented 2 years ago

No. It’s a feature request. The feature doesn’t exist (yet).