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

//! This small crate is to let developers easily document items generated in
//! macros where the content of the documentation is dynamic.
//!
//! # Examples
//!
//! ```
//! #[macro_use]
//! extern crate docgen;
//!
//! doc!(
//!     "Here is some documentation!"
//!     ""
//!     "Empty lines are represented by empty strings.";
//!     pub fn foo() {}
//! );
//!
//! # fn main() {}
//! ```
//!
//! Commas can be used as delimitter between lines:
//!
//! ```
//! #[macro_use]
//! extern crate docgen;
//!
//! doc!(
//!     "Here is some documentation!",
//!     "",
//!     "Empty lines are represented by empty strings.";
//!     pub fn foo() {}
//! );
//! # fn main() {}
//! ```
//!
//! This is particularly useful when documenting items created by macros:
//!
//! ```
//! #[macro_use]
//! extern crate docgen;
//!
//! macro_rules! add_fn {
//!     ($name:ident, $ty:ty) => {
//!         doc!(
//!             concat!("Add two [`", stringify!($ty), "`] values together.");
//!             pub fn $name(a: $ty, b: $ty) -> $ty {
//!                 a + b
//!             }
//!         );
//!     }
//! }
//!
//! add_fn!(add_u8, u8);
//! add_fn!(add_i8, i8);
//! # fn main() {}
//! ```

/// This macro is used to generate documentation upon an item.
///
/// # Examples
///
/// ```
/// #[macro_use]
/// extern crate docgen;
///
/// doc!(
///     "Here is the documentation!"
///     ""
///     "Tah dah!";
///     #[inline]
///     pub fn foo() {}
/// );
///
/// # fn main() {}
/// ```
#[macro_export]
macro_rules! doc {
    ($($expr:expr)*; $x:item) => {
        $(#[doc = $expr])*
        $x
    };
    // The same as the case above, but commas between expressions are allowed.
    ($($expr:expr),*; $x:item) => {
        $(#[doc = $expr])*
        $x
    };
}