如何编写整箱的文档？ [英] How can I write crate-wide documentation?

问题描述

为了确保记录我的板条箱中所有公共物品（如果最少要从头开始），我在我的<中指定了＃！[deny（missing_docs）] code> lib.rs 。

我希望在顶部和之后的代码中写文档注释：

  /// Rust的Hello world示例。 
 
＃！[deny（missing_docs）] 
 
 fn main（）{
 println！（ Hello world！）; 
} 
  

此操作失败：

 错误：在外部文档注释
之后不允许使用内部属性-> src / main.rs：3：3 
 | 
 3 | ＃！[deny（missing_docs）] 
 | ^ 
 | 
 =注意：内部属性（如`＃！[no_std]`）注释包含它们的项目，通常在源文件的开头。外部属性（例如，＃[test]）注释其后的项目。 
  

还原顺序，以使属性为第一，注释为第二：

 ＃！[deny（missing_docs）] 
 
 /// Rust的Hello world示例。 
 
 fn main（）{
 println！（ Hello world！）; 
} 
  

也失败：

< pre class = lang-none prettyprint-override> 错误：缺少板条箱
的文档-> src / main.rs：1：1
|
1 | /＃！[deny（missing_docs）]
2 | |
3 | | /// Rust的Hello world示例。
4 | |
5 | | fn main（）{
6 | | println！（ Hello world！）；
7 | | }
| | _ ^
|
注意：这里定义的皮棉等级
-> src / main.rs：1：9
|
1 | ＃！[deny（missing_docs）]
| ^^^^^^^^^^^^^


我找不到如何实际编写文档的方法包装箱本身。我应该如何编写包装箱的文档来满足＃！[deny（missing_docs）] ？

解决方案

我在本书将板条箱发布到Crates.io部分。

常规文档注释（以开头/// ）记录下一个项，但是没有板条箱了。

解决方案是切换而不是使用另一种注释，这次以 //！开头，该文档记录了封闭的项目。

突然起作用了：

 ＃！[deny（missing_docs）] 
 
 //！您好，Rust的世界示例。 
 
 fn main（）{
 println！（ Hello world！）; 
} 
  

In order to ensure that all public artifacts of my crate are documented (if minimally to start with), I specified #![deny(missing_docs)] in my lib.rs. This backfired.

I expected to write a documentation comment at the top and the code afterwards:

/// Hello world example for Rust.

#![deny(missing_docs)]

fn main() {
    println!("Hello world!");
}

This fails with:

error: an inner attribute is not permitted following an outer doc comment
 --> src/main.rs:3:3
  |
3 | #![deny(missing_docs)]
  |   ^
  |
  = note: inner attributes, like `#![no_std]`, annotate the item enclosing them, and are usually found at the beginning of source files. Outer attributes, like `#[test]`, annotate the item following them.

Reverting the order so that the attribute is first and the comment second:

#![deny(missing_docs)]

/// Hello world example for Rust.

fn main() {
    println!("Hello world!");
}

Also fails:

error: missing documentation for crate
 --> src/main.rs:1:1
  |
1 | / #![deny(missing_docs)]
2 | |
3 | | /// Hello world example for Rust.
4 | |
5 | | fn main() {
6 | |     println!("Hello world!");
7 | | }
  | |_^
  |
note: lint level defined here
 --> src/main.rs:1:9
  |
1 | #![deny(missing_docs)]
  |         ^^^^^^^^^^^^

I could not find how to actually write documentation for the crate itself. How should I be writing the crate's documentation to satisfy #![deny(missing_docs)]?

解决方案

I found the hidden nugget in the book's Publishing a Crate to Crates.io section.

Regular documentation comments (starting with ///) document the next item, however a crate is nobody's next.

The solution is to switch to using another kind of comment, this time starting with //!, which documents the enclosing item.

And suddenly it works:

#![deny(missing_docs)]

//! Hello world example for Rust.

fn main() {
    println!("Hello world!");
}

这篇关于如何编写整箱的文档？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！