Attributes and Conditional Compilation

#[doc(...)]

#[doc = "..."] and #[doc(...)] are the attributes that control documentation generation in rustdoc (cargo doc). Every /// text outer doc comment and //! text inner doc comment in Rust is syntactic sugar that the parser desugars directly into #[doc = " text"] and #![doc = " text"] attributes.

Essential #[doc(...)] Sub-Attributes

Beyond plain text strings (#[doc = "..."]), #[doc(...)] supports directives that control visibility, re-export rendering, search aliases, and external Markdown inclusion:

Attribute Target Effect in cargo doc Output
#[doc = include_str!("../README.md")] Crate / Module / Item Embeds an external Markdown file directly as the item's documentation (and runs its rust code blocks during cargo test --doc!)
#[doc(hidden)] Any pub item or pub use Hides the item from generated HTML documentation while keeping it pub for macros or internal sub-crates
#[doc(inline)] pub use re-export Renders the re-exported item inline on the current module page instead of showing a Re-exports link
#[doc(no_inline)] pub use re-export Forces rustdoc to render a pub use as a short Re-exports link rather than inlining full docs
#[doc(alias = "term")] Any documented item Adds alternative search terms (#[doc(alias = "lerp")] or operator symbols #[doc(alias = "+")]) to the rustdoc search bar
#![doc(html_root_url = "...")] / html_logo_url Crate root (#![doc(...)]) Customizes branding and root URLs in generated HTML docs 
How `///` Desugars to `#[doc = "..."]`:

  /// Computes linear interpolation.       #[doc = " Computes linear interpolation."]
  ///                                ===>  #[doc = ""]
  /// Returns `a + t * (b - a)`.           #[doc = " Returns `a + t * (b - a)`."]
  pub fn mix(a: f64, b: f64, t: f64)       pub fn mix(a: f64, b: f64, t: f64)

Using #[doc(alias)], #[doc(hidden)], and Macro-Generated #[doc = ...]

Because #[doc = ...] accepts any string literal or macro expansion that produces a string literal (such as concat!(...) or stringify!(...)), declarative macros can generate customized documentation for every generated function or struct!

/// Performs linear interpolation between `start` and `end`.
#[doc(alias = "lerp")]
#[doc(alias = "blend")]
pub fn interpolate(start: f64, end: f64, t: f64) -> f64 {
    start + t * (end - start)
}

// Public only so exported macros in this crate can call it; hidden from user docs:
#[doc(hidden)]
pub fn __internal_macro_helper() -> &'static str {
    "macro-internal"
}

macro_rules! define_constant_getter {
    ($fn_name:ident, $val:expr) => {
        #[doc = concat!("Returns the compile-time constant `", stringify!($val), "`.")]
        pub const fn $fn_name() -> u32 {
            $val
        }
    };
}

define_constant_getter!(protocol_version, 4);

fn main() {
    println!("interpolate(0.0, 10.0, 0.25) = {}", interpolate(0.0, 10.0, 0.25));
    println!("protocol_version() = {}", protocol_version());
    println!("helper = {}", __internal_macro_helper());
}

interpolate(0.0, 10.0, 0.25) = 2.5
protocol_version() = 4
helper = macro-internal