Rust中两种文档注释样式有什么区别？ （/// vs //！）

Question

Rust language doc说明以下关于文档评论（强调我的）：

  

文档评论使用///代替// [...]还有另一种文档评论样式//!，用于评论包含的项目（例如包装箱，模块或函数），而不是它后面的项目。

只是为了混淆事情，文档提供了一个使用///格式来记录函数的示例（通过链接可见，但在上面的省略号中省略）。

我之前看到过这两种风格几乎是同义词 - Rust中它们之间有区别吗？我在这里和互联网上的搜索没有任何结果。

Answer 1

关键字是包含。 //!条评论记录包含的内容：

fn foo() {
    //! a super awesome function
    ...
}

///评论记录了跟随的内容：

/// a super awesome function
fn foo() {
    ...
}

这些风格在其他方面是等同的。但是，您只能将//!与实际包含代码的内容（例如包装箱，模块和函数）一起使用 - 这就是为什么该文档将这三个作为示例进行调用的原因

Answer 2

此代码：

/// I am referring to the next item
mod foo {
    fn bar() {}
}

与此代码等效（以单字差为模）：

mod foo {
    //! I am referring to the enclosing item
    fn bar() {}
}

两次，doc评论都属于mod声明。

• /// 记录下一个项目
• //! 记录附上项

请注意，通常您只会使用///。使用//!记录模块以外的任何内容都是不好的风格，应该避免。如果要记录模块（包括根模块/包），您总是希望使用/// （除外）;那么用//!编写该模块内的文档是很好的。