add @stability tag

[chharvey]

I think It would be great to have a tag marking the stability level of a module or its parts.

We do have @version but that is really meant or numbers, and I can only imagine using it for an entire module. Version numbers (usually) follow SemVer and have an objective meaning in terms of compatibility.

Contrarily, stability is more of a subjective description, but does provide meaningful information (perhaps author-defined) to users about how stable a component is. @deprecated is slightly helpful, but not nearly as flexible. In a module having one version number, there may be many components, each with its own stability level, and each could ascend or descend as the project grows (as opposed to version numbers, which strictly ascend).

Some good examples of stability levels can be found in Node.js’s API documentation.

A new @stability tag would allow authors to define their own stability levels ("obsolete", "deprecated", "experimental", "locked", "frozen", etc.) and explicitly describe the meaning of each.

[cancerberoSgx]

Notice that you could add those tags and they will be exported to the output AST if you include :

	"tags": {
		"allowUnknownTags": true
	},

in the config. What you want is that the default theme to show this info right ? I guess the idea for this custom things is that you fork the theme and do it in your custom theme...

[Acanguven]

I think we still need this basic feature. Unknown tags are not covering the requirement completely.

[thw0rted]

I've seen some places that made up their own @experiemental tag; I'm not sure if other parsers are doing anything special with it or not. I got here because I'm adding type definitions (in Typescript, but with additional information captured via JSDoc) for experimental browser features -- the TS team says that they won't put anything in the default lib files if it's only "proposed", even if several major browsers support it -- and I want to make sure that any use of the feature is guarded behind feature detection.

[ekwoka]

This would be great. I'm a bit surprised this doesn't exist.

[pkvinhu]

agree, our team would love an @experimental tag. it'd be nice if we could use jsdocs to communicate that something is in beta and it would encourage people to eagerly provide feedback