Mercurial > crates > nonstick

comparison src/_doc.rs @ 171:e27c5c667a5a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Create full new types for return code and flags, separate end to end. This plumbs the ReturnCode and RawFlags types through the places where we call into or are called from PAM. Also adds Sun documentation to the project.
author Paul Fisher <paul@pfish.zone>
date Fri, 25 Jul 2025 20:52:14 -0400
parents 1bc52025156b
children 9e4ce1631bd3
comparison
equal deleted inserted replaced
170:f052e2417195 171:e27c5c667a5a
29 "- [Module Writers' Guide on `", stringify!($func), "`][mwg]\n", 29 "- [Module Writers' Guide on `", stringify!($func), "`][mwg]\n",
30 $crate::_doc::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::_doc::linklist!($func: man7, manbsd, xsso$(, $rest)*) 34 $crate::_doc::linklist!($func: man7, manbsd, mansun, 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::_doc::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::_doc::linklist!($func: $($rest),*)
46 )
47 };
48 ($func:ident: mansun$(, $rest:ident)*) => {
49 concat!(
50 "- [Illumos manpage for `", stringify!($func), "`][mansun]\n",
45 $crate::_doc::linklist!($func: $($rest),*) 51 $crate::_doc::linklist!($func: $($rest),*)
46 ) 52 )
47 }; 53 };
48 ($func:ident: xsso$(, $rest:ident)*) => { 54 ($func:ident: xsso$(, $rest:ident)*) => {
49 concat!( 55 concat!(
129 $("#", $anchor)? 135 $("#", $anchor)?
130 ) 136 )
131 }; 137 };
132 } 138 }
133 139
140 /// Generates a Markdown link reference to the SmartOS man pages.
141 ///
142 /// # Examples
143 ///
144 /// ```ignore
145 /// # use nonstick::_doc::mansun;
146 /// // Both of these formulations create a link named `manbsd`.
147 /// #[doc = mansun!(3pam fn_name)]
148 /// #[doc = mansun!(5 "a.out" "synopsis")]
149 /// // This one creates a link named `link_name`.
150 /// #[doc = mansun!(link_name: 1 alias "examples")]
151 /// # fn do_whatever() {}
152 /// ```
153 macro_rules! mansun {
154 ($n:literal $func:ident $($anchor:literal)?) => {
155 $crate::_doc::mansun!(mansun: [$n ""] $func $($anchor)?)
156 };
157 ([$n:literal $sect:literal] $func:ident $($anchor:literal)?) => {
158 $crate::_doc::mansun!(mansun: [$n $sect] $func $($anchor)?)
159 };
160 ($name:ident: $n:literal $func:ident $($anchor:literal)?) => {
161 $crate::_doc::mansun!($name: [$n ""] $func $($anchor)?)
162 };
163 ($name:ident: [$n:literal $sect:literal] $func:ident $($anchor:literal)?) => {
164 $crate::_doc::mansun!($name: [$n $sect] (stringify!($func)) $($anchor)?)
165 };
166 ($name:ident: [$n:literal $sect:literal] ($func:expr) $($anchor:literal)?) => {
167 concat!("[", stringify!($name), "]: ",
168 "https://smartos.org/man/", $n, $sect, "/", $func,
169 $("#", $anchor)?
170 )
171 };
172 }
173
134 /// Generates a Markdown link reference to the X/SSO specification. 174 /// Generates a Markdown link reference to the X/SSO specification.
135 /// 175 ///
136 /// # Examples 176 /// # Examples
137 /// 177 ///
138 /// ```ignore 178 /// ```ignore
173 macro_rules! stdlinks { 213 macro_rules! stdlinks {
174 ($n:literal $func:ident) => { 214 ($n:literal $func:ident) => {
175 concat!( 215 concat!(
176 $crate::_doc::man7!($n $func), "\n", 216 $crate::_doc::man7!($n $func), "\n",
177 $crate::_doc::manbsd!($n $func), "\n", 217 $crate::_doc::manbsd!($n $func), "\n",
218 $crate::_doc::mansun!([$n "pam"] $func), "\n",
178 $crate::_doc::xsso!($func)) 219 $crate::_doc::xsso!($func))
179 }; 220 };
180 } 221 }
181 222
182 pub(crate) use {guide, linklist, man7, manbsd, stdlinks, xsso}; 223 pub(crate) use {guide, linklist, man7, manbsd, mansun, stdlinks, xsso};