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

Question

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?

Wideawake

there has been some discussion here: internals.rust-lang.org/t/… – Impress

and an open rfc here: github.com/rust-lang/rfcs/issues/792 – Impress

Answer 1

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.

Cyruscyst

Relative paths work as well for objects in other modules: [Point](../point/struct.Point.html) – Paxon

The URL [Point](/crate_name/model/struct.Point.html) seems not to work anymore, at least when I open docs on my filesystem. It links to file:///crate_name/.... – Mudd

This answer is outdated. Though this still works, please see shepmaster's answer for an easier up-to-date approach: https://mcmap.net/q/259462/-how-to-link-to-other-fns-structs-enums-traits-in-rustdoc – Dissyllable

Answer 2

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>

Gavra

For absolute module paths, [foo](crate::stuff::thing) seems to work. – Upwind

@Upwind yes, that's listed in the documentation I've linked. – Gavra

Is there a way to reference a different crate in the same workspace? E.g. I have a macros crate and the actual lib crate and I'd like to have a link from the documentation in the macros crate to the relevant code using the macro in the lib crate. In the macros crate, trying to link to [my_lib_crate::module::Symbol] warns of a broken link; trying [../my_lib_crate::module::Symbol] doesn't recognize this as a link. Any way to achieve this? – Amasa

@OrenBen-Kiki I'd expect that you'd need to import the lib crate from the macros crate and then that would allow you to reference it. – Gavra

Yes, one can have one-directional links this way if one crate uses another; but you can't have two-way links because that would cause a circular dependency between the crates. An option that works is for the lib crate to pub use the macros crate and re-export all the macros, and document everything in the lib crate. But there seems to be no way to freely link in both directions between two crates in a workspace...? – Amasa

@OrenBen-Kiki sounds like you want github.com/rust-lang/rust/issues/74481. What I have done for my procedural macros is to re-export them from the library and document them there. Rustdoc combines the documentation in that case. – Gavra

@Gavra - thanks for the link; yes, this is exactly what I was looking for. Seems there's no solution for now other than re-exprting everything from the inner crate out of the outer one, or inserting links using manual (fragile) URLs. – Amasa

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

Allpowerful

Answer 4

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

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

etc.

Read here

Haga

Answer 5

Since the documentation is written in Markdown, just use the Markdown syntax for Hyperlinks; i.e.

[anchor text](URL)

Also, take a look at this: https://doc.rust-lang.org/book/documentation.html

Avaunt

This doesn't really answer the question, because I don't think there's a way to figure out the URL. – Niela