devela 0.28.0

A development substrate of coherence.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

// devela::yard::_doc::meta
//
//! Defines [`_doc_meta!`].
//

#[doc = crate::_tags!(internal)]
/// Composes a small rustdoc metadata section for an item.
#[doc = crate::_doc_meta!{location("yard")}]
///
/// This macro centralizes the ad-hoc metadata band used near the top of item
/// documentation. It wraps supported metadata fragments between horizontal
/// rules and dispatches each section to the corresponding helper.
///
/// # Sections
/// - `location(...)`: emits an item location fragment through [`_doc_location!`].
/// - `test_size_of(...)`: emits checked type-size metadata through [`_doc_test_size_of!`].
/// - `origin(...)`: emits re-export origin metadata for Rust or dependency items.
///
/// [`_doc_location!`]: crate::_doc_location
/// [`_doc_test_size_of!`]: crate::_doc_test_size_of
///
/// # Examples
/// ```ignore
/// #[doc = crate::_doc_meta! { location("media/audio"), test_size_of(PcmSpec = 8) }]
/// #[doc = crate::_doc_meta! { location(re-exported "code/any"), origin(rust core::any) }]
/// #[doc = crate::_doc_meta! { location(re-exported "code"), origin(crate "hashbrown") }]
/// ```
#[cfg_attr(cargo_primary_package, doc(hidden))]
#[cfg_attr(not(feature = "__docs_internal"), doc(hidden))]
#[cfg_attr(nightly_doc, doc(cfg(feature = "__docs_internal")))]
#[macro_export]
macro_rules! _doc_meta· {
    /* internal dispatcher: end */
    (@items) => { "" };
    (@items ,) => { "" };
    /* public section: location */
    (@items location($($args:tt)*) $(, $($rest:tt)*)?) => {
        concat!(
            $crate::_doc_location!(%from_meta $($args)*),
            $crate::_doc_meta!(@items $($($rest)*)?)
        )
    };
    /* public section: test_size_of */
    (@items $(#[$meta:meta])* test_size_of($($args:tt)*) $(, $($rest:tt)*)?) => {
        concat!(
            $crate::_doc_test_size_of!($(#[$meta])* $($args)*),
            $crate::_doc_meta!(@items $($($rest)*)?)
        )
    };
    /* public section: origin from Rust core/alloc/std */
    (@items origin(rust $root:ident $(:: $path:ident)* $(;
        renamed($($old:ident as $new:ident),* $(,)?))?) $(, $($rest:tt)*)?) => {
        concat!(" ",
            $crate::_doc_meta!(@emit_origin_rust $root $(:: $path)* ; $($($old as $new),*)?),
            $crate::_doc_meta!(@items $($($rest)*)?)
        )
    };
    /* public section: origin from external crate */
    (@items origin(crate $dep:literal
        $(; renamed($($old:ident as $new:ident),* $(,)?))?) $(, $($rest:tt)*)?) => {
        concat!(" ",
            $crate::_doc_meta!(@emit_origin_crate $dep; $($($old as $new),*)?),
            $crate::_doc_meta!(@items $($($rest)*)?)
        )
    };

    /* optional: display name differs from docs.rs crate slug */
    (@items origin(crate $shown:literal => $docs:literal
        $(; renamed($($old:ident as $new:ident),* $(,)?))?) $(, $($rest:tt)*)?) => {
        concat!(" ",
            $crate::_doc_meta!(@emit_origin_crate_as $shown => $docs; $($($old as $new),*)?),
            $crate::_doc_meta!(@items $($($rest)*)?)
        )
    };

    /* internal emitters */
    (@emit_origin_rust $root:ident $(:: $path:ident)* ; $($renamed:tt)*) => {
        concat!(
            "<sup>re-exported from <a title='location in `", ::core::stringify!($root),
            "`' href=\"https://doc.rust-lang.org/", ::core::stringify!($root), "/",
            $( ::core::stringify!($path), "/", )* "\">", ::core::stringify!($root),
            $("::", ::core::stringify!($path),)* "</a>",
            $crate::_doc_meta!(@emit_renamed $($renamed)*), "</sup>"
        )
    };
    (@emit_origin_crate $dep:literal; $($renamed:tt)*) => {
        concat!(
            "<sup>re-exported from the <a title='docs for `", $dep,
            "`' href=\"https://docs.rs/", $dep, "\">", $dep, "</a> crate",
            $crate::_doc_meta!(@emit_renamed $($renamed)*), ".</sup>"
        )
    };

    (@emit_origin_crate_as $shown:literal => $docs:literal; $($renamed:tt)*) => {
        concat!(
            "<sup>re-exported from the <a title='docs for `", $shown,
            "`' href=\"https://docs.rs/", $docs, "\">", $shown, "</a> crate",
            $crate::_doc_meta!(@emit_renamed $($renamed)*), ".</sup>"
        )
    };
    (@emit_renamed) => { "" };
    (@emit_renamed $($old:ident as $new:ident),+ $(,)?) => {
        concat!( " ", $( "`::", stringify!($old), "` as `", stringify!($new), "` " ),+)
    };

    /* diagnostics */
    (@items $bad:ident($($args:tt)*) $(, $($rest:tt)*)?) => {
        compile_error!(concat!("unknown _doc_meta! section: `", stringify!($bad), "`"))
    };
    (@items $($bad:tt)+) => {
        compile_error!(concat!("could not parse _doc_meta! input near: `",
            stringify!($($bad)+), "`"))
    };

    /* public entrypoints last */
    () => { "" };
    ($($rest:tt)+) => {
        concat!(
            "\n\n---\n\n",
            $crate::_doc_meta!(@items $($rest)+),
            "\n\n---\n\n",
        )
    };
}
#[doc(inline)]
pub use _doc_meta· as _doc_meta;