Crate doc_comment

The point of this (small) crate is to allow you to add doc comments from macros or to test external markdown files' code blocks through rustdoc.

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!

Now let's assume you want to test code examples in your README.md file which looks like this:

# A crate

Here is a code example:

```rust
let x = 2;
assert!(x != 0);
```

You can use the doc_comment! macro to test it like this:

#[macro_use]
extern crate doc_comment;

// When running `cargo test`, rustdoc will check this file as well.
doc_comment!(include_str!("../README.md"));

Please note that can also use the doctest! macro to have a shorter way to test an outer file:

#[macro_use]
extern crate doc_comment;

doctest!("../README.md");

Macros

doc_comment	This macro can be used to generate documentation upon a type/item (or just to test outer markdown file code examples).
doctest	This macro provides a simpler way to test an outer markdown file.