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
//
// Doc comment
//
// Copyright (c) 2018 Guillaume Gomez
//
//! The point of this (small) crate is to allow you to add doc comments from macros.
//!
//! It's especially useful when generating types with macros. For example:
//!
//! ```
//! // The macro which generates types
//! macro_rules! gen_types {
//! ($tyname:ident) => {
//! /// This is a wonderful generated struct!
//! ///
//! /// You can use it as follow:
//! ///
//! /// ```
//! /// let x = FirstOne {
//! /// field1: 0,
//! /// field2: 0,
//! /// field3: 0,
//! /// field4: 0,
//! /// };
//! ///
//! /// println!("Created a new instance of FirstOne: {:?}", x);
//! /// ```
//! #[derive(Debug)]
//! pub struct $tyname {
//! pub field1: u8,
//! pub field2: u16,
//! pub field3: u32,
//! pub field4: u64,
//! }
//! }
//! }
//!
//! // Now let's actually generate types:
//! gen_types!(FirstOne);
//! gen_types!(SecondOne);
//! gen_types!(Another);
//! ```
//!
//! So now we have created three structs with different names, but they all have the exact same
//! documentation, which is an issue for any structs not called `FirstOne`. That's where
//! [`doc_comment!`] macro comes in handy!
//!
//! Let's rewrite the `gen_types!` macro:
//!
//! // Of course, we need to import the `doc_comment` macro:
//! #[macro_use]
//! extern crate doc_comment;
//!
//! macro_rules! gen_types {
//! ($tyname:ident) => {
//! doc_comment! {
//! concat!("This is a wonderful generated struct!
//!
//! You can use it as follow:
//!
//! ```
//! let x = ", stringify!($tyname), " {
//! field1: 0,
//! field2: 0,
//! field3: 0,
//! field4: 0,
//! };
//!
//! println!(\"Created a new instance of ", stringify!($tyname), ": {:?}\", x);
//! ```"),
//! #[derive(Debug)]
//! pub struct $tyname {
//! pub field1: u8,
//! pub field2: u16,
//! pub field3: u32,
//! pub field4: u64,
//! }
//! }
//! }
//! }
//!
//! gen_types!(FirstOne);
//! gen_types!(SecondOne);
//! gen_types!(Another);
//! # fn main() {}
//!
//! Now each struct has doc which match itself!