Attribute Macro stability::unstable

#[unstable]

Mark an API as unstable.

You can apply this attribute to an item in your public API that you would like to expose to users, but are not yet ready for general use. This is useful when you want to let users try out some new functionality for an API you haven’t finished testing or designing, or for whatever reason do not want to commit any stability guarantees for.

This attribute does the following things to annotated items:

• Changes the visibility of the item from pub to pub(crate), unless a certain crate feature is enabled. This ensures that internal code within the crate can always use the item, but downstream consumers cannot access it unless they opt-in to the unstable API.
• Appends an “Availability” section to the item’s documentation that notes that the item is unstable, and indicates the name of the crate feature to enable it.

Note that unlike the #[unstable] attribute used in the standard library, this attribute does not apply itself recursively to child items.

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

Arguments

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

• feature: Specify the name of the unstable feature that should control this item’s availability. The crate feature will have the string unstable- prepended to it. If not specified, it will be guarded by a catch-all unstable feature.

Examples

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

/// This function does something really risky!
///
/// Don't use it yet!
#[stability::unstable(feature = "risky-function")]
pub fn risky_function() {
    unimplemented!()
}

This will essentially be expanded to the following:

/// This function does something really risky!
///
/// Don't use it yet!
///
/// # Availability
///
/// **This API is marked as unstable** and is only available when the
/// `unstable-risky-function` crate feature is enabled. This comes with no
/// stability guarantees, and could be changed or removed at any time.
#[cfg(feature = "unstable-risky-function")]
pub fn risky_function() {
    unimplemented!()
}

/// This function does something really risky!
///
/// Don't use it yet!
#[cfg(not(feature = "unstable-risky-function"))]
pub(crate) fn risky_function() {
    unimplemented!()
}