Mercurial > crates > nonstick

diff src/libpam/handle.rs @ 103:dfcd96a74ac4 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
write a truly prodigious amount of documentation adds a bunch of links to the OpenPAM man pages and the XSSO spec as well as just a bunch of prose and stuff.
author Paul Fisher <paul@pfish.zone>
date Wed, 25 Jun 2025 00:59:24 -0400
parents 94eb11cb1798
children
line wrap: on
line diff
--- a/src/libpam/handle.rs	Tue Jun 24 18:11:38 2025 -0400
+++ b/src/libpam/handle.rs	Wed Jun 25 00:59:24 2025 -0400
@@ -7,7 +7,10 @@
 pub use crate::libpam::pam_ffi::LibPamHandle;
 use crate::libpam::{memory, pam_ffi};
 use crate::logging::Level;
-use crate::{Conversation, EnvironMap, Flags, PamHandleApplication, PamHandleModule};
+use crate::{
+    Conversation, EnvironMap, Flags, PamHandleApplication, PamHandleModule, _guide, _linklist,
+    _stdlinks,
+};
 use num_enum::{IntoPrimitive, TryFromPrimitive};
 use std::cell::Cell;
 use std::ffi::{c_char, c_int, CString};
@@ -78,13 +81,16 @@
     /// when authenticating a user. This corresponds to the configuration file
     /// named <code>/etc/pam.d/<var>service_name</var></code>.
     ///
-    /// For more information, see the [`pam_start` man page][man], or
-    /// [`pam_start` in the PAM Application Developers' Guide][adg].
+    /// # References
+    #[doc = _linklist!(pam_start: adg, _std)]
     ///
-    /// [man]: https://www.man7.org/linux/man-pages/man3/pam_start.3.html
-    /// [adg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/adg-interface-by-app-expected.html#adg-pam_start
+    #[doc = _stdlinks!(3 pam_start)]
+    #[doc = _guide!(adg: "adg-interface-by-app-expected.html#adg-pam_start")]
     pub fn build_with_service(service_name: String) -> HandleBuilder {
-        HandleBuilder { service_name, username: None }
+        HandleBuilder {
+            service_name,
+            username: None,
+        }
     }
 
     fn start(
@@ -152,9 +158,13 @@
 impl Drop for OwnedLibPamHandle<'_> {
     /// Closes the PAM session on an owned PAM handle.
     ///
-    /// See the [`pam_end` manual page][man] for more information.
+    /// This internally calls `pam_end` with the appropriate error code.
     ///
-    /// [man]: https://www.man7.org/linux/man-pages/man3/pam_end.3.html
+    /// # References
+    #[doc = _linklist!(pam_end: adg, _std)]
+    ///
+    #[doc = _guide!(adg: "adg-interface-by-app-expected.html#adg-pam_end")]
+    #[doc = _stdlinks!(3 pam_end)]
     fn drop(&mut self) {
         unsafe {
             pam_ffi::pam_end(