Merge pull request #369 from bitflags/feat/spec

Specify the behavior of bitflags

.github/workflows/rust.yml

@@ -51,6 +51,22 @@ jobs:
       - name: Default features
         run: cargo bench --no-run
 
+  ui:
+    name: UI
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab
+
+      - name: Install Rust toolchain
+        run: rustup default beta
+
+      - name: Compile pass
+        run: cargo test pass
+
+      - name: Compile fail
+        run: cargo test fail
+
   msrv:
     name: MSRV
     runs-on: ubuntu-latest

README.md

@@ -6,9 +6,20 @@ bitflags
 [![Documentation](https://docs.rs/bitflags/badge.svg)](https://docs.rs/bitflags)
 ![License](https://img.shields.io/crates/l/bitflags.svg)
 
-A Rust macro to generate structures which behave like a set of bitflags
+`bitflags` generates flags enums with well-defined semantics and ergonomic end-user APIs.
+
+You can use `bitflags` to:
+
+- provide more user-friendly bindings to C APIs where flags may or may not be fully known in advance.
+- generate efficient options types with string parsing and formatting support.
+
+You can't use `bitflags` to:
+
+- guarantee only bits corresponding to defined flags will ever be set. `bitflags` allows access to the underlying bits type so arbitrary bits may be set.
+- define bitfields. `bitflags` only generates types where set bits denote the presence of some combination of flags.
 
 - [Documentation](https://docs.rs/bitflags)
+- [Specification](https://github.com/bitflags/bitflags/blob/main/spec.md)
 - [Release notes](https://github.com/bitflags/bitflags/releases)
 
 ## Usage