docgen/
lib.rs

1//! This small crate is to let developers easily document items generated in
2//! macros where the content of the documentation is dynamic.
3//!
4//! # Examples
5//!
6//! ```
7//! #[macro_use]
8//! extern crate docgen;
9//!
10//! doc!(
11//!     "Here is some documentation!"
12//!     ""
13//!     "Empty lines are represented by empty strings.";
14//!     pub fn foo() {}
15//! );
16//!
17//! # fn main() {}
18//! ```
19//!
20//! Commas can be used as delimitter between lines:
21//!
22//! ```
23//! #[macro_use]
24//! extern crate docgen;
25//!
26//! doc!(
27//!     "Here is some documentation!",
28//!     "",
29//!     "Empty lines are represented by empty strings.";
30//!     pub fn foo() {}
31//! );
32//! # fn main() {}
33//! ```
34//!
35//! This is particularly useful when documenting items created by macros:
36//!
37//! ```
38//! #[macro_use]
39//! extern crate docgen;
40//!
41//! macro_rules! add_fn {
42//!     ($name:ident, $ty:ty) => {
43//!         doc!(
44//!             concat!("Add two [`", stringify!($ty), "`] values together.");
45//!             pub fn $name(a: $ty, b: $ty) -> $ty {
46//!                 a + b
47//!             }
48//!         );
49//!     }
50//! }
51//!
52//! add_fn!(add_u8, u8);
53//! add_fn!(add_i8, i8);
54//! # fn main() {}
55//! ```
56
57/// This macro is used to generate documentation upon an item.
58///
59/// # Examples
60///
61/// ```
62/// #[macro_use]
63/// extern crate docgen;
64///
65/// doc!(
66///     "Here is the documentation!"
67///     ""
68///     "Tah dah!";
69///     #[inline]
70///     pub fn foo() {}
71/// );
72///
73/// # fn main() {}
74/// ```
75#[macro_export]
76macro_rules! doc {
77    ($($expr:expr)*; $x:item) => {
78        $(#[doc = $expr])*
79        $x
80    };
81    // The same as the case above, but commas between expressions are allowed.
82    ($($expr:expr),*; $x:item) => {
83        $(#[doc = $expr])*
84        $x
85    };
86}
docgen/lib.rs

docgen/
lib.rs
