如何链接到rustdoc中的其他fns/structs/enums/traits？

Question

我正在构建一个Rust库,并希望给它一些润色.在rustdoc中,我有时想在文档中链接到库的其他部分,例如fns,traits或structs.这是什么官方语法？

Answer 1

RFC 1946增加了文档内链接的概念.这允许使用Rust路径作为链接的URL:

[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

此功能尚未稳定,但如果您使用夜间工具链构建文档,则会自动启用该功能.

作为一个具体的例子,这个源代码:

//! 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 2

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

[Complex](enum.Complex.html)

同样,struct被叫的Point看起来像:

[Point](struct.Point.html)

这应该延续到大多数定义(fn,trait等等).

我应该注意到,在某些情况下这可能不起作用.无论出于何种原因,如果生成的HTML文件rustdoc最终生成不同的嵌套级别,我上面列出的相对链接可能会404.我还没有遇到这个问题.

Answer 3

如果想要链接结构的某些特定部分，例如，foo在同一结构中命名的方法（使用稳定的rust，而不是nightly）

[foo](#method.foo)

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

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