Mercurial > crates > nonstick

comparison src/_doc.rs @ 103:dfcd96a74ac4

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
children 13b4d2a19674
comparison
equal deleted inserted replaced
102:94eb11cb1798 103:dfcd96a74ac4
1 //! A place to stick documentation stuff.
2
3 /// Generates text lists of reference links for docs.
4 ///
5 /// Use this with the other doc macros for the correct link names.
6 ///
7 /// # Examples
8 ///
9 /// ```
10 /// #[doc = _linklist!(pam_get_authtok: man7, manbsd)]
11 /// ///
12 /// /// ...use it with link references, like the below...
13 /// ///
14 /// #[doc = _stdlinks!(3 pam_get_authtok)]
15 /// ```
16 #[macro_export]
17 #[doc(hidden)]
18 macro_rules! _linklist {
19 ($func:ident: adg$(, $rest:ident)*) => {
20 concat!(
21 "- [Application Developers' Guide on `", stringify!($func), "`][adg]\n",
22 $crate::_linklist!($func: $($rest),*)
23 )
24 };
25 ($func:ident: mwg$(, $rest:ident)*) => {
26 concat!(
27 "- [Module Writers' Guide on `", stringify!($func), "`][mwg]\n",
28 $crate::_linklist!($func: $($rest),*)
29 )
30 };
31 ($func:ident: _std$(, $rest:ident)*) => {
32 $crate::_linklist!($func: man7, manbsd, xsso$(, $rest)*)
33 };
34 ($func:ident: man7$(, $rest:ident)*) => {
35 concat!(
36 "- [Linux-PAM manpage for `", stringify!($func), "`][man7]\n",
37 $crate::_linklist!($func: $($rest),*)
38 )
39 };
40 ($func:ident: manbsd$(, $rest:ident)*) => {
41 concat!(
42 "- [OpenPAM manpage for `", stringify!($func), "`][manbsd]\n",
43 $crate::_linklist!($func: $($rest),*)
44 )
45 };
46 ($func:ident: xsso$(, $rest:ident)*) => {
47 concat!(
48 "- [X/SSO spec for `", stringify!($func), "`][xsso]",
49 $crate::_linklist!($func: $($rest),*)
50 )
51 };
52 ($func:ident:$(,)?) => { "" };
53 }
54
55 /// Generates a Markdown link reference to one of the PAM guides.
56 ///
57 /// # Examples
58 ///
59 /// ```
60 /// #[doc = _guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_user")]
61 /// ```
62 #[macro_export]
63 #[doc(hidden)]
64 macro_rules! _guide {
65 ($name:ident: $page_link:literal) => {
66 concat!(
67 "[",
68 stringify!($name),
69 "]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/",
70 $page_link
71 )
72 };
73 }
74
75 /// Generates a Markdown link reference to the Linux man pages on man7.org.
76 ///
77 /// # Examples
78 ///
79 /// ```
80 /// // Both of these formulations create a link reference named `man7`.
81 /// #[doc = _man7!(3 fn_name)]
82 /// #[doc = _man7!(5 thing_name "SECTION")]
83 /// // This one creates a link reference named `link_name`.
84 /// #[doc = _man7!(link_name: 1 prog_name "SECTION")]
85 /// ```
86 #[macro_export]
87 #[doc(hidden)]
88 macro_rules! _man7 {
89 ($n:literal $fn:ident $($anchor:literal)?) => {
90 $crate::_man7!(man7: $n $fn $($anchor)?)
91 };
92 ($name:ident: $n:literal $fn:ident $($anchor:literal)?) => {
93 concat!(
94 "[", stringify!($name), "]: ",
95 "https://man7.org/linux/man-pages/man", $n, "/",
96 stringify!($fn), ".", $n, ".html", $("#", $anchor)?
97 )
98 };
99 }
100
101 /// Generates a Markdown link reference to the NetBSD man pages.
102 ///
103 /// # Examples
104 ///
105 /// ```
106 /// // Both of these formulations create a link named `manbsd`.
107 /// #[doc = _manbsd!(3 fn_name)]
108 /// #[doc = _manbsd!(5 thing_name "SECTION")]
109 /// // This one creates a link named `link_name`.
110 /// #[doc = _manbsd!(link_name: 1 prog_name "SECTION")]
111 /// ```
112 #[macro_export]
113 #[doc(hidden)]
114 macro_rules! _manbsd {
115 ($n:literal $func:ident $($anchor:literal)?) => {
116 $crate::_manbsd!(manbsd: $n $func $($anchor)?)
117 };
118 ($name:ident: $n:literal $func:ident $($anchor:literal)?) => {
119 concat!("[", stringify!($name), "]: ",
120 "https://man.netbsd.org/", stringify!($func), ".", $n,
121 $("#", $anchor)?
122 )
123 };
124 }
125
126 /// Generates a Markdown link reference to the X/SSO specification.
127 ///
128 /// # Examples
129 ///
130 /// ```
131 /// // Both of these formulations create a link reference named `xsso`.
132 /// // A link to the X/SSO specification for the `pam_set_item` function.
133 /// #[doc = _xsso!(pam_set_item)]
134 /// // A link to the HTML page with the given name.
135 /// #[doc = _xsso!("some_page.htm#section-id")]
136 ///
137 /// // This one creates a link reference named `spec_toc`.
138 /// #[doc = _xsso!(spec_toc: "toc.htm")]
139 /// ```
140 #[macro_export]
141 #[doc(hidden)]
142 macro_rules! _xsso {
143 ($func:ident) => { $crate::_xsso!(xsso: concat!(stringify!($func), ".htm")) };
144 ($page:literal) => { $crate::_xsso!(xsso: $page) };
145 ($name:ident: $page:expr) => {
146 concat!("[", stringify!($name), "]: https://pubs.opengroup.org/onlinepubs/8329799/", $page)
147 };
148 }
149
150 /// Generates Markdown link references to Linux-PAM, OpenPAM, and X/SSO.
151 ///
152 /// A shortcut to `_man7!`, `_manbsd!`, and `_xsso!`.
153 ///
154 /// # Examples
155 ///
156 /// ```
157 /// #[doc = _stdlinks!(3 pam_get_item)]
158 /// ```
159 #[macro_export]
160 #[doc(hidden)]
161 macro_rules! _stdlinks {
162 ($n:literal $func:ident) => {
163 concat!($crate::_man7!($n $func), "\n", $crate::_manbsd!($n $func), "\n", $crate::_xsso!($func))
164 };
165 }