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

I'm building a Rust library and want to give it some polish. In the rustdoc, I'd sometimes like to link to other parts of the library within the docs, e.g. fns, traits or structs. What is the official syntax for this?

Solution 1:

As of Rust 1.48, you can now rely on RFC 1946. This adds the concept of intra-documentation links. This allows using Rust paths as the URL of a link:

1. [Iterator](std::iter::Iterator)
2. [Iterator][iter], and somewhere else in the document: [iter]: std::iter::Iterator
3. [Iterator], and somewhere else in the document: [Iterator]: std::iter::Iterator

The RFC also introduces "Implied Shortcut Reference Links". This allows leaving out the link reference, which is then inferred automatically.

1. [std::iter::Iterator], without having a link reference definition for Iterator anywhere else in the document
2. [`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)

As a concrete example, this 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,
    }
}

Produces this documentation:

Specifically, this HTML is generated:

<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>

Solution 2:

As of Rust 1.48, Rustdoc now supports direct intra-doc links.

Pre Rust 1.48:

Rustdoc seems to generate mostly deterministic filenames for constituent elements of a crate. Therefore if you have an enum named Complex you can generally link to it using:

[Complex](enum.Complex.html)

Similarly a struct called Point would look like:

[Point](struct.Point.html)

This should carry over to most definitions (fn, trait, and so on).

For referencing elements of a crate at different nesting levels, you can use relative paths (where each module is its own folder):

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

or use absolute paths:

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

More of these "conventions", including anchors for specific fields, etc., can be deduced if one builds docs (cargo doc --no-deps --open) and navigates to the field or item they want and takes note of the URL. Remember that only pub items are published to docs.

Solution 3:

If one wants to link some specific part of a struct e.g., a method named foo in the same struct (using stable rust, not nightly)

[foo](#method.foo)

or if it is in another struct

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