Attribute Macro stable

#[stable]

Mark an API as stable.

You can apply this attribute to an item in your public API that you would like to expose to users, and are ready to make a stability guarantee for. This is useful when you have finished testing and designing an API and are ready to commit to its design and stability.

This attribute does the following things to annotated items:

• Appends a “Stability” section to the item’s documentation that notes that the item is stable and indicates the version at which it was stabilized.

Arguments

The stable attribute supports optional arguments that can be passed to control its behavior.

• since: the version at which the item was stabilized. This should be a string that follows the Semantic Versioning convention. If not specified, the item will be marked as stable with no version information.
• issue: a link or reference to a tracking issue for the stabilized feature. This will be included in the item’s documentation.

Examples

We can apply the attribute to a public function like so:

/// This function does something really risky!
///
/// Don't use it yet!
#[instability::stable(since = "v1.0.0")]
pub fn stable_function() {
    unimplemented!()
}

This will essentially be expanded to the following:

/// This function does something really risky!
///
/// Don't use it yet!
///
/// # Stability
///
/// This API was stabilized in version 1.0.0.
pub fn stable_function() {
    unimplemented!()
}

Applying this attribute to non-pub items is pointless and does nothing.

Panics

This macro will panic if applied to an unsupported item type.

Limitations

This attribute does not change the visibility of the annotated item. You should ensure that the item’s visibility is set to pub if you want it to be part of your crate’s public API.

See also

• The unstable attribute for marking an API as unstable.