black_box docs correctness claim incorrect

[gonzalobg]

Location

https://doc.rust-lang.org/stable/std/hint/fn.black_box.html

Summary

The documentation of black_box states:

Programs cannot rely on black_box for correctness in any way.

but this is not accurate since programs can rely on it behaving like the identity function.
It would be better to reword this as

Programs cannot rely on black_box for correctness beyond it behaving as the identity function.

or similar, e.g.,

Programs cannot rely on the optimisation-inhibiting effects of black_box for correctness.

[jyn514]

@gonzalobg are you interested in making a PR to fix this? :)

[gonzalobg]

Can't, sorry.

[callumio]

@rustbot claim

[gonzalobg]

It seems that there are some other parts of the docs that are still incorrect. For example, in the How to use it section, the incorrect claim continues to be repeated:

First and foremost: black_box does not guarantee any exact behavior

I think the whole document needs a pass to fix this.

[pat-nel87]

@rustbot claim