rust - 记录 rustdoc 看不到的项目

Question

我注意到编译器插件经常提供文档甚至不会提及的宏。它们是通过编程方式注册和创建的，而不是在 rustdoc 识别的语法中定义的。自然，无法显示任何文档。

我正在寻找一种方法来解决这个问题，一种为编译时 crate 中不存在的宏生成文档的方法。

我注意到语法箱也可以从这样的事情中受益。quote_item，例如，完全没有记录。我什至找不到注册它的代码。

Answer 1

一种可能性是做编译器所做的事情：创建一个空macro_rules!宏并将文档附加到该宏。例如，如果一个板条箱定义foo采用单个表达式，则编写类似

/// Documentation
#[macro_export]
macro_rules! foo {
     ($e: expr) => ({ /* syntax extension */ })
}

我注意到语法箱也可以从这样的事情中受益。例如，quote_item 完全没有文档记录。我什至找不到注册它的代码。

您可以在 Rust 源代码中搜索quote_item，这有两个原因：它提供了一些示例，并且还允许您跟踪定义。后者更容易使用Rust 的 DXR 实例，它可以搜索带引号的东西（即可以找到字符串），并包括各种源代码导航技巧（如跳转到定义）。