Expand some aspects of the documentation

- Emphasize the distinction between `T` and `BitFlags<T>`.
- Mention `make_bitflags` in the section about `const fn` APIs.
- Add a `const` to the `make_bitflags` example.

This is motivated by the discussion in #63.

Author: meithecatte

README.md

@@ -9,6 +9,10 @@
 with `#[bitflags]`, and `BitFlags<YourEnum>` will be able to hold arbitrary combinations
 of your enum within the space of a single integer.
 
+Unlike other crates, `enumflags2` makes the type-level distinction between
+a single flag (`YourEnum`) and a set of flags (`BitFlags<YourEnum>`).
+This allows idiomatic handling of bitflags, such as with `match` and `iter`.
+
 ## Features
 
 - [x] Uses enums to represent individual flags&mdash;a set of flags is a separate type from a single flag.
@@ -75,13 +79,18 @@ context.
 **Naming convention:** If a separate, more limited function is provided
 for usage in a `const fn`, the name is suffixed with `_c`.
 
+Apart from functions whose name ends with `_c`, the [`make_bitflags!`] macro
+is often useful for many `const` and `const fn` usecases.
+
 **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.
+`BitFlags<T, u16>`, etc — best accomplished by a simple macro.
+
+**Documentation considerations:** The strategy described above is often used
+by `enumflags2` itself. To avoid clutter in the auto-generated documentation,
+the implementations for widths other than `u8` are marked with `#[doc(hidden)]`.
 
 ## Customizing `Default`
 

src/lib.rs

@@ -3,6 +3,10 @@
 //! with `#[bitflags]`, and `BitFlags<YourEnum>` will be able to hold arbitrary combinations
 //! of your enum within the space of a single integer.
 //!
+//! Unlike other crates, `enumflags2` makes the type-level distinction between
+//! a single flag (`YourEnum`) and a set of flags (`BitFlags<YourEnum>`).
+//! This allows idiomatic handling of bitflags, such as with `match` and `iter`.
+//!
 //! ## Example
 //! ```
 //! use enumflags2::{bitflags, make_bitflags, BitFlags};
@@ -58,6 +62,9 @@
 //! **Naming convention:** If a separate, more limited function is provided
 //! for usage in a `const fn`, the name is suffixed with `_c`.
 //!
+//! Apart from functions whose name ends with `_c`, the [`make_bitflags!`] macro
+//! is often useful for many `const` and `const fn` usecases.
+//!
 //! **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
@@ -298,6 +305,11 @@ pub mod _internal {
     ///
     /// The values should reflect reality, like they do if the implementation
     /// is generated by the procmacro.
+    ///
+    /// `bits` must return the same value as
+    /// [`transmute_copy`][std::mem::transmute_copy].
+    ///
+    /// Representations for all values of `T` must have exactly one bit set.
     pub unsafe trait RawBitFlags: Copy + Clone + 'static {
         /// The underlying integer type.
         type Numeric: BitFlagNum;
@@ -533,17 +545,20 @@ pub struct BitFlags<T, N = <T as _internal::RawBitFlags>::Numeric> {
 /// `BitFlags<T>`. Instead of repeating the name of your type for each flag
 /// you want to add, try `make_bitflags!(Flags::{Foo | Bar})`.
 /// ```
-/// use enumflags2::{bitflags, make_bitflags};
-/// #[bitflags]
-/// #[repr(u8)]
-/// #[derive(Clone, Copy, Debug)]
-/// enum Test {
-///     A = 1 << 0,
-///     B = 1 << 1,
-///     C = 1 << 2,
-/// }
+/// # use enumflags2::{bitflags, BitFlags, make_bitflags};
+/// # #[bitflags]
+/// # #[repr(u8)]
+/// # #[derive(Clone, Copy, Debug)]
+/// # enum Test {
+/// #     A = 1 << 0,
+/// #     B = 1 << 1,
+/// #     C = 1 << 2,
+/// # }
 /// let x = make_bitflags!(Test::{A | C});
 /// assert_eq!(x, Test::A | Test::C);
+///
+/// // Also works in const contexts:
+/// const X: BitFlags<Test> = make_bitflags!(Test::{A | C});
 /// ```
 #[macro_export]
 macro_rules! make_bitflags {