--- a/src/lib.rs	Wed May 21 00:27:18 2025 -0400
+++ b/src/lib.rs	Wed May 21 19:00:51 2025 -0400
@@ -1,31 +1,38 @@
-//! Interface to the pluggable authentication module framework (PAM).
+//! A safe, nonstick interface to PAM.
+//!
+//! This implements a type-safe library to interact with PAM.
+//! Currently, it implements the subset of PAM useful for implementing a module.
+//!
+//! To write a new PAM module using this crate:
 //!
-//! The goal of this library is to provide a type-safe API that can be used to
-//! interact with PAM.  The library is incomplete - currently it supports
-//! a subset of functions for use in a pam authentication module.  A pam module
-//! is a shared library that is invoked to authenticate a user, or to perform
-//! other functions.
+//!  1. Create a `dylib` crate.
+//!  2. Implement a subset of the functions in the [PamModule] trait
+//!     corresponding to what you want your module to do.
+//!     In the simplest case (for a password-authentication system),
+//!     this will be the [PamModule::sm_authenticate] function.
+//!  3. Export your PAM module using the [pam_hooks!] macro.
+//!  4. Build and install the dynamic library.
+//!     This usually entails placing it at
+//!     `/usr/lib/security/pam_your_module.so`,
+//!     or maybe
+//!     <code>/usr/lib/<var>your-architecture</var>/security/pam_your_module.so</code>.
 //!
-//! For general information on writing pam modules, see
+//! For general information on writing PAM modules, see
 //! [The Linux-PAM Module Writers' Guide][module-guide]
 //!
 //! [module-guide]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/Linux-PAM_MWG.html
-//!
-//! A typical authentication module will define an external function called
-//! `pam_sm_authenticate()`, which will use functions in this library to
-//! interrogate the program that requested authentication for more information,
-//! and to render a result.
-//!
-//! Note that constants that are normally read from pam header files are
-//! hard-coded in the `constants` module.  The values there are taken from
-//! a Linux system.  That means that it might take some work to get this library
-//! to work on other platforms.
-
-extern crate libc;
 
 pub mod constants;
 pub mod conv;
 pub mod items;
-#[doc(hidden)]
-pub mod macros;
 pub mod module;
+
+mod memory;
+mod pam_ffi;
+
+#[doc(inline)]
+pub use crate::{
+    constants::{ErrorCode, Flags, MessageStyle, Result},
+    conv::Conversation,
+    module::{PamHandle, PamModule},
+};