[−][src]Crate doc_comment
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);
Now each struct has doc which match itself!
It's also possible to generate doc comments without passing a type as follows:
#[macro_use] extern crate doc_comment; doc_comment!("foooooo");
Macros
doc_comment |