Description
This function is sometimes perceived as "more safe" than mem::uninitialized for arbitrary types. For types where the all-zero bit pattern is invalid, however, it is only more safe in that the run-time consequences of the UB are likely a bit less exploitable.
While the docs do warn that it can produce invalid values, this is put in the context of "dropping those invalid values is UB". At least some of the other ways in which invalid values can cause UB should be mentioned. There's a reference to mem::uninitialized for "similar caveats", but it's tricky to apply the wording there (talking about uninitialized data) to invalid values.
Ideally I'd like to say creating invalid values is UB, period (the Nomicon already says so, and it matches mem::uninitialized being slated for deprecation) but that's of course a rather drastic measure. At minimum, there should be a hint that various ways of reading the value (matching on it, putting it in an enum, printing it) are UB with invalid values.