--- a/src/lib.rs	Wed Jul 30 18:43:07 2025 -0400
+++ b/src/lib.rs	Thu Jul 31 14:36:50 2025 -0400
@@ -139,8 +139,46 @@
 //! environment variable at build time. See the [`libpam_sys`] documentation.
 #![doc = concat!("This documentation was built for **", pam_impl_name!(), "**.")]
 //!
+//! # Cargo features
+//!
+//! This crate provides the following Cargo features:
+//!
+//! - **link** (enabled by default): Actually link against PAM,
+//!   rather than just providing an abstract PAM interface.
+//!   Enabling this will fail if extensions incompatible with the
+//!   PAM implementation you're linking against are also enabled.
+//! - Extensions beyond the PAM specification provided by various PAM
+//!   implementations:
+//!   - **basic-ext**: Enable extensions provided by both Linux-PAM and OpenPAM.
+//!     This is limited to a few return enums.
+//!   - **linux-pam-ext** (includes basic-ext): Enable extensions provided by
+//!     Linux-PAM. This includes enum values and the ability to send
+//!     binary messages between the PAM module and the application.
+//!   - **openpam-ext** (includes basic-ext): Enable extensions provided by
+//!     OpenPAM. This includes enum values.
+//!   - **sun-ext**: Enable extensions provided by Sun PAM.
+//!     This includes enum values.
+//!
+//! # Design
+//!
+//! This library consists of two parts:
+//!
+//! - The generic PAM interface, a set of traits describing the behavior of PAM
+//!   and the API we export. It is independent of the PAM library itself and
+//!   could be implemented by any crate to provide PAM-like services.
+//!   This is primarily intended to allow a developer to test their PAM modules
+//!   and applications by writing mock implementations to verify their
+//!   application (or module) code's interactions with PAM itself.
+//!
+//! - The bindings to LibPAM itself. This part is included only when **link**
+//!   is enabled. These live in the `libpam` submodule (with a few exceptions
+//!   for constant-related code).
+//!
 //! # References
 //!
+//! These documents were used when authoring this library and will probably be
+//! of value if you want to implement a PAM module or a PAM application.
+//!
 //! - The Linux-PAM guides provide information for a variety of audiences.
 //!   While some of it is specific to Linux-PAM, much of it applies to other
 //!   PAM implementations:
@@ -156,15 +194,16 @@
 //!   - [OpenPAM admin documentation][bsdpam8]
 //!   - [Illumos pam.conf documentation][sunpam5]
 //! - [The original PAM specification][spec] (mostly of historical interest)
+//! - [Cooking spray](https://en.wikipedia.org/wiki/Cooking_spray)
 #![doc = ""]
-#![doc = crate::_doc::man7!(man7pam8: 8 pam)]
-#![doc = crate::_doc::manbsd!(bsdpam8: 8 pam)]
-#![doc = crate::_doc::mansun!(sunpam5: 5 "pam.conf")]
-#![doc = crate::_doc::stdlinks!(3 pam)]
-#![doc = crate::_doc::guide!(adg: "Linux-PAM_ADG.html")]
-#![doc = crate::_doc::guide!(mwg: "Linux-PAM_MWG.html")]
-#![doc = crate::_doc::guide!(sag: "Linux-PAM_SAG.html")]
-#![doc = crate::_doc::xsso!(spec: "toc.htm")]
+#![doc = _doc::man7!(man7pam8: 8 pam)]
+#![doc = _doc::manbsd!(bsdpam8: 8 pam)]
+#![doc = _doc::mansun!(sunpam5: 5 "pam.conf")]
+#![doc = _doc::stdlinks!(3 pam)]
+#![doc = _doc::guide!(adg: "Linux-PAM_ADG.html")]
+#![doc = _doc::guide!(mwg: "Linux-PAM_MWG.html")]
+#![doc = _doc::guide!(sag: "Linux-PAM_SAG.html")]
+#![doc = _doc::xsso!(spec: "toc.htm")]
 
 #[cfg(feature = "link")]
 mod _compat_checker {