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?

0 files changed, 0 insertions, 0 deletions