Doc clarification for MaybeUninit::zeroed()

[kjvalencik]

👋 Hi! While reading the documentation for MaybeUninit::zeroed() I found it unclear whether using this method for a struct where 0 is an invalid bit pattern is correct usage or not.

The method description makes it clear that it is acceptable to use this method, only a user cannot assume that it is already valid.

It depends on T whether that already makes for proper initialization.

https://doc.rust-lang.org/std/mem/union.MaybeUninit.html#method.zeroed

However, the example introduces some ambiguity.

Incorrect usage of this function: initializing a struct with zero, where some fields cannot hold 0 as a valid value.

This phrasing seems to suggest that you should not use MaybeUninit::zeroed() when 0 is not a valid bit pattern. However, I believe the intent is to merely to convey that calling assume_init() without otherwise initializing the value is invalid.

There are some valid use cases to zero the memory to prevent an accidental security issue from mis-initialization, even if the bit pattern is invalid.

Suggested alternate phrasing:

Incorrect usage of this function: assuming zero filled memory is initialized, where some fields cannot hold 0 as a valid value, without overwriting with a valid bit-pattern.