🔍 Search Terms

experimental jsdoc tag

✅ Viability Checklist

• 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 isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

I would like to mark some new APIs as "experimental" with an @experimental JSDoc tag, and have people's IDE's show a visual hint (like how @deprecated styles text with strike-through)

📃 Motivating Example

There's no way (unless I missed it) to introduce an experimental feature and to have that reflected in IDEs like @deprecated does. Example:

/**
 * @experimental Not ready for production. This feature is slated to land in the next minor. Early feedback welcome!  
 */
export function doSomethingNewAndCool() {
  // ...
}

and then IDEs would highlight this in a certain way in the code, for example like how @deprecated styles text with a strike through.

/**
 * @deprecated Not ready for production. This feature is slated to land in the next minor and be un-deprecated. Early feedback welcome!  
 */
export function doSomethingNewAndCool() {
  // ...
}

💻 Use Cases

See motivating example.

For now, a workaround is to use @deprecated, then clearly denote that the feature will be un-deprecated in a following release, but some people might misinterpret that or not read the whole message: