Documentation

Linking Between Items

Intra-doc links allow you to link directly to other Rust types, functions, methods, modules, and traits using standard Markdown link syntax ([ItemName] or [display text][ItemName]) without hardcoding brittle HTML file paths or URLs. rustdoc resolves these Rust path references against the current scope and verifies every link at build time.

Source Doc Comment:
  /// Returns [`ParseError`] if [`Config::from_str`] fails, or [`None`] if empty.
                    |                     |                       |
                    v                     v                       v
Rendered HTML Links:
  `struct.ParseError.html`   `struct.Config.html#method.from_str`  `core/option/enum.Option.html#variant.None`

Intra-Doc Link Syntax Variants

Markdown Syntax Rendered Text Target Resolved By rustdoc
[`Client`] Client (in code font) Any item named Client in scope (or imported in the module).
[`Client::connect`] Client::connect Associated function or method connect on Client.
[connect a client][Client::connect] connect a client Associated method Client::connect with custom link prose.
[the configuration](Config) the configuration Standard inline Markdown link using a Rust path as the target.
[`Vec::push`] Vec::push Standard library items in the prelude or imported in scope.
[`crate::net::Pool`] crate::net::Pool Crate-absolute path (works even if Pool is not imported in the current file).

Disambiguating Namespaces (type@, fn@, macro@)

In Rust, a type, a function/value, and a macro can share the exact same name in the same scope (for example, std::vec the module vs vec! the macro, or a struct Point and a constructor function Point()). If an intra-doc link is ambiguous, prefix the target path with a namespace disambiguator or trailing syntax:

Disambiguator Meaning Shorthand Suffix Alternative
[`type@Foo`] / [`struct@Foo`] / [`enum@Foo`] Links to the type/struct/enum Foo —
[`fn@foo`] / [`value@foo`] / [`const@FOO`] Links to the function or constant foo [`foo()`] (trailing parentheses)
[`macro@vec`] Links to the declarative or procedural macro vec! [`vec!`] (trailing exclamation mark)
[`mod@serde`] Links to the module serde — 
#![deny(rustdoc::broken_intra_doc_links)]

/// Configuration error returned by [`parse_port`].
#[derive(Debug, PartialEq, Eq)]
pub struct PortError;

/// Parses a non-zero TCP port number.
///
/// Returns [`Ok`] with the parsed [`u16`], or [`Err`]`(`[`PortError`]`)`
/// if parsing fails or the port is `0`.
///
/// See also the [`default_port()`] helper function.
pub fn parse_port(raw: &str) -> Result<u16, PortError> {
    let port = raw.parse::<u16>().map_err(|_| PortError)?;
    if port == 0 {
        return Err(PortError);
    }
    Ok(port)
}

/// Returns the default HTTP port (`8080`) validated by [`fn@parse_port`].
pub const fn default_port() -> u16 {
    8080
}

fn main() {
    println!("Parsed port: {:?}", parse_port("443"));
    println!("Default port: {}", default_port());
}

Parsed port: Ok(443)
Default port: 8080

Catching Broken Links Automatically in CI

By default, rustdoc emits a warning (rustdoc::broken_intra_doc_links) whenever an intra-doc link target cannot be resolved or is renamed during refactoring. Adding #![deny(rustdoc::broken_intra_doc_links)] to src/lib.rs (or running RUSTDOCFLAGS="-D warnings" cargo doc --no-deps) ensures broken documentation links fail the build immediately.