如何在rustdoc中链接到其他函数/结构体/枚举/特性？

Question

如何在rustdoc中链接到其他函数/结构体/枚举/特性？

rustrustdoc

77

我正在构建一个Rust库并想要它更加完善。在 rustdoc 中，我有时想要在文档中链接到库中的其他部分，例如 fn、trait 或 struct。这个官方的语法是什么？

- llogiq

3

这里有一些讨论：https://internals.rust-lang.org/t/rustdoc-link-to-other-types-from-doc-comments/968 - oli_obk

3

这里有一个开放的RFC链接：https://github.com/rust-lang/rfcs/issues/792 - oli_obk

5个回答

46

从 Rust 1.48 开始，Rustdoc 现在支持直接的文档内链接。

Rust 1.48 之前：

Rustdoc 似乎为一个 crate 的组成元素生成大多数确定性的文件名。因此，如果您有一个名为Complex 的 enum，通常可以使用以下方式链接到它：

[Complex](enum.Complex.html)

同样地，一个名为Point的struct看起来像这样：

[Point](struct.Point.html)

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

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

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

或者使用绝对路径：

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

如果一个人建立文档 (cargo doc --no-deps --open) 并导航到他们想要的字段或项并注意 URL，就可以推断出更多关于这些“约定”的信息，包括特定字段的锚点等。请记住，只有 pub 项发布到文档中。

- GenKali

1

相对路径同样适用于其他模块中的对象：Point。 - Lanklaas

8

这个URL [Point](/crate_name/model/struct.Point.html) 看起来已经不能用了，至少当我在我的文件系统上打开文档时是这样的。它链接到 file:///crate_name/...。 - cyclaminist

1

此答案已过时。虽然这仍然可行，请参阅shepmaster的答案以获取更简单、最新的方法：https://dev59.com/IVwZ5IYBdhLWcg3wVfAC#53504254 - mkirk

10

如果想要在同一个结构体中链接一些特定的部分，例如命名为 foo 的方法（使用稳定版的 Rust，而非夜间版）。

[foo](#method.foo)

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

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

- tworec

1

在 Rust 的 1.49 nightly 版本中可以工作（1.48 稳定版尚未发布）：

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

等等。

点击此处阅读

- DKomen

-1

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

[anchor text](URL)

另外，也请看一下这个：https://doc.rust-lang.org/book/documentation.html。

- pczora

23

这并没有真正回答问题，因为我认为没有办法找出URL。 - kralyk

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Shepmaster · Accepted Answer

截至Rust 1.48，您现在可以依赖RFC 1946。这增加了内部文档链接的概念。这允许使用Rust路径作为链接的URL：

[Iterator](std::iter::Iterator)
[Iterator][iter]，并且在文档的其他地方：[iter]: std::iter::Iterator
[Iterator]，并且在文档的其他地方：[Iterator]: std::iter::Iterator

RFC还引入了"暗示的快捷引用链接"。这允许省略链接引用，然后自动推断。

[std::iter::Iterator]，没有在文档的任何其他地方定义Iterator的链接引用
[`std::iter::Iterator`]，没有在文档的任何其他地方定义Iterator的链接引用（与前一种样式相同，但使用反引号将链接格式化为行内代码）

作为一个具体的例子，这段源代码为：{{source 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>