链接显示为未使用的导入

Question

有没有办法将某些内容包含到 documentation 范围中而不将其包含到代码范围中？ 我的 Rustdoc 链接到不在代码范围内的 Trait。如果我在顶部添加

use std::ops::Add

，我会收到来自

unused import

的

cargo build

警告。如果我不添加它，我会收到来自

unresolved link

的

cargo doc

警告。

理论上，

cargo build

不应该警告我，因为 rustdoc 与主代码处于相同的范围，但它确实如此。

/// [Add]
pub fn foo() {}

Answer 1

您可以完全限定该链接。

/// [Add](std::ops::Add)

请注意，您使用的语法是

的简写

/// [Add](Add)

末尾括号中的内容可以是任何有效的限定名称，包括从

std

开始的完全限定名称或其他板条箱的名称。

Answer 2

您可以使用

#[cfg(doc)]

：

#[cfg(doc)]
use std::ops::Add;

/// [Add]
pub fn foo() {}

或者按照@SilvioMayolo 的建议，使用全名。

Answer 3

虽然@ChayimFriedman建议的

#[cfg(doc)]

工作正常，但我找不到一种方法来突出显示文档中未使用的导入，例如稍后更新文档并删除链接时需要。

// doesn't warn about unused import, even if there is no link anymore

#[cfg(doc)]
use std::ops::Add;

/// documentation without link
pub fn foo() {}

因此，正如@SilvioMayolo 所建议的，

\\\ [Add](std::ops::Add)

似乎更适合长期使用，即使这意味着更多的打字。

如果您添加带有合格路径的链接到您的文档，您不会收到任何警告：

// generates no warnings

/// [Add](std::ops::Add)
pub fn foo() {}

如果您忘记添加缺少导入的文档链接的路径（或者如果您稍后重构代码并删除链接所需的导入），则

rustdoc::broken_intra_doc_links

lint 会覆盖您并发出警告关于未解析的链接。

// warns about unresolved link

/// [Add]
pub fn foo() {}

如果您稍后在链接中添加已使用的导入，

rustdoc::redundant_explicit_links

lint 会覆盖您，并会警告您有关冗余的显式链接目标。

// warns about redundant explicit link target

use std::ops::Add;

/// [Add](std::ops::Add)
pub fn foo() {}

虽然这两个 lint 都是默认警告的，但您也可以通过将 lint 添加到您的 main.rs 和/或 lib.rs.

来明确这一点。

#![warn(rustdoc::broken_intra_doc_links)]
#![warn(rustdoc::redundant_explicit_links)]

您还可以使用

deny()

或

forbid()

代替

warn()

来防止在出现链接错误时创建文档。