--- a/pam/src/hooks.rs	Tue Sep 26 01:51:39 2017 -0600
+++ b/pam/src/hooks.rs	Tue Sep 26 02:15:28 2017 -0600
@@ -2,22 +2,24 @@
 use constants::{PamFlag, PamResultCode};
 use std::ffi::CStr;
 
-/// Provides functions that are invoked by the entrypoints generated by the `pam_hooks!` macro.
+/// Provides functions that are invoked by the entrypoints generated by the
+/// [`pam_hooks!` macro](../macro.pam_hooks.html).
 ///
 /// All of hooks are ignored by PAM dispatch by default given the default return value of `PAM_IGNORE`.
 /// Override any functions that you want to handle with your module. See `man pam(3)`.
+#[allow(unused_variables)]
 pub trait PamHooks {
     /// This function performs the task of establishing whether the user is permitted to gain access at
     /// this time. It should be understood that the user has previously been validated by an
     /// authentication module. This function checks for other things. Such things might be: the time of
     /// day or the date, the terminal line, remote hostname, etc. This function may also determine
     /// things like the expiration on passwords, and respond that the user change it before continuing.
-	fn acct_mgmt(_pamh: &PamHandle, _args: Vec<&CStr>, _flags: PamFlag) -> PamResultCode {
+	fn acct_mgmt(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
 		PamResultCode::PAM_IGNORE
 	}
 
     /// This function performs the task of authenticating the user.
-	fn sm_authenticate(_pamh: &PamHandle, _args: Vec<&CStr>, _flags: PamFlag) -> PamResultCode {
+	fn sm_authenticate(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
 		PamResultCode::PAM_IGNORE
 	}
 
@@ -27,17 +29,17 @@
 	/// PAM_PRELIM_CHECK and then, if the module does not return PAM_TRY_AGAIN, subsequently with
 	/// PAM_UPDATE_AUTHTOK. It is only on the second call that the authorization token is
 	/// (possibly) changed.
-	fn sm_chauthtok(_pamh: &PamHandle, _args: Vec<&CStr>, _flags: PamFlag) -> PamResultCode {
+	fn sm_chauthtok(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
 		PamResultCode::PAM_IGNORE
 	}
 
 	/// This function is called to terminate a session.
-	fn sm_close_session(_pamh: &PamHandle, _args: Vec<&CStr>, _flags: PamFlag) -> PamResultCode {
+	fn sm_close_session(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
 		PamResultCode::PAM_IGNORE
 	}
 
 	/// This function is called to commence a session.
-	fn sm_open_session(_pamh: &PamHandle, _args: Vec<&CStr>, _flags: PamFlag) -> PamResultCode {
+	fn sm_open_session(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
 		PamResultCode::PAM_IGNORE
 	}
 
@@ -46,7 +48,7 @@
     /// information about a user than their authentication token. This function is used to make such
     /// information available to the application. It should only be called after the user has been
     /// authenticated but before a session has been established.
-	fn sm_setcred(_pamh: &PamHandle, _args: Vec<&CStr>, _flags: PamFlag) -> PamResultCode {
+	fn sm_setcred(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
 		PamResultCode::PAM_IGNORE
 	}
 }
@@ -54,10 +56,39 @@
 /// Macro to generate the `extern "C"` entrypoint bindings needed by PAM
 ///
 /// You can call `pam_hooks!(SomeType);` for any type that implements `PamHooks`
+///
+/// ## Examples:
+///
+/// Here is full example of a PAM module that would authenticate and authorize everybody:
+///
+/// ```
+/// #[macro_use] extern crate pam;
+///
+/// use pam::hooks::PamHooks;
+/// use pam::module::PamHandle;
+/// use pam::constants::{PamResultCode, PamFlag};
+/// use std::ffi::CStr;
+///
+/// # fn main() {}
+/// struct MyPamModule;
+/// pam_hooks!(MyPamModule);
+///
+/// impl PamHooks for MyPamModule {
+///	   fn sm_authenticate(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
+///        println!("Everybody is authenticated!");
+///        PamResultCode::PAM_SUCCESS
+///    }
+///
+///    fn acct_mgmt(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
+///        println!("Everybody is authorized!");
+///        PamResultCode::PAM_SUCCESS
+///    }
+/// }
+/// ```
 #[macro_export]
 macro_rules! pam_hooks {
 	($ident:ident) => (
-		pub use pam_hooks_scope::*;
+		pub use self::pam_hooks_scope::*;
 		mod pam_hooks_scope {
 			use $crate::module::PamHandle;
 			use $crate::constants::{PamFlag, PamResultCode};