记录用Rust宏创建的函数

Question

我试着做

#![deny(missing_docs)]

在铁锈里。我发现，当用这样的宏创建函数时，///注释就会被忽略：

/// docs
py_module_initializer!(libx, initlibx PyInit_libx |py, m| {
    Ok(())
});

通过以下方式：

error: missing documentation for a function
113 | py_module_initializer!(libx initlibx PyInit_libx |py, m| {
    | ^

我以为宏只会在///之后添加一个函数定义。这里怎么了？

Answer 1

您的文档注释引用了宏调用，这在您的情况下是无用的。要记录生成的函数，必须将文档注释写入宏定义，或者更改宏以接受文档注释。让我们来看看这个：

#![deny(missing_docs)]
//! crate docs

macro_rules! gen_fn {
    ($name:ident) => {
        /// generic doc comment... not very useful
        pub fn $name() {}
    }
}

gen_fn!(a);
gen_fn!(b);

这是可行的，但这不是最好的解决方案，因为doc注释对于所有生成的函数都是相同的。如果要记录每个生成的函数，则必须更改宏：

macro_rules! gen_fn {
    ($(#[$attr:meta])* => $name:ident) => {
        $(#[$attr])*
        pub fn $name() {}
    }
}

gen_fn!{
    /// Doc comment for a
    => a
}

这是可行的，因为文档注释在内部被转换为#[doc(...)]属性。您可以找到有关该here的更多信息。