3

我写了一个proc-macro库来配合我正在编写的库 - 它们一起使用，前者用于抽象出后者中的大量冗余代码。

我在我的 proc 宏中成功生成了几个结构和实现。我也在使用cargo doc图书馆，我的文档是我所期望的。但是，我在 proc 宏中创建的文档注释没有按预期工作。我的 proc 宏中的一些代码大致如下所示：

#[proc_macro_derive(MyDerive)]
pub fn derive(input: TokenStream) -> TokenStream {
    ...
    let expanded = quote! {
        ...
        impl #my_struct {
            /// This comment doesn't show up in documentation
            pub fn foo(&self, n: i32) -> bool {
               false
            }

            /// This comment DOES show up in documentation
            pub fn bar(n: i32) -> Vec<String> {
               ...
            }
        }
    }
    expanded.into()
}

当我打开生成的文档时：

  • foo本身出现在文档中，但它的评论没有
  • bar及其评论在文档中
  • 如果我更改 的评论bar，则评论不会更新。

这第三点告诉我，我可能cargo doc在某些时候使用了一些正常工作的标志，但我现在使用的是一组不同的标志，这些标志不适用于 proc 宏。我不想记录我所有的外部 crate 依赖项 ( --no-deps)，但我确实想记录我的私人项目 ( --document-private-items)。因此，我使用cargo doc --no-deps --document-private-items. 我也试过了--release。

我假设文档是从源代码构建的，而不是从构建的 .so 文件本身构建的，所以我cargo build之前没有做过cargo doc，尽管我也尝试过这个来调试这个问题。那么，确保正确生成和更新我的 proc 宏生成代码的文档的正确方法是什么？

4

0 回答 0