Update stability documentation, mention issue = "none"

src/stability.md

@@ -1,63 +1,74 @@
 # 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 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
+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.
+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
 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
 
-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 +94,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)]`.