Guidance is necessary on how to interact with rand_core::Error::CUSTOM_START

[nagisa]

Currently CUSTOM_START sets the two upper-most bits in the u32, however it is not obvious and documented how many codes are available above this point. For instance, doing something along the lines:

const MY_LIBRARY_BIT: u32 = 1 << 31;
pub const SOME_ERROR: NonZeroU32 = unsafe {
    NonZeroU32::new_unchecked(rand_core::CUSTOM_START + MY_LIBRARY_BIT + 1)
};

will fail to compile because of the addition overflow. If the user were to use bitwise or, the error would become silent, but it isn’t clear whether that’s desirable.

The documentation for CUSTOM_START should document the range of values users can expect to use within the u32.

[dhardy]

True. We should probably also document the value of CUSTOM_START, since it is not expected to change.

@newpavlov @josephlr

(Affects doc in rand_core/src/error.rs and getrandom/src/error.rs.)

[dhardy]

The above PR fixes this (for Rand crates at least).