Auto merge of #62891 - vext01:improve-black-box-docs, r=RalfJung,Centril,gnzlbg

Improve the documentation for std::hint::black_box.

The other day a colleague was reviewing some of my code which was using `black_box` to block constant propogation. There was a little confusion because the documentation kind of implies that `black_box` is only useful for dead code elimination, and only in benchmarking scenarios.

The docs currently say:

> A function that is opaque to the optimizer, to allow benchmarks to pretend to use outputs to assist in avoiding dead-code elimination.

Here is our discussion, in which I show (using godbolt) that a black box can also block constant propagation:
https://github.com/softdevteam/yk/pull/21#discussion_r302985038

This change makes the docstring for `black_box` a little more general, and while we are here, I've added an example (the same one from our discussion).

![image](https://user-images.githubusercontent.com/604955/61701322-ddf1e400-ad35-11e9-878c-b5b44a20770c.png)

OK to go in?

1 files changed, 12 insertions, 4 deletions

diff --git a/src/libcore/hint.rs b/src/libcore/hint.rs
index 3b2b28217f9..6439fa0e0c8 100644
--- a/src/libcore/hint.rs
+++ b/src/libcore/hint.rs
@@ -104,11 +104,19 @@ pub fn spin_loop() {
     }
 }
 
-/// A function that is opaque to the optimizer, to allow benchmarks to
-/// pretend to use outputs to assist in avoiding dead-code
-/// elimination.
+/// An identity function that *__hints__* to the compiler to be maximally pessimistic about what
+/// `black_box` could do.
 ///
-/// This function is a no-op, and does not even read from `dummy`.
+/// [`std::convert::identity`]: https://doc.rust-lang.org/core/convert/fn.identity.html
+///
+/// Unlike [`std::convert::identity`], a Rust compiler is encouraged to assume that `black_box` can
+/// use `x` in any possible valid way that Rust code is allowed to without introducing undefined
+/// behavior in the calling code. This property makes `black_box` useful for writing code in which
+/// certain optimizations are not desired, such as benchmarks.
+///
+/// Note however, that `black_box` is only (and can only be) provided on a "best-effort" basis. The
+/// extent to which it can block optimisations may vary depending upon the platform and code-gen
+/// backend used. Programs cannot rely on `black_box` for *correctness* in any way.
 #[inline]
 #[unstable(feature = "test", issue = "50297")]
 #[allow(unreachable_code)] // this makes #[cfg] a bit easier below.