Use a _c suffix for const functions; update docs

Notably, for_each_uint! now helps hide the repeated implementations
in the docs, leaving only one copy visible.

Author: meithecatte

README.md

@@ -8,6 +8,8 @@
 `enumflags2` defines a `BitFlags<T>` type, which is a `Set<T>`
 for enums without associated data.
 
+This means that the type of a single flag is separate from a set of flags.
+
 ## Usage
 
 In your `Cargo.toml`:
@@ -25,33 +27,38 @@ enumflags2 = "^0.6"
 - [x] The debug formatter prints the binary flag value as well as the flag enums: `BitFlags(0b1111, [A, B, C, D])`.
 - [x] Optional support for serialization with the [`serde`](https://serde.rs/) feature flag.
 
-### Example
-
-```rust
-use enumflags2::BitFlags;
+## Example
+```
+use enumflags2::{bitflags, make_bitflags, BitFlags};
 
-#[derive(BitFlags, Copy, Clone, Debug, PartialEq)]
+#[bitflags]
 #[repr(u8)]
+#[derive(Copy, Clone, Debug, PartialEq)]
 enum Test {
     A = 0b0001,
     B = 0b0010,
     C = 0b0100,
     D = 0b1000,
 }
 
-let a_b = Test::A | Test::B; // BitFlags<Test>
+// Flags can be combined with |, this creates a BitFlags of your type:
+let a_b: BitFlags<Test> = Test::A | Test::B;
 let a_c = Test::A | Test::C;
-let b_c_d = Test::C | Test::B | Test::D;
+let b_c_d = make_bitflags!(Test::{B | C | D});
+
+// The debug output lets you inspect both the numeric value and
+// the actual flags:
 
 // BitFlags<Test>(0b11, [A, B])
 println!("{:?}", a_b);
 
 // BitFlags<Test>(0b1, [A])
 println!("{:?}", a_b & a_c);
 
-// Iterate over the flags like a normal set!
+// Iterate over the flags like a normal set
 assert_eq!(a_b.iter().collect::<Vec<_>>(), &[Test::A, Test::B]);
 
+// Query the contents with contains and intersects
 assert!(a_b.contains(Test::A));
 assert!(b_c_d.contains(Test::B | Test::C));
 assert!(!(b_c_d.contains(a_b)));
@@ -60,37 +67,28 @@ assert!(a_b.intersects(a_c));
 assert!(!(a_b.intersects(Test::C | Test::D)));
 ```
 
-### Note
-
-By default, the `BitFlags` are `usize`-sized. If you want them to be smaller,
-specify a `repr` on your enum as in the example above.
-
-### Migrating from 0.5
-
-The minimum rustc version has been bumped to 1.34.0, because of `syn 1.0`. The
-version policy from now on will be "what's available on Debian stable", [because
-Debian is famously slow with new software versions][debian-snailpace].
-
-You should no longer depend on `enumflags2_derive` directly.
-Use the reexport from the `enumflags2` crate.
-semver guarantees will be violated if you depend on the derive crate directly.
+## Optional Feature Flags
 
-The derive macro has been renamed to `BitFlags`, to make it clearer what the
-derive does.
+- [`serde`](https://serde.rs/) implements `Serialize` and `Deserialize`
+  for `BitFlags<T>`.
+- `std` implements `std::error::Error` for `FromBitsError`.
 
-The `nostd` feature flag has been removed. The crate now only depends on `libcore`
-by default. Enable the `std` flag to get an implementation of `std::error::Error`
-on error types.
+## `const fn`-compatible APIs
 
-Flags more than one bit set have been found to have inconsistent semantics.
-They are now rejected at compile-time. The same applies to flags without any
-bit set. If you were relying on this in your code, please [open an issue][issue]
-and explain your usecase.
+**Background:** The subset of `const fn` features currently stabilized is pretty limited.
+Most notably, [const traits are still at the RFC stage][const-trait-rfc],
+which makes it impossible to use any overloaded operators in a const
+context.
 
-`BitFlags::from_bits` returns a `Result` instead of an `Option`. This might
-necessitate some minor changes in your code.
+**Naming convention:** If a separate, more limited function is provided
+for usage in a `const fn`, the name is suffixed with `_c`.
 
-`BitFlags::not` has been removed. Use the `!` operator instead.
+**Blanket implementations:** If you attempt to write a `const fn` ranging
+over `T: BitFlag`, you will be met with an error explaining that currently,
+the only allowed trait bound for a `const fn` is `?Sized`. You will probably
+want to write a separate implementation for `BitFlags<T, u8>`,
+`BitFlags<T, u16>`, etc — probably generated by a macro.
+This strategy is often used by `enumflags2` itself; to avoid clutter, only
+one of the copies is shown in the documentation.
 
-[debian-snailpace]: https://www.jwz.org/blog/2016/04/i-would-like-debian-to-stop-shipping-xscreensaver/
-[issue]: https://github.com/NieDzejkob/enumflags2/issues/new
+[const-trait-rfc]: https://github.com/rust-lang/rfcs/pull/2632

src/fallible.rs

@@ -5,7 +5,7 @@ use super::BitFlag;
 
 // Coherence doesn't let us use a generic type here. Work around by implementing
 // for each integer type manually.
-for_each_uint! { ty =>
+for_each_uint! { $ty $hide_docs =>
     impl<T> TryFrom<$ty> for BitFlags<T>
     where
         T: BitFlag<Numeric=$ty>,