Mercurial > crates > nonstick

comparison src/_doc.rs @ 146:1bc52025156b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Split PAM items into their own separate struct. To trim down the number of methods on `PamShared`, this puts all the Items into their own struct(s). This also makes the split between authtok/authtok_item easier to understand.
author Paul Fisher <paul@pfish.zone>
date Sun, 06 Jul 2025 19:10:26 -0400
parents 5c1e315c18ff
children
comparison
equal deleted inserted replaced
145:8f964b701652 146:1bc52025156b
5 /// Use this with the other doc macros for the correct link names. 5 /// Use this with the other doc macros for the correct link names.
6 /// 6 ///
7 /// # Examples 7 /// # Examples
8 /// 8 ///
9 /// ```ignore 9 /// ```ignore
10 /// # use nonstick::{linklist, stdlinks}; 10 /// # use nonstick::_doc::{linklist, stdlinks};
11 /// /// Here is a list of links: 11 /// /// Here is a list of links:
12 /// /// 12 /// ///
13 /// #[doc = linklist!(pam_get_authtok: man7, manbsd)] 13 /// #[doc = linklist!(pam_get_authtok: man7, manbsd)]
14 /// /// 14 /// ///
15 /// /// The links are defined in the `stdlinks!` invocation below: 15 /// /// The links are defined in the `stdlinks!` invocation below:
19 /// ``` 19 /// ```
20 macro_rules! linklist { 20 macro_rules! linklist {
21 ($func:ident: adg$(, $rest:ident)*) => { 21 ($func:ident: adg$(, $rest:ident)*) => {
22 concat!( 22 concat!(
23 "- [Application Developers' Guide on `", stringify!($func), "`][adg]\n", 23 "- [Application Developers' Guide on `", stringify!($func), "`][adg]\n",
24 $crate::linklist!($func: $($rest),*) 24 $crate::_doc::linklist!($func: $($rest),*)
25 ) 25 )
26 }; 26 };
27 ($func:ident: mwg$(, $rest:ident)*) => { 27 ($func:ident: mwg$(, $rest:ident)*) => {
28 concat!( 28 concat!(
29 "- [Module Writers' Guide on `", stringify!($func), "`][mwg]\n", 29 "- [Module Writers' Guide on `", stringify!($func), "`][mwg]\n",
30 $crate::linklist!($func: $($rest),*) 30 $crate::_doc::linklist!($func: $($rest),*)
31 ) 31 )
32 }; 32 };
33 ($func:ident: _std$(, $rest:ident)*) => { 33 ($func:ident: _std$(, $rest:ident)*) => {
34 $crate::linklist!($func: man7, manbsd, xsso$(, $rest)*) 34 $crate::_doc::linklist!($func: man7, manbsd, xsso$(, $rest)*)
35 }; 35 };
36 ($func:ident: man7$(, $rest:ident)*) => { 36 ($func:ident: man7$(, $rest:ident)*) => {
37 concat!( 37 concat!(
38 "- [Linux-PAM manpage for `", stringify!($func), "`][man7]\n", 38 "- [Linux-PAM manpage for `", stringify!($func), "`][man7]\n",
39 $crate::linklist!($func: $($rest),*) 39 $crate::_doc::linklist!($func: $($rest),*)
40 ) 40 )
41 }; 41 };
42 ($func:ident: manbsd$(, $rest:ident)*) => { 42 ($func:ident: manbsd$(, $rest:ident)*) => {
43 concat!( 43 concat!(
44 "- [OpenPAM manpage for `", stringify!($func), "`][manbsd]\n", 44 "- [OpenPAM manpage for `", stringify!($func), "`][manbsd]\n",
45 $crate::linklist!($func: $($rest),*) 45 $crate::_doc::linklist!($func: $($rest),*)
46 ) 46 )
47 }; 47 };
48 ($func:ident: xsso$(, $rest:ident)*) => { 48 ($func:ident: xsso$(, $rest:ident)*) => {
49 concat!( 49 concat!(
50 "- [X/SSO spec for `", stringify!($func), "`][xsso]", 50 "- [X/SSO spec for `", stringify!($func), "`][xsso]",
51 $crate::linklist!($func: $($rest),*) 51 $crate::_doc::linklist!($func: $($rest),*)
52 ) 52 )
53 }; 53 };
54 ($func:ident:$(,)?) => { "" }; 54 ($func:ident:$(,)?) => { "" };
55 } 55 }
56 56
79 /// Generates a Markdown link reference to the Linux man pages on man7.org. 79 /// Generates a Markdown link reference to the Linux man pages on man7.org.
80 /// 80 ///
81 /// # Examples 81 /// # Examples
82 /// 82 ///
83 /// ```ignore 83 /// ```ignore
84 /// # use nonstick::man7; 84 /// # use nonstick::_doc::man7;
85 /// /// This contains a [link to the man page for malloc][man7]. 85 /// /// This contains a [link to the man page for malloc][man7].
86 /// #[doc = man7!(3 malloc)] 86 /// #[doc = man7!(3 malloc)]
87 /// # fn do_whatever() {} 87 /// # fn do_whatever() {}
88 /// 88 ///
89 /// /// This contains both a link to the ["structure" section of `hgrc`][man7] 89 /// /// This contains both a link to the ["structure" section of `hgrc`][man7]
93 /// #[doc = man7!(systemd_env: 1 systemd "ENVIRONMENT")] 93 /// #[doc = man7!(systemd_env: 1 systemd "ENVIRONMENT")]
94 /// # fn do_whatever2() {} 94 /// # fn do_whatever2() {}
95 /// ``` 95 /// ```
96 macro_rules! man7 { 96 macro_rules! man7 {
97 ($n:literal $fn:ident $($anchor:literal)?) => { 97 ($n:literal $fn:ident $($anchor:literal)?) => {
98 $crate::man7!(man7: $n $fn $($anchor)?) 98 $crate::_doc::man7!(man7: $n $fn $($anchor)?)
99 }; 99 };
100 ($name:ident: $n:literal $fn:ident $($anchor:literal)?) => { 100 ($name:ident: $n:literal $fn:ident $($anchor:literal)?) => {
101 concat!( 101 concat!(
102 "[", stringify!($name), "]: ", 102 "[", stringify!($name), "]: ",
103 "https://man7.org/linux/man-pages/man", $n, "/", 103 "https://man7.org/linux/man-pages/man", $n, "/",
109 /// Generates a Markdown link reference to the NetBSD man pages. 109 /// Generates a Markdown link reference to the NetBSD man pages.
110 /// 110 ///
111 /// # Examples 111 /// # Examples
112 /// 112 ///
113 /// ```ignore 113 /// ```ignore
114 /// # use nonstick::manbsd; 114 /// # use nonstick::_doc::manbsd;
115 /// // Both of these formulations create a link named `manbsd`. 115 /// // Both of these formulations create a link named `manbsd`.
116 /// #[doc = manbsd!(3 fn_name)] 116 /// #[doc = manbsd!(3 fn_name)]
117 /// #[doc = manbsd!(5 thing_name "SECTION")] 117 /// #[doc = manbsd!(5 thing_name "SECTION")]
118 /// // This one creates a link named `link_name`. 118 /// // This one creates a link named `link_name`.
119 /// #[doc = manbsd!(link_name: 1 prog_name "SECTION")] 119 /// #[doc = manbsd!(link_name: 1 prog_name "SECTION")]
120 /// # fn do_whatever() {} 120 /// # fn do_whatever() {}
121 /// ``` 121 /// ```
122 macro_rules! manbsd { 122 macro_rules! manbsd {
123 ($n:literal $func:ident $($anchor:literal)?) => { 123 ($n:literal $func:ident $($anchor:literal)?) => {
124 $crate::manbsd!(manbsd: $n $func $($anchor)?) 124 $crate::_doc::manbsd!(manbsd: $n $func $($anchor)?)
125 }; 125 };
126 ($name:ident: $n:literal $func:ident $($anchor:literal)?) => { 126 ($name:ident: $n:literal $func:ident $($anchor:literal)?) => {
127 concat!("[", stringify!($name), "]: ", 127 concat!("[", stringify!($name), "]: ",
128 "https://man.netbsd.org/", stringify!($func), ".", $n, 128 "https://man.netbsd.org/", stringify!($func), ".", $n,
129 $("#", $anchor)? 129 $("#", $anchor)?
134 /// Generates a Markdown link reference to the X/SSO specification. 134 /// Generates a Markdown link reference to the X/SSO specification.
135 /// 135 ///
136 /// # Examples 136 /// # Examples
137 /// 137 ///
138 /// ```ignore 138 /// ```ignore
139 /// # use nonstick::xsso; 139 /// # use nonstick::_doc::xsso;
140 /// /// This docstring will [link to the X/SSO spec for `pam_set_item`][xsso]. 140 /// /// This docstring will [link to the X/SSO spec for `pam_set_item`][xsso].
141 /// /// 141 /// ///
142 /// #[doc = xsso!(pam_set_item)] 142 /// #[doc = xsso!(pam_set_item)]
143 /// # fn link_one() {} 143 /// # fn link_one() {}
144 /// 144 ///
148 /// #[doc = xsso!("some_page.htm#section-id")] 148 /// #[doc = xsso!("some_page.htm#section-id")]
149 /// #[doc = xsso!(spec_toc: "toc.htm")] 149 /// #[doc = xsso!(spec_toc: "toc.htm")]
150 /// # fn do_whatever() {} 150 /// # fn do_whatever() {}
151 /// ``` 151 /// ```
152 macro_rules! xsso { 152 macro_rules! xsso {
153 ($func:ident) => { $crate::xsso!(xsso: concat!(stringify!($func), ".htm")) }; 153 ($func:ident) => { $crate::_doc::xsso!(xsso: concat!(stringify!($func), ".htm")) };
154 ($page:literal) => { $crate::xsso!(xsso: $page) }; 154 ($page:literal) => { $crate::_doc::xsso!(xsso: $page) };
155 ($name:ident: $page:expr) => { 155 ($name:ident: $page:expr) => {
156 concat!("[", stringify!($name), "]: https://pubs.opengroup.org/onlinepubs/8329799/", $page) 156 concat!("[", stringify!($name), "]: https://pubs.opengroup.org/onlinepubs/8329799/", $page)
157 }; 157 };
158 } 158 }
159 159
162 /// A shortcut to `man7!`, `manbsd!`, and `xsso!`. 162 /// A shortcut to `man7!`, `manbsd!`, and `xsso!`.
163 /// 163 ///
164 /// # Examples 164 /// # Examples
165 /// 165 ///
166 /// ```ignore 166 /// ```ignore
167 /// # use nonstick::stdlinks; 167 /// # use nonstick::_doc::stdlinks;
168 /// /// Check out [this][man7], [that][manbsd], or [the other][xsso]. 168 /// /// Check out [this][man7], [that][manbsd], or [the other][xsso].
169 /// /// 169 /// ///
170 /// #[doc = stdlinks!(3 pam_get_item)] 170 /// #[doc = stdlinks!(3 pam_get_item)]
171 /// # fn do_whatever() {} 171 /// # fn do_whatever() {}
172 /// ``` 172 /// ```
173 macro_rules! stdlinks { 173 macro_rules! stdlinks {
174 ($n:literal $func:ident) => { 174 ($n:literal $func:ident) => {
175 concat!($crate::man7!($n $func), "\n", $crate::manbsd!($n $func), "\n", $crate::xsso!($func)) 175 concat!(
176 $crate::_doc::man7!($n $func), "\n",
177 $crate::_doc::manbsd!($n $func), "\n",
178 $crate::_doc::xsso!($func))
176 }; 179 };
177 } 180 }
178 181
179 pub(crate) use {guide, linklist, man7, manbsd, stdlinks, xsso}; 182 pub(crate) use {guide, linklist, man7, manbsd, stdlinks, xsso};