update the readme

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