The#[doc] attribute

The#[doc] attribute lets you control various aspects of howrustdoc doesits job.

The most basic function of#[doc] is to handle the actual documentationtext. That is,/// is syntax sugar for#[doc]. This means that these twoare the same:

#![allow(unused)]fn main() {/// This is a doc comment.#[doc = r" This is a doc comment."]fn f() {}}

(Note the leading space and the raw string literal in the attribute version.)

In most cases,/// is easier to use than#[doc]. One case where the latter is easier iswhen generating documentation in macros; thecollapse-docs pass will combine multiple#[doc] attributes into a single doc comment, letting you generate code like this:

#![allow(unused)]fn main() {#[doc = "This is"]#[doc = " a "]#[doc = "doc comment"]fn f() {}}

Which can feel more flexible. Note that this would generate this:

#![allow(unused)]fn main() {#[doc = "This is\n a \ndoc comment"]fn f() {}}

but given that docs are rendered via Markdown, it will remove these newlines.

Another use case is for including external files as documentation:

#![allow(unused)]fn main() {#[doc = include_str!("../../README.md")]fn f() {}}

Thedoc attribute has more options though! These don't involve the text ofthe output, but instead, various aspects of the presentation of the output.We've split them into two kinds below: attributes that are useful at thecrate level, and ones that are useful at the item level.

At the crate level

These options control how the docs look at a crate level.

html_favicon_url

This form of thedoc attribute lets you control the favicon of your docs.

#![allow(unused)]#![doc(html_favicon_url = "https://example.com/favicon.ico")]fn main() {}

This will put<link rel="icon" href="{}"> into your docs, wherethe string for the attribute goes into the{}.

If you don't use this attribute, a default favicon will be used.

html_logo_url

This form of thedoc attribute lets you control the logo in the upperleft hand side of the docs.

#![allow(unused)]#![doc(html_logo_url = "https://example.com/logo.jpg")]fn main() {}

This will put<a href='../index.html'><img src='{}' alt='logo' width='100'></a> intoyour docs, where the string for the attribute goes into the{}.

If you don't use this attribute, there will be no logo.

html_playground_url

This form of thedoc attribute lets you control where the "run" buttonson your documentation examples make requests to.

#![allow(unused)]#![doc(html_playground_url = "https://playground.example.com/")]fn main() {}

Now, when you press "run", the button will make a request to this domain. The requestURL will contain 3 query parameters:

1. code for the code in the documentation
2. version for the Rust channel, e.g. nightly, which is decided by whethercode contain unstable features
3. edition for the Rust edition, e.g. 2024

If you don't use this attribute, there will be no run buttons.

issue_tracker_base_url

This form of thedoc attribute is mostly only useful for the standard library;When a feature is unstable, an issue number for tracking the feature must begiven.rustdoc uses this number, plus the base URL given here, to link tothe tracking issue.

#![allow(unused)]#![doc(issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/")]fn main() {}

html_root_url

The#[doc(html_root_url = "…")] attribute value indicates the URL forgenerating links to external crates. When rustdoc needs to generate a link toan item in an external crate, it will first check if the extern crate has beendocumented locally on-disk, and if so link directly to it. Failing that, itwill use the URL given by the--extern-html-root-url command-line flag ifavailable. If that is not available, then it will use thehtml_root_urlvalue in the extern crate if it is available. If that is not available, thenthe extern items will not be linked.

#![allow(unused)]#![doc(html_root_url = "https://docs.rs/serde/1.0")]fn main() {}

html_no_source

By default,rustdoc will include the source code of your program, with linksto it in the docs. But if you include this:

#![allow(unused)]#![doc(html_no_source)]fn main() {}

it will not.

test(no_crate_inject)

By default,rustdoc will automatically add a line withextern crate my_crate; into each doctest.But if you include this:

#![allow(unused)]#![doc(test(no_crate_inject))]fn main() {}

it will not.

At the item level

These forms of the#[doc] attribute are used on individual items, to control howthey are documented.

inline andno_inline

These attributes are used onuse statements, and control where the documentation showsup. For example, consider this Rust code:

pub use bar::Bar;/// bar docspub mod bar {    /// the docs for Bar    pub struct Bar;}fn main() {}

The documentation will generate a "Re-exports" section, and saypub use bar::Bar;, whereBar is a link to its page.

If we change theuse line like this:

#[doc(inline)]pub use bar::Bar;pub mod bar { pub struct Bar; }fn main() {}

Instead,Bar will appear in aStructs section, just likeBar was defined at thetop level, rather thanpub use'd.

Let's change our original example, by makingbar private:

pub use bar::Bar;/// bar docsmod bar {    /// the docs for Bar    pub struct Bar;}fn main() {}

Here, becausebar is not public,bar wouldn't have its own page, so there's nowhereto link to.rustdoc will inline these definitions, and so we end up in the same caseas the#[doc(inline)] above;Bar is in aStructs section, as if it were defined atthe top level. If we add theno_inline form of the attribute:

#[doc(no_inline)]pub use bar::Bar;/// bar docsmod bar {    /// the docs for Bar    pub struct Bar;}fn main() {}

Now we'll have aRe-exports line, andBar will not link to anywhere.

One special case: In Rust 2018 and later, if youpub use one of your dependencies,rustdoc willnot eagerly inline it as a module unless you add#[doc(inline)].

If you want to know more about inlining rules, take a look at there-exports chapter.

hidden

Any item annotated with#[doc(hidden)] will not appear in the documentation,unless the--document-hidden-items flag is used.

You can find more information in there-exports chapter.

alias

This attribute adds an alias in the search index.

Let's take an example:

#![allow(unused)]fn main() {#[doc(alias = "TheAlias")]pub struct SomeType;}

So now, if you enter "TheAlias" in the search, it'll displaySomeType.Of course, if you enterSomeType it'll returnSomeType as expected!

FFI example

This doc attribute is especially useful when writing bindings for a C library.For example, let's say we have a C function that looks like this:

int lib_name_do_something(Obj *obj);

It takes a pointer to anObj type and returns an integer. In Rust, it mightbe written like this:

pub struct Obj {    inner: *mut ffi::Obj,}impl Obj {    pub fn do_something(&mut self) -> i32 {        unsafe { ffi::lib_name_do_something(self.inner) }    }}

The function has been turned into a method to make it more convenient to use.However, if you want to look for the Rust equivalent oflib_name_do_something,you have no way to do so.

To get around this limitation, we just add#[doc(alias = "lib_name_do_something")]on thedo_something method and then it's all good!Users can now look forlib_name_do_something in our crate directly and findObj::do_something.

test(attr(...))

This form of thedoc attribute allows you to add arbitrary attributes to all your doctests. Forexample, if you want your doctests to fail if they have dead code, you could add this:

#![allow(unused)]#![doc(test(attr(deny(dead_code))))]fn main() {mod my_mod {    #![doc(test(attr(allow(dead_code))))] // but allow `dead_code` for this module}}

test(attr(..)) attributes are appended to the parent module's, they do not replace the currentlist of attributes. In the previous example, both attributes would be present:

#![allow(unused)]fn main() {// For every doctest in `my_mod`#![deny(dead_code)] // from the crate-root#![allow(dead_code)] // from `my_mod`}