From b37ec78690124a83bf87feddbc7169c28156a6a2 Mon Sep 17 00:00:00 2001 From: Ross MacArthur <ross@macarthur.io> Date: Sun, 22 Dec 2019 17:20:48 +0200 Subject: [PATCH 1/3] Rewrap stability.md to column 79 --- src/stability.md | 83 +++++++++++++++++++++++++----------------------- 1 file changed, 44 insertions(+), 39 deletions(-) diff --git a/src/stability.md b/src/stability.md index 1db738cb2..86d2a2e69 100644 --- a/src/stability.md +++ b/src/stability.md @@ -1,30 +1,32 @@ # Stability attributes -This section is about the stability attributes and schemes that allow stable APIs to use unstable -APIs internally in the rustc standard library. +This section is about the stability attributes and schemes that allow stable +APIs to use unstable APIs internally in the rustc standard library. -For instructions on stabilizing a language feature see -[Stabilizing Features](./stabilization_guide.md). +For instructions on stabilizing a language feature see [Stabilizing +Features](./stabilization_guide.md). ## unstable -The `#[unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")]` attribute explicitly -marks an item as unstable. Items that are marked as "unstable" cannot be used -without a corresponding `#![feature]` attribute on the crate, even on a -nightly compiler. This restriction only applies across crate boundaries, unstable -items may be used within the crate they are defined. +The `#[unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")]` +attribute explicitly marks an item as unstable. Items that are marked as +"unstable" cannot be used without a corresponding `#![feature]` attribute on +the crate, even on a nightly compiler. This restriction only applies across +crate boundaries, unstable items may be used within the crate they are defined. -The `unstable` attribute infects all sub-items, where the attribute doesn't have to be -reapplied. So if you apply this to a module, all items in the module will be unstable. +The `unstable` attribute infects all sub-items, where the attribute doesn't +have to be reapplied. So if you apply this to a module, all items in the module +will be unstable. -You can make specific sub-items stable by using the `#[stable]` attribute on them. -The stability scheme works similarly to how `pub` works. You can have public functions of -nonpublic modules and you can have stable functions in unstable modules or vice versa. +You can make specific sub-items stable by using the `#[stable]` attribute on +them. The stability scheme works similarly to how `pub` works. You can have +public functions of nonpublic modules and you can have stable functions in +unstable modules or vice versa. Note, however, that due to a [rustc bug], stable items inside unstable modules *are* available to stable code in that location! So, for example, stable code -can import `core::intrinsics::transmute` even though `intrinsics` is an unstable -module. Thus, this kind of nesting should be avoided when possible. +can import `core::intrinsics::transmute` even though `intrinsics` is an +unstable module. Thus, this kind of nesting should be avoided when possible. The `unstable` attribute may also have the `soft` value, which makes it a future-incompatible deny-by-default lint instead of a hard error. This is used @@ -35,29 +37,32 @@ prevents breaking dependencies by leveraging Cargo's lint capping. ## stable -The `#[stable(feature = "foo", "since = "1.420.69")]` attribute explicitly marks an item as -stabilized. To do this, follow the instructions in +The `#[stable(feature = "foo", "since = "1.420.69")]` attribute explicitly +marks an item as stabilized. To do this, follow the instructions in [Stabilizing Features](./stabilization_guide.md). Note that stable functions may use unstable things in their body. ## allow_internal_unstable -Macros, compiler desugarings and `const fn`s expose their bodies to the call site. To -work around not being able to use unstable things in the standard library's macros, there's the -`#[allow_internal_unstable(feature1, feature2)]` attribute that whitelists the given features for -usage in stable macros or `const fn`s. - -Note that `const fn`s are even more special in this regard. You can't just whitelist any feature, -the features need an implementation in `qualify_min_const_fn.rs`. For example the `const_fn_union` -feature gate allows accessing fields of unions inside stable `const fn`s. The rules for when it's -ok to use such a feature gate are that behavior matches the runtime behavior of the same code -(see also [this blog post][blog]). This means that you may not create a -`const fn` that e.g. transmutes a memory address to an integer, because the addresses of things -are nondeterministic and often unknown at compile-time. - -Always ping @oli-obk, @RalfJung, and @Centril if you are adding more `allow_internal_unstable` -attributes to any `const fn` +Macros, compiler desugarings and `const fn`s expose their bodies to the call +site. To work around not being able to use unstable things in the standard +library's macros, there's the `#[allow_internal_unstable(feature1, feature2)]` +attribute that whitelists the given features for usage in stable macros or +`const fn`s. + +Note that `const fn`s are even more special in this regard. You can't just +whitelist any feature, the features need an implementation in +`qualify_min_const_fn.rs`. For example the `const_fn_union` feature gate allows +accessing fields of unions inside stable `const fn`s. The rules for when it's +ok to use such a feature gate are that behavior matches the runtime behavior of +the same code (see also [this blog post][blog]). This means that you may not +create a `const fn` that e.g. transmutes a memory address to an integer, +because the addresses of things are nondeterministic and often unknown at +compile-time. + +Always ping @oli-obk, @RalfJung, and @Centril if you are adding more +`allow_internal_unstable` attributes to any `const fn` ## staged_api @@ -83,13 +88,13 @@ item must also have a `stable` or `unstable` attribute. )] ``` -The `suggestion` field is optional. If given, it should be a string that can -be used as a machine-applicable suggestion to correct the warning. This is -typically used when the identifier is renamed, but no other significant -changes are necessary. +The `suggestion` field is optional. If given, it should be a string that can be +used as a machine-applicable suggestion to correct the warning. This is +typically used when the identifier is renamed, but no other significant changes +are necessary. -Another difference from the `deprecated` attribute is that the `since` field -is actually checked against the current version of `rustc`. If `since` is in a +Another difference from the `deprecated` attribute is that the `since` field is +actually checked against the current version of `rustc`. If `since` is in a future version, then the `deprecated_in_future` lint is triggered which is default `allow`, but most of the standard library raises it to a warning with `#![warn(deprecated_in_future)]`. From 7081a0d710c915ce0b8ffa3609efd314faae3e6e Mon Sep 17 00:00:00 2001 From: Ross MacArthur <ross@macarthur.io> Date: Sun, 22 Dec 2019 17:21:02 +0200 Subject: [PATCH 2/3] Update stability documentation, mention `issue = "none"` --- src/stability.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/stability.md b/src/stability.md index 86d2a2e69..9e75495b1 100644 --- a/src/stability.md +++ b/src/stability.md @@ -14,6 +14,10 @@ attribute explicitly marks an item as unstable. Items that are marked as the crate, even on a nightly compiler. This restriction only applies across crate boundaries, unstable items may be used within the crate they are defined. +The `issue` field specifies the associated GitHub [issue number]. This field is +required and all unstable features should have an associated tracking issue. In +rare cases where there is no sensible value `issue = "none"` is used. + The `unstable` attribute infects all sub-items, where the attribute doesn't have to be reapplied. So if you apply this to a module, all items in the module will be unstable. @@ -33,6 +37,7 @@ future-incompatible deny-by-default lint instead of a hard error. This is used by the `bench` attribute which was accidentally accepted in the past. This prevents breaking dependencies by leveraging Cargo's lint capping. +[issue number]: https://github.com/rust-lang/rust/issues [rustc bug]: https://github.com/rust-lang/rust/issues/15702 ## stable From e0dcb9979cf8c8168705af667cf673b93eaa7a5b Mon Sep 17 00:00:00 2001 From: Ross MacArthur <ross@macarthur.io> Date: Sun, 22 Dec 2019 23:36:34 +0200 Subject: [PATCH 3/3] Minor update to stability.md --- src/stability.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/stability.md b/src/stability.md index 9e75495b1..292d88813 100644 --- a/src/stability.md +++ b/src/stability.md @@ -12,7 +12,8 @@ The `#[unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")]` attribute explicitly marks an item as unstable. Items that are marked as "unstable" cannot be used without a corresponding `#![feature]` attribute on the crate, even on a nightly compiler. This restriction only applies across -crate boundaries, unstable items may be used within the crate they are defined. +crate boundaries, unstable items may be used within the crate that defines +them. The `issue` field specifies the associated GitHub [issue number]. This field is required and all unstable features should have an associated tracking issue. In