intra-doc-links

name	intra-doc-links
description	Use when writing or editing a Rust doc comment that references a type, method, or module — link the reference so renames are caught by rustdoc.
metadata	{"author":"0xMiden"}

Use Intra-Doc Links in Rust Doc Comments

Rule

When a doc comment mentions a type, method, trait, constant, or module that exists in scope, write it as an intra-doc link:

/// Returns the [`AccountId`] associated with this [`Account`].
///
/// See also [`AccountStorage::commitment`] for the storage commitment.

Use [Name] for items already in scope; use [Name](crate::path::Name) for items elsewhere; use [Name]: ... reference-style at the bottom for long paths.

Do not write type names as plain text or inside single backticks alone (e.g. `AccountId` without brackets) when the item is reachable from rustdoc.

Why

Intra-doc links are checked by rustdoc, so renaming a linked item produces a warning while plain-text references silently go stale. They also render as clickable navigation in the generated docs.

Examples

// Good
/// Returns the [`AccountId`] of this account.
///
/// # Errors
///
/// Returns [`AccountError::NotFound`] if the storage slot is empty.
pub fn account_id(&self) -> Result<AccountId, AccountError> { ... }

// Bad
/// Returns the `AccountId` of this account.
///
/// # Errors
///
/// Returns `AccountError::NotFound` if the storage slot is empty.
pub fn account_id(&self) -> Result<AccountId, AccountError> { ... }

---

Source: 0xMiden/protocol — distributed by TomeVault.