crates/nonstick: src/_doc.rs annotate

annotate src/_doc.rs @ 189:b2456d274576 default tip

Add line breaks that rustfmt ate back to documentation.

author	Paul Fisher <paul@pfish.zone>
date	Thu, 31 Jul 2025 15:42:12 -0400
parents	9e4ce1631bd3
children

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
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	10 /// # use nonstick::_doc::{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",
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	24 $crate::_doc::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",
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	30 $crate::_doc::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)*) => {
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	34 $crate::_doc::linklist!($func: man7, manbsd, mansun, 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",
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	39 $crate::_doc::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",
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	45 $crate::_doc::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 };
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	48 ($func:ident: mansun$(, $rest:ident)*) => {
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	49 concat!(
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	50 "- [Illumos manpage for `", stringify!($func), "`][mansun]\n",
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	51 $crate::_doc::linklist!($func: $($rest),*)
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	52 )
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	53 };
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	54 ($func:ident: xsso$(, $rest:ident)*) => {
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	55 concat!(
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	56 "- [X/SSO spec for `", stringify!($func), "`][xsso]",
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	57 $crate::_doc::linklist!($func: $($rest),*)
103 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 };
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	60 ($func:ident:$(,)?) => { "" };
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	61 }
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 /// 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	64 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	65 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	66 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	67 /// ```ignore
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	68 /// # use nonstick::{guide};
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	69 /// /// See [the guide][mwg].
13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	70 /// ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	71 /// #[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	72 /// # fn do_whatever() {}
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	73 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	74 macro_rules! guide {
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	75 ($name:ident: $page_link:literal) => {
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	76 concat!(
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 stringify!($name),
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	79 "]: 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	80 $page_link
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 }
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 /// 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	86 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	87 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	88 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	89 /// ```ignore
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	90 /// # use nonstick::_doc::man7;
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	91 /// /// 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	92 /// #[doc = man7!(3 malloc)]
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	93 /// # fn do_whatever() {}
13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	94 ///
13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	95 /// /// This contains both a link to the ["structure" section of `hgrc`][man7]
142 5c1e315c18ff minor doc nicening Paul Fisher <paul@pfish.zone> parents: 118 diff changeset	96 /// /// and a link to the ["environment" section of `systemd`][systemd_env].
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	97 /// ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	98 /// #[doc = man7!(5 hgrc "STRUCTURE")]
142 5c1e315c18ff minor doc nicening Paul Fisher <paul@pfish.zone> parents: 118 diff changeset	99 /// #[doc = man7!(systemd_env: 1 systemd "ENVIRONMENT")]
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	100 /// # fn do_whatever2() {}
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	101 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	102 macro_rules! man7 {
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	103 ($n:literal $fn:ident $($anchor:literal)?) => {
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	104 $crate::_doc::man7!(man7: $n $fn $($anchor)?)
103 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 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	119 /// ```ignore
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	120 /// # use nonstick::_doc::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`.
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	122 /// #[doc = manbsd!(3 fn_name)]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	123 /// #[doc = manbsd!(5 thing_name "SECTION")]
103 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`.
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 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 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	128 macro_rules! manbsd {
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	129 ($n:literal $func:ident $($anchor:literal)?) => {
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	130 $crate::_doc::manbsd!(manbsd: $n $func $($anchor)?)
103 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 ($name:ident: $n:literal $func:ident $($anchor:literal)?) => {
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	133 concat!("[", stringify!($name), "]: ",
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	134 "https://man.netbsd.org/", stringify!($func), ".", $n,
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	135 $("#", $anchor)?
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	136 )
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	137 };
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
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	140 /// Generates a Markdown link reference to the SmartOS man pages.
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	141 ///
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	142 /// # Examples
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	143 ///
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	144 /// ```ignore
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	145 /// # use nonstick::_doc::mansun;
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 171 diff changeset	146 /// // Both of these formulations create a link named `mansun`.
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	147 /// #[doc = mansun!(3pam fn_name)]
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	148 /// #[doc = mansun!(5 "a.out" "synopsis")]
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	149 /// // This one creates a link named `link_name`.
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	150 /// #[doc = mansun!(link_name: 1 alias "examples")]
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	151 /// # fn do_whatever() {}
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	152 /// ```
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	153 macro_rules! mansun {
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	154 ($n:literal $func:ident $($anchor:literal)?) => {
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	155 $crate::_doc::mansun!(mansun: [$n ""] $func $($anchor)?)
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	156 };
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 171 diff changeset	157 ($n:literal $func:literal $($anchor:literal)?) => {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 171 diff changeset	158 $crate::_doc::mansun!(mansun: [$n ""] $func $($anchor)?)
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 171 diff changeset	159 };
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	160 ([$n:literal $sect:literal] $func:ident $($anchor:literal)?) => {
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	161 $crate::_doc::mansun!(mansun: [$n $sect] $func $($anchor)?)
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	162 };
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	163 ($name:ident: $n:literal $func:ident $($anchor:literal)?) => {
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	164 $crate::_doc::mansun!($name: [$n ""] $func $($anchor)?)
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	165 };
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 171 diff changeset	166 ($name:ident: $n:literal $func:literal $($anchor:literal)?) => {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 171 diff changeset	167 $crate::_doc::mansun!($name: [$n ""] ($func) $($anchor)?)
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 171 diff changeset	168 };
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	169 ($name:ident: [$n:literal $sect:literal] $func:ident $($anchor:literal)?) => {
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	170 $crate::_doc::mansun!($name: [$n $sect] (stringify!($func)) $($anchor)?)
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	171 };
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	172 ($name:ident: [$n:literal $sect:literal] ($func:expr) $($anchor:literal)?) => {
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	173 concat!("[", stringify!($name), "]: ",
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	174 "https://smartos.org/man/", $n, $sect, "/", $func,
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	175 $("#", $anchor)?
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	176 )
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	177 };
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	178 }
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	179
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	180 /// 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	181 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	182 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	183 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	184 /// ```ignore
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	185 /// # use nonstick::_doc::xsso;
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	186 /// /// 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	187 /// ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	188 /// #[doc = xsso!(pam_set_item)]
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	189 /// # fn link_one() {}
106 49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff. Paul Fisher <paul@pfish.zone> parents: 105 diff changeset	190 ///
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	191 /// /// This docstring will link to [`some_page`][xsso].
13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	192 /// /// 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	193 /// ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	194 /// #[doc = xsso!("some_page.htm#section-id")]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	195 /// #[doc = xsso!(spec_toc: "toc.htm")]
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	196 /// # fn do_whatever() {}
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	197 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	198 macro_rules! xsso {
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	199 ($func:ident) => { $crate::_doc::xsso!(xsso: concat!(stringify!($func), ".htm")) };
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	200 ($page:literal) => { $crate::_doc::xsso!(xsso: $page) };
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	201 ($name:ident: $page:expr) => {
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	202 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	203 };
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	204 }
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	205
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	206 /// 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	207 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	208 /// A shortcut to `man7!`, `manbsd!`, and `xsso!`.
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	209 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	210 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	211 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	212 /// ```ignore
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	213 /// # use nonstick::_doc::stdlinks;
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	214 /// /// 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	215 /// ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	216 /// #[doc = stdlinks!(3 pam_get_item)]
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	217 /// # fn do_whatever() {}
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	218 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	219 macro_rules! stdlinks {
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	220 ($n:literal $func:ident) => {
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	221 concat!(
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	222 $crate::_doc::man7!($n $func), "\n",
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	223 $crate::_doc::manbsd!($n $func), "\n",
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	224 $crate::_doc::mansun!([$n "pam"] $func), "\n",
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	225 $crate::_doc::xsso!($func))
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	226 };
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	227 }
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	228
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	229 pub(crate) use {guide, linklist, man7, manbsd, mansun, stdlinks, xsso};

Mercurial > crates > nonstick

annotate src/_doc.rs @ 189:b2456d274576 default tip