Attribute Macro 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.
• Annotated impl blocks will instead be removed.
• Changes the Visibility of certain child items of the annotated item (such as struct fields) to match the item’s visibility. Children that are not public will not be affected.
• Appends an “Stability” section to the item’s documentation that notes that the item is unstable and indicates the name of the crate feature to enable it.

Child items of annotated modules are unchanged, as it might be desirable to be able to re-export them even if the module visibility is restricted. You should apply the attribute to each item within the module with the same feature name if you want to restrict the module’s contents itself and not just the module namespace.

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: the name of the unstable feature that should control this item’s availability. This will have the string unstable- prepended to it. If not specified, the item will instead be guarded by a catch-all unstable feature.
• issue: a link or reference to a tracking issue for the unstable 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::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!()
}

We can also apply the attribute to an impl block like so:

/// This structure is responsible for bar.
pub struct Foo;

#[instability::unstable(feature = "unstable-dependency")]
impl Default for Foo {
    fn default() -> Self {
        unimplemented!()
    }
}