Mercurial > crates > nonstick

comparison src/_doc.rs @ 105:13b4d2a19674

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Support Rust v1.75.0. This is the version included in Ubuntu 24.04 LTS and Debian Trixie, so it's old enough to have wide penetration without being too old to get new features (Debian Stable, I love you but v1.63 is just not going to work out).
author Paul Fisher <paul@pfish.zone>
date Thu, 26 Jun 2025 00:48:51 -0400
parents dfcd96a74ac4
children 49d9e2b5c189
comparison
equal deleted inserted replaced
104:a2676475e86b 105:13b4d2a19674
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 /// ```
10 /// # use nonstick::{_linklist, _stdlinks};
11 /// /// Here is a list of links:
12 /// ///
10 /// #[doc = _linklist!(pam_get_authtok: man7, manbsd)] 13 /// #[doc = _linklist!(pam_get_authtok: man7, manbsd)]
11 /// /// 14 /// ///
12 /// /// ...use it with link references, like the below... 15 /// /// The links are defined in the `stdlinks!` invocation below:
13 /// /// 16 /// ///
14 /// #[doc = _stdlinks!(3 pam_get_authtok)] 17 /// #[doc = _stdlinks!(3 pam_get_authtok)]
18 /// # fn do_whatever() {}
15 /// ``` 19 /// ```
16 #[macro_export] 20 #[macro_export]
17 #[doc(hidden)] 21 #[doc(hidden)]
18 macro_rules! _linklist { 22 macro_rules! _linklist {
19 ($func:ident: adg$(, $rest:ident)*) => { 23 ($func:ident: adg$(, $rest:ident)*) => {
55 /// Generates a Markdown link reference to one of the PAM guides. 59 /// Generates a Markdown link reference to one of the PAM guides.
56 /// 60 ///
57 /// # Examples 61 /// # Examples
58 /// 62 ///
59 /// ``` 63 /// ```
64 /// # use nonstick::{_guide};
65 /// /// See [the guide][mwg].
66 /// ///
60 /// #[doc = _guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_user")] 67 /// #[doc = _guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_user")]
68 /// # fn do_whatever() {}
61 /// ``` 69 /// ```
62 #[macro_export] 70 #[macro_export]
63 #[doc(hidden)] 71 #[doc(hidden)]
64 macro_rules! _guide { 72 macro_rules! _guide {
65 ($name:ident: $page_link:literal) => { 73 ($name:ident: $page_link:literal) => {
75 /// Generates a Markdown link reference to the Linux man pages on man7.org. 83 /// Generates a Markdown link reference to the Linux man pages on man7.org.
76 /// 84 ///
77 /// # Examples 85 /// # Examples
78 /// 86 ///
79 /// ``` 87 /// ```
80 /// // Both of these formulations create a link reference named `man7`. 88 /// # use nonstick::_man7;
81 /// #[doc = _man7!(3 fn_name)] 89 /// /// This contains a [link to the man page for malloc][man7].
82 /// #[doc = _man7!(5 thing_name "SECTION")] 90 /// #[doc = _man7!(3 malloc)]
83 /// // This one creates a link reference named `link_name`. 91 /// # fn do_whatever() {}
84 /// #[doc = _man7!(link_name: 1 prog_name "SECTION")] 92 ///
93 /// /// This contains both a link to the ["structure" section of `hgrc`][man7]
94 /// /// and a link to the ["environment" section of `systemd`][sysd_env].
95 /// ///
96 /// #[doc = _man7!(5 hgrc "STRUCTURE")]
97 /// #[doc = _man7!(sysd_env: 1 systemd "ENVIRONMENT")]
98 /// # fn do_whatever2() {}
85 /// ``` 99 /// ```
86 #[macro_export] 100 #[macro_export]
87 #[doc(hidden)] 101 #[doc(hidden)]
88 macro_rules! _man7 { 102 macro_rules! _man7 {
89 ($n:literal $fn:ident $($anchor:literal)?) => { 103 ($n:literal $fn:ident $($anchor:literal)?) => {
101 /// Generates a Markdown link reference to the NetBSD man pages. 115 /// Generates a Markdown link reference to the NetBSD man pages.
102 /// 116 ///
103 /// # Examples 117 /// # Examples
104 /// 118 ///
105 /// ``` 119 /// ```
120 /// # use nonstick::_manbsd;
106 /// // Both of these formulations create a link named `manbsd`. 121 /// // Both of these formulations create a link named `manbsd`.
107 /// #[doc = _manbsd!(3 fn_name)] 122 /// #[doc = _manbsd!(3 fn_name)]
108 /// #[doc = _manbsd!(5 thing_name "SECTION")] 123 /// #[doc = _manbsd!(5 thing_name "SECTION")]
109 /// // This one creates a link named `link_name`. 124 /// // This one creates a link named `link_name`.
110 /// #[doc = _manbsd!(link_name: 1 prog_name "SECTION")] 125 /// #[doc = _manbsd!(link_name: 1 prog_name "SECTION")]
126 /// # fn do_whatever() {}
111 /// ``` 127 /// ```
112 #[macro_export] 128 #[macro_export]
113 #[doc(hidden)] 129 #[doc(hidden)]
114 macro_rules! _manbsd { 130 macro_rules! _manbsd {
115 ($n:literal $func:ident $($anchor:literal)?) => { 131 ($n:literal $func:ident $($anchor:literal)?) => {
126 /// Generates a Markdown link reference to the X/SSO specification. 142 /// Generates a Markdown link reference to the X/SSO specification.
127 /// 143 ///
128 /// # Examples 144 /// # Examples
129 /// 145 ///
130 /// ``` 146 /// ```
131 /// // Both of these formulations create a link reference named `xsso`. 147 /// # use nonstick::_xsso;
132 /// // A link to the X/SSO specification for the `pam_set_item` function. 148 /// /// This docstring will [link to the X/SSO spec for `pam_set_item`][xsso].
149 /// ///
133 /// #[doc = _xsso!(pam_set_item)] 150 /// #[doc = _xsso!(pam_set_item)]
134 /// // A link to the HTML page with the given name. 151 /// # fn link_one() {}
152 ///
153 /// /// This docstring will link to [`some_page`][xsso].
154 /// /// I can also link to [the table of contents][spec_toc].
155 /// ///
135 /// #[doc = _xsso!("some_page.htm#section-id")] 156 /// #[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")] 157 /// #[doc = _xsso!(spec_toc: "toc.htm")]
158 /// # fn do_whatever() {}
139 /// ``` 159 /// ```
140 #[macro_export] 160 #[macro_export]
141 #[doc(hidden)] 161 #[doc(hidden)]
142 macro_rules! _xsso { 162 macro_rules! _xsso {
143 ($func:ident) => { $crate::_xsso!(xsso: concat!(stringify!($func), ".htm")) }; 163 ($func:ident) => { $crate::_xsso!(xsso: concat!(stringify!($func), ".htm")) };
152 /// A shortcut to `_man7!`, `_manbsd!`, and `_xsso!`. 172 /// A shortcut to `_man7!`, `_manbsd!`, and `_xsso!`.
153 /// 173 ///
154 /// # Examples 174 /// # Examples
155 /// 175 ///
156 /// ``` 176 /// ```
177 /// # use nonstick::_stdlinks;
178 /// /// Check out [this][man7], [that][manbsd], or [the other][xsso].
179 /// ///
157 /// #[doc = _stdlinks!(3 pam_get_item)] 180 /// #[doc = _stdlinks!(3 pam_get_item)]
181 /// # fn do_whatever() {}
158 /// ``` 182 /// ```
159 #[macro_export] 183 #[macro_export]
160 #[doc(hidden)] 184 #[doc(hidden)]
161 macro_rules! _stdlinks { 185 macro_rules! _stdlinks {
162 ($n:literal $func:ident) => { 186 ($n:literal $func:ident) => {