Document from_bits_unchecked unsafety (#200)

[niklasf]

Every unsafe method should have documented safety invariants. Here's an attempt for from_bits_unchecked().

[KodrAus]

Thanks @niklasf! This looks good to me

[SOF3]

How exactly can the bitflags! {} caller decide whether to allow extra flags? Furthermore, how exactly could unchecked bits actually lead to memory unsafety (rather than just unexpected behaviour)?

[KodrAus]

@SOF3 Whether or not to allow extra flags is determined by the source-of-truth for those flags. The motivation for this feature was for bitflags! that mirror another source that might change from under them. It's unsafe in the same sense that transmuting an integer to boolean is unsafe. Not every possible bit-pattern is a valid value for flags, so as the caller you're guaranteeing the bits you provide are "valid", where the definition of valid depends on the source of the flags.