1 # The `#[doc]` attribute
3 The `#[doc]` attribute lets you control various aspects of how `rustdoc` does
6 The most basic function of `#[doc]` is to handle the actual documentation
7 text. That is, `///` is syntax sugar for `#[doc]`. This means that these two
11 /// This is a doc comment.
12 #[doc = " This is a doc comment."]
16 (Note the leading space in the attribute version.)
18 In most cases, `///` is easier to use than `#[doc]`. One case where the latter is easier is
19 when generating documentation in macros; the `collapse-docs` pass will combine multiple
20 `#[doc]` attributes into a single doc comment, letting you generate code like this:
25 #[doc = "doc comment"]
29 Which can feel more flexible. Note that this would generate this:
32 #[doc = "This is\n a \ndoc comment"]
36 but given that docs are rendered via Markdown, it will remove these newlines.
38 Another use case is for including external files as documentation:
41 #[doc = include_str!("../README.md")]
45 The `doc` attribute has more options though! These don't involve the text of
46 the output, but instead, various aspects of the presentation of the output.
47 We've split them into two kinds below: attributes that are useful at the
48 crate level, and ones that are useful at the item level.
52 These options control how the docs look at a crate level.
54 ### `html_favicon_url`
56 This form of the `doc` attribute lets you control the favicon of your docs.
59 #![doc(html_favicon_url = "https://example.com/favicon.ico")]
62 This will put `<link rel="shortcut icon" href="{}">` into your docs, where
63 the string for the attribute goes into the `{}`.
65 If you don't use this attribute, there will be no favicon.
69 This form of the `doc` attribute lets you control the logo in the upper
70 left hand side of the docs.
73 #![doc(html_logo_url = "https://example.com/logo.jpg")]
76 This will put `<a href='index.html'><img src='{}' alt='logo' width='100'></a>` into
77 your docs, where the string for the attribute goes into the `{}`.
79 If you don't use this attribute, there will be no logo.
81 ### `html_playground_url`
83 This form of the `doc` attribute lets you control where the "run" buttons
84 on your documentation examples make requests to.
87 #![doc(html_playground_url = "https://playground.example.com/")]
90 Now, when you press "run", the button will make a request to this domain.
92 If you don't use this attribute, there will be no run buttons.
94 ### `issue_tracker_base_url`
96 This form of the `doc` attribute is mostly only useful for the standard library;
97 When a feature is unstable, an issue number for tracking the feature must be
98 given. `rustdoc` uses this number, plus the base URL given here, to link to
102 #![doc(issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/")]
107 The `#[doc(html_root_url = "…")]` attribute value indicates the URL for
108 generating links to external crates. When rustdoc needs to generate a link to
109 an item in an external crate, it will first check if the extern crate has been
110 documented locally on-disk, and if so link directly to it. Failing that, it
111 will use the URL given by the `--extern-html-root-url` command-line flag if
112 available. If that is not available, then it will use the `html_root_url`
113 value in the extern crate if it is available. If that is not available, then
114 the extern items will not be linked.
117 #![doc(html_root_url = "https://docs.rs/serde/1.0")]
122 By default, `rustdoc` will include the source code of your program, with links
123 to it in the docs. But if you include this:
126 #![doc(html_no_source)]
131 ### `test(no_crate_inject)`
133 By default, `rustdoc` will automatically add a line with `extern crate my_crate;` into each doctest.
134 But if you include this:
137 #![doc(test(no_crate_inject))]
142 ### `test(attr(...))`
144 This form of the `doc` attribute allows you to add arbitrary attributes to all your doctests. For
145 example, if you want your doctests to fail if they produce any warnings, you could add this:
148 #![doc(test(attr(deny(warnings))))]
153 These forms of the `#[doc]` attribute are used on individual items, to control how
156 ### `#[doc(no_inline)]`/`#[doc(inline)]`
158 These attributes are used on `use` statements, and control where the documentation shows
159 up. For example, consider this Rust code:
172 The documentation will generate a "Re-exports" section, and say `pub use bar::Bar;`, where
173 `Bar` is a link to its page.
175 If we change the `use` line like this:
180 # pub mod bar { pub struct Bar; }
184 Instead, `Bar` will appear in a `Structs` section, just like `Bar` was defined at the
185 top level, rather than `pub use`'d.
187 Let's change our original example, by making `bar` private:
200 Here, because `bar` is not public, `Bar` wouldn't have its own page, so there's nowhere
201 to link to. `rustdoc` will inline these definitions, and so we end up in the same case
202 as the `#[doc(inline)]` above; `Bar` is in a `Structs` section, as if it were defined at
203 the top level. If we add the `no_inline` form of the attribute:
217 Now we'll have a `Re-exports` line, and `Bar` will not link to anywhere.
219 One special case: In Rust 2018 and later, if you `pub use` one of your dependencies, `rustdoc` will
220 not eagerly inline it as a module unless you add `#[doc(inline)]`.
224 Any item annotated with `#[doc(hidden)]` will not appear in the documentation, unless
225 the `strip-hidden` pass is removed.
229 This attribute adds an alias in the search index.
231 Let's take an example:
234 #[doc(alias = "TheAlias")]
238 So now, if you enter "TheAlias" in the search, it'll display `SomeType`.
239 Of course, if you enter `SomeType` it'll return `SomeType` as expected!
243 This doc attribute is especially useful when writing bindings for a C library.
244 For example, let's say we have a C function that looks like this:
247 int lib_name_do_something(Obj *obj);
250 It takes a pointer to an `Obj` type and returns an integer. In Rust, it might
251 be written like this:
253 ```ignore (using non-existing ffi types)
255 inner: *mut ffi::Obj,
259 pub fn do_something(&mut self) -> i32 {
260 unsafe { ffi::lib_name_do_something(self.inner) }
265 The function has been turned into a method to make it more convenient to use.
266 However, if you want to look for the Rust equivalent of `lib_name_do_something`,
267 you have no way to do so.
269 To get around this limitation, we just add `#[doc(alias = "lib_name_do_something")]`
270 on the `do_something` method and then it's all good!
271 Users can now look for `lib_name_do_something` in our crate directly and find