🎓 A1Learner
🔍

Rust Documentation Attributes

Doc attributes are #[doc] settings that steer the documentation pages. One attribute can hide a helper from the pages.

The attribute under the sugar

These two forms write the same documentation:

#[doc = " Adds one."]
pub fn add_one(x: i32) -> i32 { x + 1 }

Findable under another name

#[doc(alias)] adds a search name — handy for the word that users coming from another language will type:

#[doc(alias = "plus_one")]
pub fn add_one(x: i32) -> i32 { x + 1 }

Show a re-export's docs in place

#[doc(inline)] sits on a pub use. It puts the item's docs on the re-export page itself. It does not send the reader away. The reader need not visit its home module:

mod inner {
    pub fn add_one(x: i32) -> i32 { x + 1 }
}
#[doc(inline)]
pub use inner::add_one;

A logo for the whole site

One inner attribute at the crate root brands every page:

#![doc(html_logo_url = "https://example.com/logo.png")]

One attribute for every doctest

At the crate root, test(attr(...)) adds an attribute. It adds it to all doctests at once. Here, dead code inside examples becomes an error:

#![doc(test(attr(deny(dead_code))))]

Example

/// Adds one to a number.
/// See also [subtract_one].
pub fn add_one(x: i32) -> i32 { x + 1 }
/// Subtracts one from a number.
/// Used in the docs of [add_one].
pub fn subtract_one(x: i32) -> i32 { x - 1 }
#[doc(hidden)]
pub fn secret_helper() -> i32 { 42 }
fn main() {
    println!("add = {}", add_one(4));
    println!("sub = {}", subtract_one(4));
    println!("hidden still runs = {}", secret_helper());
}

Key points

  • Crate-level forms steer the whole site: #![doc(html_logo_url = "...")] sets the logo, #![doc(html_favicon_url = "...")] sets the favicon, and #![doc(html_playground_url = "...")] chooses where Run buttons send examples
  • Use #!Put [doc(test(attr(deny(dead_code))))] at the crate root.
  • It adds an attribute to every doctest at once.
  • A module can add its own the same way.
  • The two lists are combined.
  • They are not replaced
  • #![doc(html_no_source)] hides the source links from your pages, for docs you publish but whose code you do not share
  • #![doc(html_root_url = "...")] tells other crates where your docs live online, so links from their pages to your items can work
  • Doc attributes are #[doc] settings that control what the documentation pages show and how they behave.

In this example, the two doc comments link to each other. [subtract_one] sits in the first comment. [add_one] sits in the second. Both become links on the generated pages. secret_helper carries #[doc(hidden)], so cargo doc builds it no page at all. But hidden only affects the pages. main still calls secret_helper(). It calls it like any public function. It prints hidden still runs = 42. That line sits between add = 5 and sub = 3.

Note

Doc attributes change only the pages, never the program.

#[doc(hidden)] is a curtain, not a lock — the item stays public, so never use it to hide a secret.

Try it Yourself

Edit the code, then press Run.

Running is simulated · Rust Playground

Exercise

What does #[doc(hidden)] do to an item?