Mercurial > crates > nonstick

comparison src/_doc.rs @ 116:a12706e42c9d default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Logging, macros, and building: - Changes logging API to accept the `Location` of the log statement. Fixes OpenPAM implementation. - Stops publicly exporting doc macros. - Uses dlopen to detect the PAM library rather than header jankery.
author Paul Fisher <paul@pfish.zone>
date Sun, 29 Jun 2025 18:27:51 -0400
parents 49d9e2b5c189
children
comparison
equal deleted inserted replaced
115:1e11a52b4665 116:a12706e42c9d
4 /// 4 ///
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 /// ``` 9 /// ```ignore
10 /// # use nonstick::{_linklist, _stdlinks}; 10 /// # use nonstick::{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:
16 /// /// 16 /// ///
17 /// #[doc = _stdlinks!(3 pam_get_authtok)] 17 /// #[doc = stdlinks!(3 pam_get_authtok)]
18 /// # fn do_whatever() {} 18 /// # fn do_whatever() {}
19 /// ``` 19 /// ```
20 #[macro_export] 20 macro_rules! linklist {
21 #[doc(hidden)]
22 macro_rules! _linklist {
23 ($func:ident: adg$(, $rest:ident)*) => { 21 ($func:ident: adg$(, $rest:ident)*) => {
24 concat!( 22 concat!(
25 "- [Application Developers' Guide on `", stringify!($func), "`][adg]\n", 23 "- [Application Developers' Guide on `", stringify!($func), "`][adg]\n",
26 $crate::_linklist!($func: $($rest),*) 24 $crate::linklist!($func: $($rest),*)
27 ) 25 )
28 }; 26 };
29 ($func:ident: mwg$(, $rest:ident)*) => { 27 ($func:ident: mwg$(, $rest:ident)*) => {
30 concat!( 28 concat!(
31 "- [Module Writers' Guide on `", stringify!($func), "`][mwg]\n", 29 "- [Module Writers' Guide on `", stringify!($func), "`][mwg]\n",
32 $crate::_linklist!($func: $($rest),*) 30 $crate::linklist!($func: $($rest),*)
33 ) 31 )
34 }; 32 };
35 ($func:ident: _std$(, $rest:ident)*) => { 33 ($func:ident: _std$(, $rest:ident)*) => {
36 $crate::_linklist!($func: man7, manbsd, xsso$(, $rest)*) 34 $crate::linklist!($func: man7, manbsd, xsso$(, $rest)*)
37 }; 35 };
38 ($func:ident: man7$(, $rest:ident)*) => { 36 ($func:ident: man7$(, $rest:ident)*) => {
39 concat!( 37 concat!(
40 "- [Linux-PAM manpage for `", stringify!($func), "`][man7]\n", 38 "- [Linux-PAM manpage for `", stringify!($func), "`][man7]\n",
41 $crate::_linklist!($func: $($rest),*) 39 $crate::linklist!($func: $($rest),*)
42 ) 40 )
43 }; 41 };
44 ($func:ident: manbsd$(, $rest:ident)*) => { 42 ($func:ident: manbsd$(, $rest:ident)*) => {
45 concat!( 43 concat!(
46 "- [OpenPAM manpage for `", stringify!($func), "`][manbsd]\n", 44 "- [OpenPAM manpage for `", stringify!($func), "`][manbsd]\n",
47 $crate::_linklist!($func: $($rest),*) 45 $crate::linklist!($func: $($rest),*)
48 ) 46 )
49 }; 47 };
50 ($func:ident: xsso$(, $rest:ident)*) => { 48 ($func:ident: xsso$(, $rest:ident)*) => {
51 concat!( 49 concat!(
52 "- [X/SSO spec for `", stringify!($func), "`][xsso]", 50 "- [X/SSO spec for `", stringify!($func), "`][xsso]",
53 $crate::_linklist!($func: $($rest),*) 51 $crate::linklist!($func: $($rest),*)
54 ) 52 )
55 }; 53 };
56 ($func:ident:$(,)?) => { "" }; 54 ($func:ident:$(,)?) => { "" };
57 } 55 }
58 56
59 /// Generates a Markdown link reference to one of the PAM guides. 57 /// Generates a Markdown link reference to one of the PAM guides.
60 /// 58 ///
61 /// # Examples 59 /// # Examples
62 /// 60 ///
63 /// ``` 61 /// ```ignore
64 /// # use nonstick::{_guide}; 62 /// # use nonstick::{guide};
65 /// /// See [the guide][mwg]. 63 /// /// See [the guide][mwg].
66 /// /// 64 /// ///
67 /// #[doc = _guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_user")] 65 /// #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_user")]
68 /// # fn do_whatever() {} 66 /// # fn do_whatever() {}
69 /// ``` 67 /// ```
70 #[macro_export] 68 macro_rules! guide {
71 #[doc(hidden)]
72 macro_rules! _guide {
73 ($name:ident: $page_link:literal) => { 69 ($name:ident: $page_link:literal) => {
74 concat!( 70 concat!(
75 "[", 71 "[",
76 stringify!($name), 72 stringify!($name),
77 "]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/", 73 "]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/",
82 78
83 /// 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.
84 /// 80 ///
85 /// # Examples 81 /// # Examples
86 /// 82 ///
87 /// ``` 83 /// ```ignore
88 /// # use nonstick::_man7; 84 /// # use nonstick::man7;
89 /// /// This contains a [link to the man page for malloc][man7]. 85 /// /// This contains a [link to the man page for malloc][man7].
90 /// #[doc = _man7!(3 malloc)] 86 /// #[doc = man7!(3 malloc)]
91 /// # fn do_whatever() {} 87 /// # fn do_whatever() {}
92 /// 88 ///
93 /// /// 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]
94 /// /// and a link to the ["environment" section of `systemd`][sysd_env]. 90 /// /// and a link to the ["environment" section of `systemd`][sysd_env].
95 /// /// 91 /// ///
96 /// #[doc = _man7!(5 hgrc "STRUCTURE")] 92 /// #[doc = man7!(5 hgrc "STRUCTURE")]
97 /// #[doc = _man7!(sysd_env: 1 systemd "ENVIRONMENT")] 93 /// #[doc = man7!(sysd_env: 1 systemd "ENVIRONMENT")]
98 /// # fn do_whatever2() {} 94 /// # fn do_whatever2() {}
99 /// ``` 95 /// ```
100 #[macro_export] 96 macro_rules! man7 {
101 #[doc(hidden)]
102 macro_rules! _man7 {
103 ($n:literal $fn:ident $($anchor:literal)?) => { 97 ($n:literal $fn:ident $($anchor:literal)?) => {
104 $crate::_man7!(man7: $n $fn $($anchor)?) 98 $crate::man7!(man7: $n $fn $($anchor)?)
105 }; 99 };
106 ($name:ident: $n:literal $fn:ident $($anchor:literal)?) => { 100 ($name:ident: $n:literal $fn:ident $($anchor:literal)?) => {
107 concat!( 101 concat!(
108 "[", stringify!($name), "]: ", 102 "[", stringify!($name), "]: ",
109 "https://man7.org/linux/man-pages/man", $n, "/", 103 "https://man7.org/linux/man-pages/man", $n, "/",
114 108
115 /// Generates a Markdown link reference to the NetBSD man pages. 109 /// Generates a Markdown link reference to the NetBSD man pages.
116 /// 110 ///
117 /// # Examples 111 /// # Examples
118 /// 112 ///
119 /// ``` 113 /// ```ignore
120 /// # use nonstick::_manbsd; 114 /// # use nonstick::manbsd;
121 /// // Both of these formulations create a link named `manbsd`. 115 /// // Both of these formulations create a link named `manbsd`.
122 /// #[doc = _manbsd!(3 fn_name)] 116 /// #[doc = manbsd!(3 fn_name)]
123 /// #[doc = _manbsd!(5 thing_name "SECTION")] 117 /// #[doc = manbsd!(5 thing_name "SECTION")]
124 /// // This one creates a link named `link_name`. 118 /// // This one creates a link named `link_name`.
125 /// #[doc = _manbsd!(link_name: 1 prog_name "SECTION")] 119 /// #[doc = manbsd!(link_name: 1 prog_name "SECTION")]
126 /// # fn do_whatever() {} 120 /// # fn do_whatever() {}
127 /// ``` 121 /// ```
128 #[macro_export] 122 macro_rules! manbsd {
129 #[doc(hidden)]
130 macro_rules! _manbsd {
131 ($n:literal $func:ident $($anchor:literal)?) => { 123 ($n:literal $func:ident $($anchor:literal)?) => {
132 $crate::_manbsd!(manbsd: $n $func $($anchor)?) 124 $crate::manbsd!(manbsd: $n $func $($anchor)?)
133 }; 125 };
134 ($name:ident: $n:literal $func:ident $($anchor:literal)?) => { 126 ($name:ident: $n:literal $func:ident $($anchor:literal)?) => {
135 concat!("[", stringify!($name), "]: ", 127 concat!("[", stringify!($name), "]: ",
136 "https://man.netbsd.org/", stringify!($func), ".", $n, 128 "https://man.netbsd.org/", stringify!($func), ".", $n,
137 $("#", $anchor)? 129 $("#", $anchor)?
141 133
142 /// Generates a Markdown link reference to the X/SSO specification. 134 /// Generates a Markdown link reference to the X/SSO specification.
143 /// 135 ///
144 /// # Examples 136 /// # Examples
145 /// 137 ///
146 /// ``` 138 /// ```ignore
147 /// # use nonstick::_xsso; 139 /// # use nonstick::xsso;
148 /// /// 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].
149 /// /// 141 /// ///
150 /// #[doc = _xsso!(pam_set_item)] 142 /// #[doc = xsso!(pam_set_item)]
151 /// # fn link_one() {} 143 /// # fn link_one() {}
152 /// 144 ///
153 /// /// This docstring will link to [`some_page`][xsso]. 145 /// /// This docstring will link to [`some_page`][xsso].
154 /// /// I can also link to [the table of contents][spec_toc]. 146 /// /// I can also link to [the table of contents][spec_toc].
155 /// /// 147 /// ///
156 /// #[doc = _xsso!("some_page.htm#section-id")] 148 /// #[doc = xsso!("some_page.htm#section-id")]
157 /// #[doc = _xsso!(spec_toc: "toc.htm")] 149 /// #[doc = xsso!(spec_toc: "toc.htm")]
158 /// # fn do_whatever() {} 150 /// # fn do_whatever() {}
159 /// ``` 151 /// ```
160 #[macro_export] 152 macro_rules! xsso {
161 #[doc(hidden)] 153 ($func:ident) => { $crate::xsso!(xsso: concat!(stringify!($func), ".htm")) };
162 macro_rules! _xsso { 154 ($page:literal) => { $crate::xsso!(xsso: $page) };
163 ($func:ident) => { $crate::_xsso!(xsso: concat!(stringify!($func), ".htm")) };
164 ($page:literal) => { $crate::_xsso!(xsso: $page) };
165 ($name:ident: $page:expr) => { 155 ($name:ident: $page:expr) => {
166 concat!("[", stringify!($name), "]: https://pubs.opengroup.org/onlinepubs/8329799/", $page) 156 concat!("[", stringify!($name), "]: https://pubs.opengroup.org/onlinepubs/8329799/", $page)
167 }; 157 };
168 } 158 }
169 159
170 /// Generates Markdown link references to Linux-PAM, OpenPAM, and X/SSO. 160 /// Generates Markdown link references to Linux-PAM, OpenPAM, and X/SSO.
171 /// 161 ///
172 /// A shortcut to `_man7!`, `_manbsd!`, and `_xsso!`. 162 /// A shortcut to `man7!`, `manbsd!`, and `xsso!`.
173 /// 163 ///
174 /// # Examples 164 /// # Examples
175 /// 165 ///
176 /// ``` 166 /// ```ignore
177 /// # use nonstick::_stdlinks; 167 /// # use nonstick::stdlinks;
178 /// /// Check out [this][man7], [that][manbsd], or [the other][xsso]. 168 /// /// Check out [this][man7], [that][manbsd], or [the other][xsso].
179 /// /// 169 /// ///
180 /// #[doc = _stdlinks!(3 pam_get_item)] 170 /// #[doc = stdlinks!(3 pam_get_item)]
181 /// # fn do_whatever() {} 171 /// # fn do_whatever() {}
182 /// ``` 172 /// ```
183 #[macro_export] 173 macro_rules! stdlinks {
184 #[doc(hidden)]
185 macro_rules! _stdlinks {
186 ($n:literal $func:ident) => { 174 ($n:literal $func:ident) => {
187 concat!($crate::_man7!($n $func), "\n", $crate::_manbsd!($n $func), "\n", $crate::_xsso!($func)) 175 concat!($crate::man7!($n $func), "\n", $crate::manbsd!($n $func), "\n", $crate::xsso!($func))
188 }; 176 };
189 } 177 }
178
179 pub(crate) use {linklist, guide, man7, manbsd, xsso, stdlinks};