leonardomso__rust-skills/rules/doc-intra-links.md

doc-intra-links

Use intra-doc links to reference types and items

Why It Matters

Intra-doc links ([TypeName], [method](Self::method)) create clickable references in generated documentation. They're verified at doc-build time, catching broken links early. Unlike URL links, they automatically update when items are renamed or moved.

Bad

/// Returns the length of the buffer.
/// 
/// See also `capacity()` for the allocated size, and the
/// `Buffer` struct for more details.
pub fn len(&self) -> usize {
    self.data.len()
}

/// Parses the input using std::str::FromStr trait.
/// Check the Error enum for possible failures.
pub fn parse<T: FromStr>(input: &str) -> Result<T, Error> {
    // ...
}

Good

/// Returns the length of the buffer.
/// 
/// See also [`capacity()`](Self::capacity) for the allocated size, and
/// [`Buffer`] for more details.
pub fn len(&self) -> usize {
    self.data.len()
}

/// Parses the input using [`FromStr`] trait.
/// Check [`Error`] for possible failures.
///
/// [`FromStr`]: std::str::FromStr
pub fn parse<T: FromStr>(input: &str) -> Result<T, Error> {
    // ...
}

Link Syntax

Syntax	Links To	Example
[Name]	Item in scope	[Vec], [Option]
[path::Name]	Fully qualified item	[std::vec::Vec]
[Self::method]	Method on current type	[Self::new]
[Type::method]	Method on other type	[String::new]
[Type::CONST]	Associated constant	[usize::MAX]
[text](path)	Custom text	[see here](Self::len)

Common Patterns

Linking to Self Members

impl Buffer {
    /// Creates an empty buffer.
    ///
    /// Use [`with_capacity`](Self::with_capacity) if you know the size.
    pub fn new() -> Self { /* ... */ }
    
    /// Creates a buffer with pre-allocated capacity.
    ///
    /// See [`new`](Self::new) for the default constructor.
    pub fn with_capacity(cap: usize) -> Self { /* ... */ }
}

Linking to Trait Methods

/// Converts to a string representation.
///
/// This is the implementation of [`Display::fmt`](std::fmt::Display::fmt).
impl Display for MyType {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        // ...
    }
}

Disambiguation

When names conflict, use suffixes:

/// See [`foo()`](fn@foo) for the function and [`foo`](mod@foo) for the module.

/// Works with [`Error`](struct@Error) struct or [`Error`](trait@Error) trait.

Suffix	Item Type
fn@	Function
mod@	Module
struct@	Struct
enum@	Enum
trait@	Trait
type@	Type alias
const@	Constant
macro@	Macro

Reference-Style Links

For repeated links or long paths:

/// Parses using [`serde`] with [`Deserialize`] trait.
/// Returns a [`Result`] that may contain [`Error`].
///
/// [`serde`]: https://serde.rs
/// [`Deserialize`]: serde::Deserialize
/// [`Result`]: std::result::Result
/// [`Error`]: crate::Error

Verification

Enable link checking in CI:

RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

This fails if any intra-doc links are broken.

See Also

• doc-all-public - Documenting public items
• doc-examples-section - Adding examples
• doc-errors-section - Documenting errors