Move feature docs to lib.rs and improve them

Author: jonas-schievink

Cargo.toml

@@ -24,11 +24,6 @@ embedded-hal = "0.2.4"
 [features]
 cm7-r0p1 = []
 inline-asm = []
-
-# Link against prebuilt assembly blobs that are compatible with Linker-Plugin LTO.
-# When using this feature, you *must* pass `-Clinker-plugin-lto` to rustc. See this link for
-# details:
-# https://doc.rust-lang.org/stable/rustc/linker-plugin-lto.html
 linker-plugin-lto = []
 
 [workspace]

src/lib.rs

@@ -24,6 +24,32 @@
 //!
 //! The disadvantage is that `inline-asm` requires a nightly toolchain.
 //!
+//! ## `cm7-r0p1`
+//!
+//! This feature enables workarounds for errata found on Cortex-M7 chips with revision r0p1. Some
+//! functions in this crate only work correctly on those chips if this Cargo feature is enabled
+//! (the functions are documented accordingly).
+//!
+//! ## `linker-plugin-lto`
+//!
+//! This feature links against prebuilt assembly blobs that are compatible with [Linker-Plugin LTO].
+//! This allows inlining assembly routines into the caller, even without the `inline-asm` feature,
+//! and works on stable Rust (but note the drawbacks below!).
+//!
+//! If you want to use this feature, you need to be aware of a few things:
+//!
+//! - You need to make sure that `-Clinker-plugin-lto` is passed to rustc. Please refer to the
+//!   [Linker-Plugin LTO] documentation for details.
+//!
+//! - You have to use a Rust version whose LLVM version is compatible with the toolchain in
+//!   `asm-toolchain`.
+//!
+//! - Due to a [Rust bug][rust-lang/rust#75940], this option does not work with optimization
+//!   levels `s` and `z`.
+//!
+//! [Linker-Plugin LTO]: https://doc.rust-lang.org/stable/rustc/linker-plugin-lto.html
+//! [rust-lang/rust#75940]: https://github.com/rust-lang/rust/issues/75940
+//!
 //! # Minimum Supported Rust Version (MSRV)
 //!
 //! This crate is guaranteed to compile on stable Rust 1.31 and up. It *might*