Comparison semantics may be unexpected

[ronnodas]

As implemented, comparison between BitFlags is not the same as contains and depends on the bit assigned to each variant (explicitly or implicitly via the ordering of the variants). This is needed to implement Ord but may not be the expected semantics of a <= b. It would be nice if this was explained in the documentation.

One could even argue that BitFlags<Enum> should not implement Ord but only PartialOrd (with the semantics a <= b iff b.contains(a)) except maybe if Enum implements Ord.

[meithecatte]

I do agree that the impl isn't ideal – the usecase is using BitFlags as (part of) a BTreeMap key, which unfortunately requires full Ord, and precludes any meaningful interpretations for <=. I wish Rust had a way to distinguish "meaningful comparison" from BTreeMap's "has an arbitrary ordering" requirement.

I'd gladly merge a PR that clarifies this in the docs, though!