Mercurial > crates > nonstick

annotate 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
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
1 //! A place to stick documentation stuff.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
2
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
3 /// Generates text lists of reference links for docs.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
4 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
5 /// Use this with the other doc macros for the correct link names.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
6 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
7 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
8 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
9 /// ```
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
10 /// # use nonstick::{_linklist, _stdlinks};
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
11 /// /// Here is a list of links:
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
12 /// ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
13 /// #[doc = _linklist!(pam_get_authtok: man7, manbsd)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
14 /// ///
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
15 /// /// The links are defined in the `stdlinks!` invocation below:
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
16 /// ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
17 /// #[doc = _stdlinks!(3 pam_get_authtok)]
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
18 /// # fn do_whatever() {}
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
19 /// ```
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
20 #[macro_export]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
21 #[doc(hidden)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
22 macro_rules! _linklist {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
23 ($func:ident: adg$(, $rest:ident)*) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
24 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
25 "- [Application Developers' Guide on `", stringify!($func), "`][adg]\n",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
26 $crate::_linklist!($func: $($rest),*)
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
27 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
28 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
29 ($func:ident: mwg$(, $rest:ident)*) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
30 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
31 "- [Module Writers' Guide on `", stringify!($func), "`][mwg]\n",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
32 $crate::_linklist!($func: $($rest),*)
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
33 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
34 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
35 ($func:ident: _std$(, $rest:ident)*) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
36 $crate::_linklist!($func: man7, manbsd, xsso$(, $rest)*)
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
37 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
38 ($func:ident: man7$(, $rest:ident)*) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
39 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
40 "- [Linux-PAM manpage for `", stringify!($func), "`][man7]\n",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
41 $crate::_linklist!($func: $($rest),*)
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
42 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
43 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
44 ($func:ident: manbsd$(, $rest:ident)*) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
45 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
46 "- [OpenPAM manpage for `", stringify!($func), "`][manbsd]\n",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
47 $crate::_linklist!($func: $($rest),*)
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
48 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
49 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
50 ($func:ident: xsso$(, $rest:ident)*) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
51 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
52 "- [X/SSO spec for `", stringify!($func), "`][xsso]",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
53 $crate::_linklist!($func: $($rest),*)
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
54 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
55 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
56 ($func:ident:$(,)?) => { "" };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
57 }
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
58
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
59 /// Generates a Markdown link reference to one of the PAM guides.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
60 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
61 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
62 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
63 /// ```
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
64 /// # use nonstick::{_guide};
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
65 /// /// See [the guide][mwg].
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
66 /// ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
67 /// #[doc = _guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_user")]
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
68 /// # fn do_whatever() {}
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
69 /// ```
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
70 #[macro_export]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
71 #[doc(hidden)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
72 macro_rules! _guide {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
73 ($name:ident: $page_link:literal) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
74 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
75 "[",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
76 stringify!($name),
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
77 "]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
78 $page_link
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
79 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
80 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
81 }
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
82
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
83 /// Generates a Markdown link reference to the Linux man pages on man7.org.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
84 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
85 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
86 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
87 /// ```
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
88 /// # use nonstick::_man7;
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
89 /// /// This contains a [link to the man page for malloc][man7].
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
90 /// #[doc = _man7!(3 malloc)]
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
91 /// # fn do_whatever() {}
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
92 ///
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
93 /// /// This contains both a link to the ["structure" section of `hgrc`][man7]
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
94 /// /// and a link to the ["environment" section of `systemd`][sysd_env].
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
95 /// ///
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
96 /// #[doc = _man7!(5 hgrc "STRUCTURE")]
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
97 /// #[doc = _man7!(sysd_env: 1 systemd "ENVIRONMENT")]
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
98 /// # fn do_whatever2() {}
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
99 /// ```
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
100 #[macro_export]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
101 #[doc(hidden)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
102 macro_rules! _man7 {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
103 ($n:literal $fn:ident $($anchor:literal)?) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
104 $crate::_man7!(man7: $n $fn $($anchor)?)
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
105 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
106 ($name:ident: $n:literal $fn:ident $($anchor:literal)?) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
107 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
108 "[", stringify!($name), "]: ",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
109 "https://man7.org/linux/man-pages/man", $n, "/",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
110 stringify!($fn), ".", $n, ".html", $("#", $anchor)?
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
111 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
112 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
113 }
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
114
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
115 /// Generates a Markdown link reference to the NetBSD man pages.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
116 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
117 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
118 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
119 /// ```
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
120 /// # use nonstick::_manbsd;
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
121 /// // Both of these formulations create a link named `manbsd`.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
122 /// #[doc = _manbsd!(3 fn_name)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
123 /// #[doc = _manbsd!(5 thing_name "SECTION")]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
124 /// // This one creates a link named `link_name`.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
125 /// #[doc = _manbsd!(link_name: 1 prog_name "SECTION")]
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
126 /// # fn do_whatever() {}
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
127 /// ```
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
128 #[macro_export]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
129 #[doc(hidden)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
130 macro_rules! _manbsd {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
131 ($n:literal $func:ident $($anchor:literal)?) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
132 $crate::_manbsd!(manbsd: $n $func $($anchor)?)
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
133 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
134 ($name:ident: $n:literal $func:ident $($anchor:literal)?) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
135 concat!("[", stringify!($name), "]: ",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
136 "https://man.netbsd.org/", stringify!($func), ".", $n,
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
137 $("#", $anchor)?
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
138 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
139 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
140 }
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
141
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
142 /// Generates a Markdown link reference to the X/SSO specification.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
143 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
144 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
145 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
146 /// ```
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
147 /// # use nonstick::_xsso;
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
148 /// /// This docstring will [link to the X/SSO spec for `pam_set_item`][xsso].
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
149 /// ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
150 /// #[doc = _xsso!(pam_set_item)]
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
151 /// # fn link_one() {}
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
152 ///
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
153 /// /// This docstring will link to [`some_page`][xsso].
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
154 /// /// I can also link to [the table of contents][spec_toc].
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
155 /// ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
156 /// #[doc = _xsso!("some_page.htm#section-id")]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
157 /// #[doc = _xsso!(spec_toc: "toc.htm")]
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
158 /// # fn do_whatever() {}
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
159 /// ```
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
160 #[macro_export]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
161 #[doc(hidden)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
162 macro_rules! _xsso {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
163 ($func:ident) => { $crate::_xsso!(xsso: concat!(stringify!($func), ".htm")) };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
164 ($page:literal) => { $crate::_xsso!(xsso: $page) };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
165 ($name:ident: $page:expr) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
166 concat!("[", stringify!($name), "]: https://pubs.opengroup.org/onlinepubs/8329799/", $page)
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
167 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
168 }
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
169
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
170 /// Generates Markdown link references to Linux-PAM, OpenPAM, and X/SSO.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
171 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
172 /// A shortcut to `_man7!`, `_manbsd!`, and `_xsso!`.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
173 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
174 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
175 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
176 /// ```
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
177 /// # use nonstick::_stdlinks;
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
178 /// /// Check out [this][man7], [that][manbsd], or [the other][xsso].
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
179 /// ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
180 /// #[doc = _stdlinks!(3 pam_get_item)]
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
181 /// # fn do_whatever() {}
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
182 /// ```
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
183 #[macro_export]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
184 #[doc(hidden)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
185 macro_rules! _stdlinks {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
186 ($n:literal $func:ident) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
187 concat!($crate::_man7!($n $func), "\n", $crate::_manbsd!($n $func), "\n", $crate::_xsso!($func))
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
188 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
189 }