crates/nonstick: src/_doc.rs annotate

annotate src/_doc.rs @ 171:e27c5c667a5a

Create full new types for return code and flags, separate end to end. This plumbs the ReturnCode and RawFlags types through the places where we call into or are called from PAM. Also adds Sun documentation to the project.

author	Paul Fisher <paul@pfish.zone>
date	Fri, 25 Jul 2025 20:52:14 -0400
parents	1bc52025156b
children	9e4ce1631bd3

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;
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	146 /// // Both of these formulations create a link named `manbsd`.
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 };
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	157 ([$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	158 $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	159 };
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	160 ($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	161 $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	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 $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	164 $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	165 };
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	166 ($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	167 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	168 "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	169 $("#", $anchor)?
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	170 )
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 }
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	173
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	174 /// 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	175 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	176 /// # Examples
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 /// ```ignore
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	179 /// # use nonstick::_doc::xsso;
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	180 /// /// 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	181 /// ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	182 /// #[doc = xsso!(pam_set_item)]
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	183 /// # fn link_one() {}
106 49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff. Paul Fisher <paul@pfish.zone> parents: 105 diff changeset	184 ///
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	185 /// /// This docstring will link to [`some_page`][xsso].
13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	186 /// /// 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	187 /// ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	188 /// #[doc = xsso!("some_page.htm#section-id")]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	189 /// #[doc = xsso!(spec_toc: "toc.htm")]
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	190 /// # fn do_whatever() {}
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	191 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	192 macro_rules! xsso {
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	193 ($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	194 ($page:literal) => { $crate::_doc::xsso!(xsso: $page) };
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	195 ($name:ident: $page:expr) => {
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	196 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	197 };
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	198 }
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	199
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	200 /// 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	201 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	202 /// A shortcut to `man7!`, `manbsd!`, and `xsso!`.
103 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 /// # Examples
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	205 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	206 /// ```ignore
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	207 /// # use nonstick::_doc::stdlinks;
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	208 /// /// 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	209 /// ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	210 /// #[doc = stdlinks!(3 pam_get_item)]
105 13b4d2a19674 Support Rust v1.75.0. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	211 /// # fn do_whatever() {}
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	212 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	213 macro_rules! stdlinks {
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	214 ($n:literal $func:ident) => {
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	215 concat!(
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	216 $crate::_doc::man7!($n $func), "\n",
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 142 diff changeset	217 $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	218 $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	219 $crate::_doc::xsso!($func))
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	220 };
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: diff changeset	221 }
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 106 diff changeset	222
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	223 pub(crate) use {guide, linklist, man7, manbsd, mansun, stdlinks, xsso};

Mercurial > crates > nonstick

annotate src/_doc.rs @ 171:e27c5c667a5a