//! A place to stick documentation stuff.

/// Generates text lists of reference links for docs.
///
/// Use this with the other doc macros for the correct link names.
///
/// # Examples
///
/// ```
/// #[doc = _linklist!(pam_get_authtok: man7, manbsd)]
/// ///
/// /// ...use it with link references, like the below...
/// ///
/// #[doc = _stdlinks!(3 pam_get_authtok)]
/// ```
#[macro_export]
#[doc(hidden)]
macro_rules! _linklist {
    ($func:ident: adg$(, $rest:ident)*) => {
        concat!(
            "- [Application Developers' Guide on `", stringify!($func), "`][adg]\n",
            $crate::_linklist!($func: $($rest),*)
        )
    };
    ($func:ident: mwg$(, $rest:ident)*) => {
        concat!(
            "- [Module Writers' Guide on `", stringify!($func), "`][mwg]\n",
            $crate::_linklist!($func: $($rest),*)
        )
    };
    ($func:ident: _std$(, $rest:ident)*) => {
        $crate::_linklist!($func: man7, manbsd, xsso$(, $rest)*)
    };
    ($func:ident: man7$(, $rest:ident)*) => {
        concat!(
            "- [Linux-PAM manpage for `", stringify!($func), "`][man7]\n",
            $crate::_linklist!($func: $($rest),*)
        )
    };
    ($func:ident: manbsd$(, $rest:ident)*) => {
        concat!(
            "- [OpenPAM manpage for `", stringify!($func), "`][manbsd]\n",
            $crate::_linklist!($func: $($rest),*)
        )
    };
    ($func:ident: xsso$(, $rest:ident)*) => {
        concat!(
            "- [X/SSO spec for `", stringify!($func), "`][xsso]",
            $crate::_linklist!($func: $($rest),*)
        )
    };
    ($func:ident:$(,)?) => { "" };
}

/// Generates a Markdown link reference to one of the PAM guides.
///
/// # Examples
///
/// ```
/// #[doc = _guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_user")]
/// ```
#[macro_export]
#[doc(hidden)]
macro_rules! _guide {
    ($name:ident: $page_link:literal) => {
        concat!(
            "[",
            stringify!($name),
            "]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/",
            $page_link
        )
    };
}

/// Generates a Markdown link reference to the Linux man pages on man7.org.
///
/// # Examples
///
/// ```
/// // Both of these formulations create a link reference named `man7`.
/// #[doc = _man7!(3 fn_name)]
/// #[doc = _man7!(5 thing_name "SECTION")]
/// // This one creates a link reference named `link_name`.
/// #[doc = _man7!(link_name: 1 prog_name "SECTION")]
/// ```
#[macro_export]
#[doc(hidden)]
macro_rules! _man7 {
    ($n:literal $fn:ident $($anchor:literal)?) => {
        $crate::_man7!(man7: $n $fn $($anchor)?)
    };
    ($name:ident: $n:literal $fn:ident $($anchor:literal)?) => {
        concat!(
            "[", stringify!($name), "]: ",
            "https://man7.org/linux/man-pages/man", $n, "/",
            stringify!($fn), ".", $n, ".html", $("#", $anchor)?
        )
    };
}

/// Generates a Markdown link reference to the NetBSD man pages.
///
/// # Examples
///
/// ```
/// // Both of these formulations create a link named `manbsd`.
/// #[doc = _manbsd!(3 fn_name)]
/// #[doc = _manbsd!(5 thing_name "SECTION")]
/// // This one creates a link named `link_name`.
/// #[doc = _manbsd!(link_name: 1 prog_name "SECTION")]
/// ```
#[macro_export]
#[doc(hidden)]
macro_rules! _manbsd {
    ($n:literal $func:ident $($anchor:literal)?) => {
        $crate::_manbsd!(manbsd: $n $func $($anchor)?)
    };
    ($name:ident: $n:literal $func:ident $($anchor:literal)?) => {
        concat!("[", stringify!($name), "]: ",
            "https://man.netbsd.org/", stringify!($func), ".", $n,
            $("#", $anchor)?
        )
    };
}

/// Generates a Markdown link reference to the X/SSO specification.
///
/// # Examples
///
/// ```
/// // Both of these formulations create a link reference named `xsso`.
/// // A link to the X/SSO specification for the `pam_set_item` function.
/// #[doc = _xsso!(pam_set_item)]
/// // A link to the HTML page with the given name.
/// #[doc = _xsso!("some_page.htm#section-id")]
///
/// // This one creates a link reference named `spec_toc`.
/// #[doc = _xsso!(spec_toc: "toc.htm")]
/// ```
#[macro_export]
#[doc(hidden)]
macro_rules! _xsso {
    ($func:ident) => { $crate::_xsso!(xsso: concat!(stringify!($func), ".htm")) };
    ($page:literal) => { $crate::_xsso!(xsso: $page) };
    ($name:ident: $page:expr) => {
        concat!("[", stringify!($name), "]: https://pubs.opengroup.org/onlinepubs/8329799/", $page)
    };
}

/// Generates Markdown link references to Linux-PAM, OpenPAM, and X/SSO.
///
/// A shortcut to `_man7!`, `_manbsd!`, and `_xsso!`.
///
/// # Examples
///
/// ```
/// #[doc = _stdlinks!(3 pam_get_item)]
/// ```
#[macro_export]
#[doc(hidden)]
macro_rules! _stdlinks {
    ($n:literal $func:ident) => {
        concat!($crate::_man7!($n $func), "\n", $crate::_manbsd!($n $func), "\n", $crate::_xsso!($func))
    };
}