通过名称链接到项目

Rustdoc 可以使用项目的路径直接链接到其他 rustdoc 页面。这被称为“文档内链接”。

例如，在以下代码中，所有链接都将链接到 Bar 的 rustdoc 页面

#![allow(unused)]
fn main() {
/// This struct is not [Bar]
pub struct Foo1;

/// This struct is also not [bar](Bar)
pub struct Foo2;

/// This struct is also not [bar][b]
///
/// [b]: Bar
pub struct Foo3;

/// This struct is also not [`Bar`]
pub struct Foo4;

/// This struct *is* [`Bar`]!
pub struct Bar;
}

与普通 Markdown 不同，[bar][Bar] 语法也支持，无需 [Bar]: ... 引用链接。

链接周围的反引号将被剥离，因此 [`Option`] 将正确链接到 Option。

有效链接

您可以引用范围内的任何内容，并使用路径，包括 Self、self、super 和 crate。关联项（函数、类型和常量）受支持，但不适用于泛型特质实现。Rustdoc 还支持链接到标准库文档中列出的所有基本类型。

您还可以引用带有泛型参数的项目，例如 Vec<T>。链接将解析为好像您写了 [`Vec<T>`](Vec) 一样。完全限定的语法（例如，<Vec as IntoIterator>::into_iter()）尚不支持。

#![allow(unused)]
fn main() {
use std::sync::mpsc::Receiver;

/// This is a version of [`Receiver<T>`] with support for [`std::future`].
///
/// You can obtain a [`std::future::Future`] by calling [`Self::recv()`].
pub struct AsyncReceiver<T> {
    sender: Receiver<T>
}

impl<T> AsyncReceiver<T> {
    pub async fn recv() -> T {
        unimplemented!()
    }
}
}

Rustdoc 允许使用 URL 片段说明符，就像普通链接一样

#![allow(unused)]
fn main() {
/// This is a special implementation of [positional parameters].
///
/// [positional parameters]: std::fmt#formatting-parameters
struct MySpecialFormatter;
}

命名空间和消歧符

Rust 中的路径有三个命名空间：类型、值和宏。项目名称在它们的命名空间内必须是唯一的，但可以与其他命名空间中的项目重叠。如果出现歧义，rustdoc 将警告歧义并建议一个消歧符。

#![allow(unused)]
fn main() {
/// See also: [`Foo`](struct@Foo)
struct Bar;

/// This is different from [`Foo`](fn@Foo)
struct Foo {}

fn Foo() {}
}

这些前缀在文档中显示时将被剥离，因此 [struct@Foo] 将呈现为 Foo。以下前缀可用：struct、enum、trait、union、mod、module、const、constant、fn、function、method、derive、type、value、macro、prim 或 primitive。

您还可以通过在函数名称后添加 () 或在宏名称后添加 ! 来为函数消歧。宏 ! 后面可以是 ()、{} 或 []。示例

#![allow(unused)]
fn main() {
/// This is different from [`foo!()`].
fn foo() {}

/// This is different from [`foo()`]
macro_rules! foo {
  () => {}
}
}

有一种情况会自动执行消歧：如果文档内链接与特质和派生 proc 宏同时解析。在这种情况下，它将始终生成指向特质的链接，并且不会发出“缺少消歧”警告。此情况的一个很好的例子是当您链接到 Clone 特质时：还有一个 Clone proc 宏，但它在这种情况下会忽略它。如果您想链接到 proc 宏，可以使用 macro@ 消歧符。

警告、重新导出和作用域

链接在定义项目的模块的作用域内解析，即使项目被重新导出。如果来自另一个板条箱的链接无法解析，则不会发出警告。

#![allow(unused)]
fn main() {
mod inner {
    /// Link to [f()]
    pub struct S;
    pub fn f() {}
}
pub use inner::S; // the link to `f` will still resolve correctly
}

重新导出项目时，rustdoc 允许向其添加其他文档。该附加文档将在重新导出的作用域内解析，而不是原始作用域内，允许您链接到新板条箱中的项目。如果新链接无法解析，它们仍然会发出警告。

#![allow(unused)]
fn main() {
/// See also [foo()]
pub use std::process::Command;

pub fn foo() {}
}

这对于 proc 宏特别有用，proc 宏必须始终在其自己的专用板条箱中定义。

注意：由于 macro_rules! 宏在 Rust 中的作用域方式，macro_rules! 宏的文档内链接将相对于板条箱根目录解析，而不是它定义的模块。

如果链接看起来“不够像”文档内链接，它们将被忽略，并且不会发出警告，即使链接无法解析。例如，任何包含 / 或 [] 字符的链接都将被忽略。

如果无法生成文档内链接会发生什么

在某些情况下（例如，位于 cfg 后面的项目），无法生成指向项目的文档内链接。在 Markdown 中创建链接有不同的方法，具体取决于您使用的方法，它在这种情况下将以不同的方式呈现

1. [a]
2. [b][c]
3. [d](e)
4. [f]

[f]: g

1. 和 2. 将在呈现的文档中按原样显示（即，[a] 和 [b][c]），而 3. 和 4. 将被替换为指向 e 的链接（对于 [d](e)）和 g（对于 [f]）。

Rustdoc 手册

通过名称链接到项目

有效链接

命名空间和消歧符

警告、重新导出和作用域

如果无法生成文档内链接会发生什么