`@experimental` JSDoc tag, with strikethrough style (or similar) like `@deprecated` JSDoc tag

[trusktr]

🔍 Search Terms

experimental jsdoc tag

✅ Viability Checklist

• [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 isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• [X] 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:

[danhorvath]

We use the @experimental tag to mark certain components and features in our internal design system. Currently we use a custom linter rule to help our consumers notice when they use an experimental component/feature, but we would very much appreciate an explicit visual hint in the IDE

[nikeee]

If this is up for grabs, I'd implement that

[lppedd]

This is extremely useful, especially when the codebase is in prototyping phase.
Code doesn't evolve following carefully drafted specifications, so marking certain code paths as "risky" is a must have.

[tristonarmstrong]

I've encountered quite a few people/library makers wishing something like this existed. I also ended up looking for this tag myself, with nothing to be found. I looked to see if there was more traffic on this, and it appears some others also request this. I imagine most people just find some hacky workaround like using deprecated or just writing a comment.

I decided i would impliment this yesterday and the day before, but i doubt this will ever get merged. The contribution guidelines require an existing backlog PR already created. Tests for it not created yet, and im not sure about the strikethrough thing, but it does what we needed for now

https://github.com/tristonarmstrong/TypeScript

[Netail]

I don't think strikethrough would be the right approach, maybe something else...?

[tristonarmstrong]

I don't think strikethrough would be the right approach, maybe something else...?

vscode is doing that. That's why i included the screenshot from another editor. Tho it is because experimental and deprecated are being setup the same way. If we want a new way to display it, then we'd need to wait for editors to support some new thing i think

[harrisonhoward]

I don't think strikethrough would be the right approach, maybe something else...?

I was thinking underline?