用宏生成文档

Question

在定义表单的某些元组结构时，我有几个宏可以减少样板：

macro_rules! new_type (($name:ident, $bytes:expr) => (
    pub struct $name(pub [u8; $bytes]);
    // some common operations on $name
));

然而，我也想记录一下这些新的结构。最好是在宏调用之前编写文档。

/// A certain type
new_type!(CertainType, 42);

但是，当发生这种情况时，Rust不会为CertainType生成文档。

另一种(不那么灵活)的选择是做如下事情：

macro_rules! new_type (($name:ident, $bytes:expr) => (
    /// Some more generic documentation for $name 
    pub struct $name(pub [u8; $bytes]);
    // some common operations on $name
));

但是，这样做时，Rust宏系统不会在文档注释中展开令牌$name。剩下的唯一选择是在宏中编写非常通用的文档，但这会导致我的库记录得更糟糕。

你有什么建议来处理这件事？对我来说，最好的解决方案是能够为每次宏调用编写特定的文档，但如果不可能，我将希望得到关于如何在文档注释中展开标记的提示。

Answer 1

可以在宏调用中捕获文档注释。它并不广为人知，但锈蚀文档实际上表示为项目上的一种特殊类型的属性。例如：

/// Some documentation comment
pub fn function() {}

// is equivalent to

#[doc="Some documentation comment"]
pub fn function() {}

并且可以捕获宏中的属性。已经有几个宏使用此功能，其中最常用的可能是bitflags!。

macro_rules! bitflags {
    (
        $(#[$outer:meta])*
        pub struct $BitFlags:ident: $T:ty {
            $(
                $(#[$inner:ident $($args:tt)*])*
                const $Flag:ident = $value:expr;
            )+
        }
    ) => { /* ... */ };
    // ...
}

注意模式的$(#[$outer:meta])*和$(#[$inner:meta])*部分。它们捕获模式中放置在相应项之前的所有属性。如果您在那里写了一个doc注释，它将被转换为doc属性，并像往常一样传递给rustdoc。

下面是使用此方法的quick_error机箱中的一个示例：

quick_error! {
    #[derive(Debug)]
    pub enum SomeError {
        /// IO Error
        Io(err: io::Error) {}
        /// Arbitrary system error
        Sys(errno: nix::Errno) {}
    }
}

这里是由quick_error宏生成的结构的一个例子，这里是它的定义。