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

//
// Doc comment
//
// Copyright (c) 2018 Guillaume Gomez
//

#![cfg_attr(feature = "no_core", feature(no_core))]
#![cfg_attr(feature = "no_core", no_core)]
#![cfg_attr(not(feature = "no_core"), no_std)]

//! 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!

#[macro_export]
macro_rules! doc_comment {
    ($x:expr, $($tt:tt)*) => {
        #[doc = $x]
        $($tt)*
    };
}