Lint
rustdoc 提供 Lint 来帮助您编写和测试文档。您可以像使用其他 Lint 一样使用它们，方法是：
#![allow(unused)] #![allow(rustdoc::broken_intra_doc_links)] // allows the lint, no diagnostics will be reported #![warn(rustdoc::broken_intra_doc_links)] // warn if there are broken intra-doc links #![deny(rustdoc::broken_intra_doc_links)] // error if there are broken intra-doc links fn main() { }
请注意，除了 missing_docs 之外，这些 Lint 仅在运行 rustdoc 时可用，而不是 rustc。
以下是 rustdoc 提供的 Lint 列表：
broken_intra_doc_links
此 Lint **默认情况下发出警告**。此 Lint 检测到何时 文档内链接 无法解析。例如
#![allow(unused)] fn main() { /// I want to link to [`Nonexistent`] but it doesn't exist! pub fn foo() {} }
您将收到一条警告信息，提示
warning: unresolved link to `Nonexistent`
--> test.rs:1:24
|
1 | /// I want to link to [`Nonexistent`] but it doesn't exist!
| ^^^^^^^^^^^^^ no item named `Nonexistent` in `test`
当存在歧义时，它也会发出警告并建议如何消除歧义
#![allow(unused)] fn main() { /// [`Foo`] pub fn function() {} pub enum Foo {} pub fn Foo(){} }
warning: `Foo` is both an enum and a function
--> test.rs:1:6
|
1 | /// [`Foo`]
| ^^^^^ ambiguous link
|
= note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default
help: to link to the enum, prefix with the item type
|
1 | /// [`enum@Foo`]
| ^^^^^^^^^^
help: to link to the function, add parentheses
|
1 | /// [`Foo()`]
| ^^^^^^^
private_intra_doc_links
此 Lint **默认情况下发出警告**。此 Lint 检测到何时从公共项目到私有项目的 文档内链接。例如
#![allow(unused)] #![warn(rustdoc::private_intra_doc_links)] // note: unnecessary - warns by default. fn main() { /// [private] pub fn public() {} fn private() {} }
这会发出警告，表明该链接在您的文档中出现时将被破坏
warning: public documentation for `public` links to private item `private`
--> priv.rs:1:6
|
1 | /// [private]
| ^^^^^^^ this item is private
|
= note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
= note: this link will resolve properly if you pass `--document-private-items`
请注意，这在您是否传递 --document-private-items 时会有不同的行为！如果您记录了私有项目，那么即使有警告，它仍然会生成一个链接
warning: public documentation for `public` links to private item `private`
--> priv.rs:1:6
|
1 | /// [private]
| ^^^^^^^ this item is private
|
= note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
= note: this link resolves only because you passed `--document-private-items`, but will break without
missing_docs
此 Lint **默认情况下允许**。它检测到缺少文档的项目。例如
#![warn(missing_docs)] pub fn undocumented() {} fn main() {}
然后 undocumented 函数将有以下警告
warning: missing documentation for a function
--> your-crate/lib.rs:3:1
|
3 | pub fn undocumented() {}
| ^^^^^^^^^^^^^^^^^^^^^
请注意，与其他 rustdoc Lint 不同，此 Lint 也可直接从 rustc 获得。
missing_crate_level_docs
此 Lint **默认情况下允许**。它检测到 crate 根目录中是否没有文档。例如
#![allow(unused)] #![warn(rustdoc::missing_crate_level_docs)] fn main() { }
这将生成以下警告
warning: no documentation found for this crate's top-level module
|
= help: The following guide may be of use:
https://doc.rust-lang.net.cn/nightly/rustdoc/how-to-write-documentation.html
目前，默认情况下是“允许”，但将来打算将其改为警告。这旨在通过向用户提供一些有关如何开始的说明来介绍新用户如何记录他们的 crate，而不会提供像 missing_docs 那样压倒性的警告。
missing_doc_code_examples
此 Lint **默认情况下允许**，并且 **仅限 nightly 版本**。它检测到文档块中缺少代码示例。例如
#![warn(rustdoc::missing_doc_code_examples)] /// There is no code example! pub fn no_code_example() {} fn main() {}
然后 no_code_example 函数将有以下警告
warning: Missing code example in this documentation
--> your-crate/lib.rs:3:1
|
LL | /// There is no code example!
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
要修复 Lint，您需要在文档块中添加一个代码示例
#![allow(unused)] fn main() { /// There is no code example! /// /// ``` /// println!("calling no_code_example..."); /// no_code_example(); /// println!("we called no_code_example!"); /// ``` pub fn no_code_example() {} }
private_doc_tests
此 Lint **默认情况下允许**。它检测到私有项目上的文档测试。例如
#![warn(rustdoc::private_doc_tests)] mod foo { /// private doc test /// /// ``` /// assert!(false); /// ``` fn bar() {} } fn main() {}
这将给出
warning: Documentation test in private item
--> your-crate/lib.rs:4:1
|
4 | / /// private doc test
5 | | ///
6 | | /// ```
7 | | /// assert!(false);
8 | | /// ```
| |___________^
invalid_codeblock_attributes
此 Lint **默认情况下发出警告**。它检测到文档示例中代码块属性可能存在错误类型的值。例如
#![allow(unused)] #![warn(rustdoc::invalid_codeblock_attributes)] // note: unnecessary - warns by default. fn main() { /// Example. /// /// ```should-panic /// assert_eq!(1, 2); /// ``` pub fn foo() {} }
这将给出
warning: unknown attribute `should-panic`. Did you mean `should_panic`?
--> src/lib.rs:1:1
|
1 | / /// Example.
2 | | ///
3 | | /// ```should-panic
4 | | /// assert_eq!(1, 2);
5 | | /// ```
| |_______^
|
= note: `#[warn(rustdoc::invalid_codeblock_attributes)]` on by default
= help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
在上面的示例中，正确形式是 should_panic。这有助于检测某些常见属性的拼写错误。
invalid_html_tags
此 Lint **默认情况下发出警告**。它检测到未关闭或无效的 HTML 标签。例如
#![allow(unused)] #![warn(rustdoc::invalid_html_tags)] fn main() { /// <h1> /// </script> pub fn foo() {} }
这将给出
warning: unopened HTML tag `script`
--> foo.rs:1:1
|
1 | / /// <h1>
2 | | /// </script>
| |_____________^
|
note: the lint level is defined here
--> foo.rs:1:9
|
1 | #![warn(rustdoc::invalid_html_tags)]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^
warning: unclosed HTML tag `h1`
--> foo.rs:1:1
|
1 | / /// <h1>
2 | | /// </script>
| |_____________^
warning: 2 warnings emitted
invalid_rust_codeblocks
此 Lint **默认情况下发出警告**。它检测到文档示例中无效的 Rust 代码块（例如，空，无法解析为 Rust）。例如
#![allow(unused)] fn main() { /// Empty code blocks (with and without the `rust` marker): /// /// ```rust /// ``` /// /// Invalid syntax in code blocks: /// /// ```rust /// '< /// ``` pub fn foo() {} }
这将给出
warning: Rust code block is empty
--> lint.rs:3:5
|
3 | /// ```rust
| _____^
4 | | /// ```
| |_______^
|
= note: `#[warn(rustdoc::invalid_rust_codeblocks)]` on by default
warning: could not parse code block as Rust code
--> lint.rs:8:5
|
8 | /// ```rust
| _____^
9 | | /// '<
10 | | /// ```
| |_______^
|
= note: error from rustc: unterminated character literal
bare_urls
此 Lint **默认情况下发出警告**。它检测到不是链接的 URL。例如
#![allow(unused)] #![warn(rustdoc::bare_urls)] // note: unnecessary - warns by default. fn main() { /// http://example.org /// [http://example.net] pub fn foo() {} }
这将给出
warning: this URL is not a hyperlink
--> links.rs:1:5
|
1 | /// http://example.org
| ^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<http://example.org>`
|
= note: `#[warn(rustdoc::bare_urls)]` on by default
warning: this URL is not a hyperlink
--> links.rs:3:6
|
3 | /// [http://example.net]
| ^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<http://example.net>`
warning: 2 warnings emitted
unescaped_backticks
此 Lint **默认情况下允许**。它检测到未转义的反引号 (`)。这通常意味着内联代码已损坏。例如
#![allow(unused)] #![warn(rustdoc::unescaped_backticks)] fn main() { /// `add(a, b) is the same as `add(b, a)`. pub fn add(a: i32, b: i32) -> i32 { a + b } }
这将给出
warning: unescaped backtick
--> src/lib.rs:3:41
|
3 | /// `add(a, b) is the same as `add(b, a)`.
| ^
|
note: the lint level is defined here
--> src/lib.rs:1:9
|
1 | #![warn(rustdoc::unescaped_backticks)]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
help: a previous inline code might be longer than expected
|
3 | /// `add(a, b)` is the same as `add(b, a)`.
| +
help: if you meant to use a literal backtick, escape it
|
3 | /// `add(a, b) is the same as `add(b, a)\`.
| +
warning: 1 warning emitted
redundant_explicit_links
此 Lint **默认情况下发出警告**。它检测到与计算出的自动链接相同的显式链接。这通常意味着显式链接可以删除。例如
#![allow(unused)] #![warn(rustdoc::redundant_explicit_links)] // note: unnecessary - warns by default. fn main() { /// add takes 2 [`usize`](usize) and performs addition /// on them, then returns result. pub fn add(left: usize, right: usize) -> usize { left + right } }
这将给出
error: redundant explicit rustdoc link
--> src/lib.rs:3:27
|
3 | /// add takes 2 [`usize`](usize) and performs addition
| ^^^^^
|
= note: Explicit link does not affect the original link
note: the lint level is defined here
--> src/lib.rs:1:9
|
1 | #![deny(rustdoc::redundant_explicit_links)]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
= help: Remove explicit link instead