Mercurial > crates > nonstick

annotate 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
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 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
9 /// ```ignore
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
10 /// # use nonstick::{linklist, stdlinks};
105
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 /// ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
13 /// #[doc = linklist!(pam_get_authtok: man7, manbsd)]
103
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 /// ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
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 /// ```
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
20 macro_rules! linklist {
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
21 ($func:ident: adg$(, $rest:ident)*) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
22 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
23 "- [Application Developers' Guide on `", stringify!($func), "`][adg]\n",
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
24 $crate::linklist!($func: $($rest),*)
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
25 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
26 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
27 ($func:ident: mwg$(, $rest:ident)*) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
28 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
29 "- [Module Writers' Guide on `", stringify!($func), "`][mwg]\n",
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
30 $crate::linklist!($func: $($rest),*)
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
31 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
32 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
33 ($func:ident: _std$(, $rest:ident)*) => {
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
34 $crate::linklist!($func: man7, manbsd, xsso$(, $rest)*)
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
35 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
36 ($func:ident: man7$(, $rest:ident)*) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
37 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
38 "- [Linux-PAM manpage for `", stringify!($func), "`][man7]\n",
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
39 $crate::linklist!($func: $($rest),*)
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
40 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
41 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
42 ($func:ident: manbsd$(, $rest:ident)*) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
43 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
44 "- [OpenPAM manpage for `", stringify!($func), "`][manbsd]\n",
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
45 $crate::linklist!($func: $($rest),*)
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
46 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
47 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
48 ($func:ident: xsso$(, $rest:ident)*) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
49 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
50 "- [X/SSO spec for `", stringify!($func), "`][xsso]",
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
51 $crate::linklist!($func: $($rest),*)
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
52 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
53 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
54 ($func:ident:$(,)?) => { "" };
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
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
57 /// 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
58 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
59 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
60 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
61 /// ```ignore
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
62 /// # use nonstick::{guide};
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
63 /// /// See [the guide][mwg].
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
64 /// ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
65 /// #[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
66 /// # fn do_whatever() {}
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
67 /// ```
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
68 macro_rules! guide {
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
69 ($name:ident: $page_link:literal) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
70 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
71 "[",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
72 stringify!($name),
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
73 "]: 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
74 $page_link
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 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
77 }
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
78
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
79 /// 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
80 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
81 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
82 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
83 /// ```ignore
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
84 /// # use nonstick::man7;
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
85 /// /// This contains a [link to the man page for malloc][man7].
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
86 /// #[doc = man7!(3 malloc)]
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
87 /// # fn do_whatever() {}
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
88 ///
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
89 /// /// 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
90 /// /// 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
91 /// ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
92 /// #[doc = man7!(5 hgrc "STRUCTURE")]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
93 /// #[doc = man7!(sysd_env: 1 systemd "ENVIRONMENT")]
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
94 /// # fn do_whatever2() {}
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
95 /// ```
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
96 macro_rules! man7 {
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
97 ($n:literal $fn:ident $($anchor:literal)?) => {
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
98 $crate::man7!(man7: $n $fn $($anchor)?)
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 ($name:ident: $n:literal $fn:ident $($anchor:literal)?) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
101 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
102 "[", stringify!($name), "]: ",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
103 "https://man7.org/linux/man-pages/man", $n, "/",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
104 stringify!($fn), ".", $n, ".html", $("#", $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 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
107 }
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
108
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
109 /// 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
110 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
111 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
112 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
113 /// ```ignore
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
114 /// # use nonstick::manbsd;
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
115 /// // Both of these formulations create a link named `manbsd`.
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
116 /// #[doc = manbsd!(3 fn_name)]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
117 /// #[doc = manbsd!(5 thing_name "SECTION")]
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
118 /// // This one creates a link named `link_name`.
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
119 /// #[doc = manbsd!(link_name: 1 prog_name "SECTION")]
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
120 /// # fn do_whatever() {}
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
121 /// ```
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
122 macro_rules! manbsd {
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
123 ($n:literal $func:ident $($anchor:literal)?) => {
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
124 $crate::manbsd!(manbsd: $n $func $($anchor)?)
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
125 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
126 ($name:ident: $n:literal $func:ident $($anchor:literal)?) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
127 concat!("[", stringify!($name), "]: ",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
128 "https://man.netbsd.org/", stringify!($func), ".", $n,
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
129 $("#", $anchor)?
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
130 )
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
131 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
132 }
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 /// 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
135 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
136 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
137 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
138 /// ```ignore
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
139 /// # use nonstick::xsso;
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
140 /// /// 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
141 /// ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
142 /// #[doc = xsso!(pam_set_item)]
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
143 /// # fn link_one() {}
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents: 105
diff changeset
144 ///
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
145 /// /// This docstring will link to [`some_page`][xsso].
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
146 /// /// 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
147 /// ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
148 /// #[doc = xsso!("some_page.htm#section-id")]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
149 /// #[doc = xsso!(spec_toc: "toc.htm")]
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
150 /// # fn do_whatever() {}
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
151 /// ```
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
152 macro_rules! xsso {
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
153 ($func:ident) => { $crate::xsso!(xsso: concat!(stringify!($func), ".htm")) };
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
154 ($page:literal) => { $crate::xsso!(xsso: $page) };
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
155 ($name:ident: $page:expr) => {
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
156 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
157 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
158 }
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 /// 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
161 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
162 /// A shortcut to `man7!`, `manbsd!`, and `xsso!`.
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
163 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
164 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
165 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
166 /// ```ignore
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
167 /// # use nonstick::stdlinks;
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
168 /// /// 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
169 /// ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
170 /// #[doc = stdlinks!(3 pam_get_item)]
105
13b4d2a19674 Support Rust v1.75.0.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
171 /// # fn do_whatever() {}
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
172 /// ```
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
173 macro_rules! stdlinks {
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
174 ($n:literal $func:ident) => {
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
175 concat!($crate::man7!($n $func), "\n", $crate::manbsd!($n $func), "\n", $crate::xsso!($func))
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
176 };
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
177 }
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
178
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
179 pub(crate) use {linklist, guide, man7, manbsd, xsso, stdlinks};