如何在 rustdoc 中 link 到其他 fns/structs/enums/traits？

Question

我正在构建一个 Rust 库并想对其进行一些润色。在 rustdoc 中，我有时想 link 到文档中库的其他部分，例如fn 秒、trait 秒或 struct 秒。这个的官方语法是什么？

Answer 1

由于文档是用 Markdown 编写的，因此只需使用 Markdown 语法进行超链接；即

[anchor text](URL)

另外，看看这个：https://doc.rust-lang.org/book/documentation.html

Answer 2

Pre Rust 1.48:

Rustdoc 似乎为板条箱的组成元素生成了大部分确定性的文件名。因此，如果您有一个名为 Complex 的 enum，您通常可以 link 使用它：

[Complex](enum.Complex.html)

类似地，一个名为 Point 的 struct 看起来像：

[Point](struct.Point.html)

这应该适用于大多数定义（fn、trait，等等）。

要在不同的嵌套级别引用 crate 的元素，您可以使用相对路径（其中每个模块都是其自己的文件夹）：

[Point](../model/struct.Point.html)

或使用绝对路径：

[Point](/crate_name/model/struct.Point.html)

如果构建文档 (cargo doc --no-deps --open) 并导航到他们想要的字段或项目并记下URL。请记住，只有 pub 项目会发布到文档。

Answer 3

如果想要 link 结构的某些特定部分，例如，在同一结构中名为 foo 的方法（使用 stable rust，而不是每晚)

[foo](#method.foo)

或者如果它在另一个结构中

[foo](struct.OtherStruct.html#method.foo)

Answer 4

从 Rust 1.48, you can now rely on RFC 1946. This adds the concept of intra-documentation links. This allows using Rust paths 作为 URL 的 link:

[Iterator](std::iter::Iterator)

[Iterator][iter], and somewhere else in the document: [iter]: std::iter::Iterator

[Iterator], and somewhere else in the document: [Iterator]: std::iter::Iterator

RFC 还介绍了"Implied Shortcut Reference Links"。这允许省略 link 引用，然后自动推断。

[std::iter::Iterator], without having a link reference definition for Iterator anywhere else in the document

[`std::iter::Iterator`], without having a link reference definition for Iterator anywhere else in the document (same as previous style but with back ticks to format link as inline code)

作为一个具体的例子，这个源代码：

//! Check out [ExampleStruct], especially [this
//! method](ExampleStruct::foo), but [the trait method][trait] is also
//! cool. There is also [an enum variant you can
//! use](nested::ExampleEnum::Beta).
//!
//! [trait]: ExampleTrait::bar

pub struct ExampleStruct;

impl ExampleStruct {
    pub fn foo(&self) {}
}

pub trait ExampleTrait {
    fn bar();
}

pub mod nested {
    pub enum ExampleEnum {
        Alpha,
        Beta,
    }
}

生成此文档：

具体来说，生成这个HTML：

<p>Check out <a href="../doc_link_example/struct.ExampleStruct.html" title="ExampleStruct">ExampleStruct</a>, especially <a href="../doc_link_example/struct.ExampleStruct.html#method.foo">this method</a>, but <a href="../doc_link_example/trait.ExampleTrait.html#tymethod.bar">the trait method</a> is also cool. There is also <a href="../doc_link_example/nested/enum.ExampleEnum.html#Beta.v">an enum variant you can use</a>.</p>

Answer 5

在 Rust 1.49 nightly 中有效（1.48 稳定版尚未发布）：

[super::structs::WebApiResponse]
[mycrate::structs::WebApiResponse]

等等

Read here

如何在 rustdoc 中 link 到其他 fns/structs/enums/traits？

How to link to other fns/structs/enums/traits in rustdoc?

rust

rustdoc