doc-comment

从宏中编写文档注释。

使用示例

// Of course, we need to import the `doc_comment` macro:
#[macro_use]
extern crate doc_comment;

// If you want to test examples in your README file.
doctest!("../README.md");

// If you want to test your README file ONLY on "cargo test":
#[cfg(doctest)]
doctest!("../README.md");

// If you want to document an item:
doc_comment!(concat!("fooo", "or not foo"), pub struct Foo {});

更多信息，请参阅 文档。

lib.rs:

这个（小）crate 的目的是允许您通过宏添加文档注释或通过 rustdoc 测试外部 markdown 文件的代码块。

包含用于测试的文件

假设您想测试 README.md 文件中的代码示例，该文件看起来像这样

# A crate

Here is a code example:

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

您可以使用 doc_comment! 宏进行测试，如下所示

#[macro_use]
extern crate doc_comment;

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

请注意，您还可以使用 doctest! 宏以更简短的方式来测试外部文件

#[macro_use]
extern crate doc_comment;

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

请注意，您还可以使用 #[cfg(doctest)]

#[cfg(doctest)]
doctest!("../README.md");

在这种情况下，README.md 文件中的示例将仅在 cargo test 上运行。有关 #[cfg(doctest)] 的更多信息，请参阅 这篇博客文章。

通用文档

现在假设您想要为多个类型编写一次文档，但仍希望针对每种类型具有特定的示例

// 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);

现在我们创建了三个不同名称的结构体，但它们都具有完全相同的文档，这对于任何不被称为 FirstOne 的结构体来说是一个问题。这正是 doc_comment! 宏派上用场的时候！

让我们重写 gen_types! 宏

 // 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() {}

现在每个结构体的文档都与自身匹配！