//! 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
///
/// ```
/// # use nonstick::{_linklist, _stdlinks};
/// /// Here is a list of links:
/// ///
/// #[doc = _linklist!(pam_get_authtok: man7, manbsd)]
/// ///
/// /// The links are defined in the `stdlinks!` invocation below:
/// ///
/// #[doc = _stdlinks!(3 pam_get_authtok)]
/// # fn do_whatever() {}
/// ```
#[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
///
/// ```
/// # use nonstick::{_guide};
/// /// See [the guide][mwg].
/// ///
/// #[doc = _guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_user")]
/// # fn do_whatever() {}
/// ```
#[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
///
/// ```
/// # use nonstick::_man7;
/// /// This contains a [link to the man page for malloc][man7].
/// #[doc = _man7!(3 malloc)]
/// # fn do_whatever() {}
///
/// /// This contains both a link to the ["structure" section of `hgrc`][man7]
/// /// and a link to the ["environment" section of `systemd`][sysd_env].
/// ///
/// #[doc = _man7!(5 hgrc "STRUCTURE")]
/// #[doc = _man7!(sysd_env: 1 systemd "ENVIRONMENT")]
/// # fn do_whatever2() {}
/// ```
#[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
///
/// ```
/// # use nonstick::_manbsd;
/// // 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")]
/// # fn do_whatever() {}
/// ```
#[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
///
/// ```
/// # use nonstick::_xsso;
/// /// This docstring will [link to the X/SSO spec for `pam_set_item`][xsso].
/// ///
/// #[doc = _xsso!(pam_set_item)]
/// # fn link_one() {}
/// 
/// /// This docstring will link to [`some_page`][xsso].
/// /// I can also link to [the table of contents][spec_toc].
/// ///
/// #[doc = _xsso!("some_page.htm#section-id")]
/// #[doc = _xsso!(spec_toc: "toc.htm")]
/// # fn do_whatever() {}
/// ```
#[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
///
/// ```
/// # use nonstick::_stdlinks;
/// /// Check out [this][man7], [that][manbsd], or [the other][xsso].
/// ///
/// #[doc = _stdlinks!(3 pam_get_item)]
/// # fn do_whatever() {}
/// ```
#[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))
    };
}