记录使用 Rust 中的宏创建的函数 [重复]

Question

我试过了

#![deny(missing_docs)]

在 Rust 中。我发现/// cmets 在使用这样的宏创建函数时会被忽略：

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

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

#![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 cmets 对于所有生成的函数都是相同的。如果您想记录每个生成的函数，您必须更改宏：

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

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

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