Clarify means of printing human-readable string in 2.0.0

[kpreid]

In bitflags 1.3, the automatic Debug implementation produced a concise human-readable string like "A | B"; in bitflags 2.0 it produces a string like "NameOfTheStruct(A | B)". This is an entirely reasonable change for Debug, since Debug is generally “no promises”, but if I want the previous string, it's not obvious how to get it. I dug around the examples and found in https://github.com/bitflags/bitflags/blob/main/examples/fmt.rs the remark that

        // You can `#[derive]` the `Debug` trait, but implementing it manually
        // can produce output like `A | B` instead of `Flags(A | B)`.
    ...
    impl fmt::Debug for Flags {
        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
            fmt::Debug::fmt(&self.0, f)
        }
    }

but it would be nice if this were in the library documentation under “Display and Debug”, especially since the changelog said “The representation of generated flags types has changed from a struct with the single field bits to a newtype. That means you can't refer to the underlying bits using the .bits field.” which led me to believe that self.0 wasn't usable (though on further thought, the Rust privacy rules mean that it would be unlikely for that to be the case, since the type is defined in the user's module).

The existence of the parser module and the remark that “This library defines a standard text-based representation for flags that generated flags types can use.” suggests that there should be an way to print that representation, but it doesn't go on to explain how.

Therefore, I suggest the following changes:

• Document that self.0 implements Display and what the format of that is, at https://docs.rs/bitflags/latest/bitflags/#debug-and-display, and in the changelog for migration purposes.
  • Put the “fmt(&self.0” trick in the documentation, not just an example.
• Document all the other characteristics of self.0 (what type is it? what properties does that type have?) if it is intended to be used.

[KodrAus]

Thanks for the feedback @kpreid 👍

Any improvements we can make to the documentation would be worthwhile. We do include generated docs for the internal .0 field, but should call this out more so it's more obvious what it is.