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

In Rust 1.49 nightly it works (1.48 stable not released yet):

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

etc.

Read here


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:

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

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)

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.

Tags:

Rust

Rustdoc