Document restricted_std

This PR aims to pin down exactly what restricted_std is meant to achieve
and what it isn't.

This commit fixes rust-lang/wg-cargo-std-aware#87
by explaining why the error appears and what the choices the user has.
The error describes how std cannot function without knowing about some
form of OS/platform support. Any features of std that work without an
OS should be moved to core/alloc (see #27242
#103765).

Note that the message says "platform" and "environment" because, since
#120232, libstd can be built for
some JSON targets. This is still unsupported (all JSON targets probably
should be unstable rust-lang/wg-cargo-std-aware#90),
but a JSON target with the right configuration should hopefully have
some partial libstd support.

I propose closing rust-lang/wg-cargo-std-aware#69
as "Won't fix" since any support of std without properly configured os,
vendor or env fields is very fragile considering future upgrades of Rust
or dependencies. In addition there's no likely path to it being fixed
long term (making std buildable for all targets being the only
solution). This is distinct from tier 3 platforms with limited std
support implemented (and as such aren't restricted_std) because these
platforms can conceptually work in the future and std support should
mainly improve over time.

The alternative to closing rust-lang/wg-cargo-std-aware#69
is a new crate feature for std which escapes the restricted_std
mechanism in build.rs. It could be used with the -Zbuild-std-features
flag if we keep it permanently unstable, which I hope we can do anyway.
A minor side-effect in this scenario is that std wouldn't be marked as
unstable if documentation for it were generated with build-std.

Author: adamgemmell

library/std/src/lib.rs

@@ -220,7 +220,16 @@
 #![cfg_attr(feature = "miri-test-libstd", feature(rustc_private))]
 //
 #![cfg_attr(not(feature = "restricted-std"), stable(feature = "rust1", since = "1.0.0"))]
-#![cfg_attr(feature = "restricted-std", unstable(feature = "restricted_std", issue = "none"))]
+#![cfg_attr(
+    feature = "restricted-std",
+    unstable(
+        feature = "restricted_std",
+        issue = "none",
+        reason = "You have attempted to use a standard library built for a platform that it doesn't \
+            know how to support. Consider building it for a known environment, disabling it with \
+            `#![no_std]` or overriding this warning by enabling this feature".
+    )
+)]
 #![cfg_attr(not(bootstrap), rustc_preserve_ub_checks)]
 #![doc(
     html_playground_url = "https://play.rust-lang.org/",