crates/nonstick: src/_doc.rs annotate

annotate src/_doc.rs @ 141:a508a69c068a

Remove a lot of Results from functions. Many functions are documented to only return failing Results when given improper inputs or when there is a memory allocation failure (which can be verified by looking at the source). In cases where we know our input is correct, we don't need to check for memory allocation errors for the same reason that Rust doesn't do so when you, e.g., create a new Vec.

author	Paul Fisher <paul@pfish.zone>
date	Sat, 05 Jul 2025 17:16:56 -0400
parents	39760dfc9b3b
children	5c1e315c18ff

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
118 39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	179 pub(crate) use {guide, linklist, man7, manbsd, stdlinks, xsso};

Mercurial > crates > nonstick

annotate src/_doc.rs @ 141:a508a69c068a