Rust中两种文档注释样式有什么区别？(/// vs //!)

Question

该锈语言文档说,有关文档的意见(重点煤矿)以下内容:

文档注释使用///而不是//[...]还有另一种文档注释样式//!,用于评论包含项目(例如板条箱,模块或函数),而不是后面的项目.

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

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

Answer 1

关键词包含.//!评论记录包含它的东西:

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

///注释文档的事情如下它:

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

风格在其他方面是等同的.但是你只能使用//!实际包含代码的东西- 比如crate,modules和functions - 这就是为什么doc会把这三个作为例子.

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声明.

• ///记录下一个项目
• //!记录封闭物品

注意,通常你只会使用///.记录模块以外的任何东西//!都是不好的风格,应该避免.你总是想要使用,/// 除非你想要记录一个模块(包括root-module/crate); 那么用这个模块编写文档就可以了//!.