src/doc/rustdoc/src/the-doc-attribute.md

   1 # The `#[doc]` attribute
   2
   3 The `#[doc]` attribute lets you control various aspects of how `rustdoc` does
   4 its job.
   5
   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
   8 are the same:
   9
  10 ```rust,no_run
  11 /// This is a doc comment.
  12 #[doc = " This is a doc comment."]
  13 # fn f() {}
  14 ```
  15
  16 (Note the leading space in the attribute version.)
  17
  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:
  21
  22 ```rust,no_run
  23 #[doc = "This is"]
  24 #[doc = " a "]
  25 #[doc = "doc comment"]
  26 # fn f() {}
  27 ```
  28
  29 Which can feel more flexible. Note that this would generate this:
  30
  31 ```rust,no_run
  32 #[doc = "This is\n a \ndoc comment"]
  33 # fn f() {}
  34 ```
  35
  36 but given that docs are rendered via Markdown, it will remove these newlines.
  37
  38 Another use case is for including external files as documentation:
  39
  40 ```rust,no_run
  41 #[doc = include_str!("../README.md")]
  42 # fn f() {}
  43 ```
  44
  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.
  49
  50 ## At the crate level
  51
  52 These options control how the docs look at a crate level.
  53
  54 ### `html_favicon_url`
  55
  56 This form of the `doc` attribute lets you control the favicon of your docs.
  57
  58 ```rust,no_run
  59 #![doc(html_favicon_url = "https://example.com/favicon.ico")]
  60 ```
  61
  62 This will put `<link rel="icon" href="{}">` into your docs, where
  63 the string for the attribute goes into the `{}`.
  64
  65 If you don't use this attribute, there will be no favicon.
  66
  67 ### `html_logo_url`
  68
  69 This form of the `doc` attribute lets you control the logo in the upper
  70 left hand side of the docs.
  71
  72 ```rust,no_run
  73 #![doc(html_logo_url = "https://example.com/logo.jpg")]
  74 ```
  75
  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 `{}`.
  78
  79 If you don't use this attribute, there will be no logo.
  80
  81 ### `html_playground_url`
  82
  83 This form of the `doc` attribute lets you control where the "run" buttons
  84 on your documentation examples make requests to.
  85
  86 ```rust,no_run
  87 #![doc(html_playground_url = "https://playground.example.com/")]
  88 ```
  89
  90 Now, when you press "run", the button will make a request to this domain.
  91
  92 If you don't use this attribute, there will be no run buttons.
  93
  94 ### `issue_tracker_base_url`
  95
  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
  99 the tracking issue.
 100
 101 ```rust,no_run
 102 #![doc(issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/")]
 103 ```
 104
 105 ### `html_root_url`
 106
 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.
 115
 116 ```rust,no_run
 117 #![doc(html_root_url = "https://docs.rs/serde/1.0")]
 118 ```
 119
 120 ### `html_no_source`
 121
 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:
 124
 125 ```rust,no_run
 126 #![doc(html_no_source)]
 127 ```
 128
 129 it will not.
 130
 131 ### `test(no_crate_inject)`
 132
 133 By default, `rustdoc` will automatically add a line with `extern crate my_crate;` into each doctest.
 134 But if you include this:
 135
 136 ```rust,no_run
 137 #![doc(test(no_crate_inject))]
 138 ```
 139
 140 it will not.
 141
 142 ### `test(attr(...))`
 143
 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:
 146
 147 ```rust,no_run
 148 #![doc(test(attr(deny(warnings))))]
 149 ```
 150
 151 ## At the item level
 152
 153 These forms of the `#[doc]` attribute are used on individual items, to control how
 154 they are documented.
 155
 156 ### `inline` and `no_inline`
 157
 158 <span id="docno_inlinedocinline"></span>
 159
 160 These attributes are used on `use` statements, and control where the documentation shows
 161 up. For example, consider this Rust code:
 162
 163 ```rust,no_run
 164 pub use bar::Bar;
 165
 166 /// bar docs
 167 pub mod bar {
 168     /// the docs for Bar
 169     pub struct Bar;
 170 }
 171 # fn main() {}
 172 ```
 173
 174 The documentation will generate a "Re-exports" section, and say `pub use bar::Bar;`, where
 175 `Bar` is a link to its page.
 176
 177 If we change the `use` line like this:
 178
 179 ```rust,no_run
 180 #[doc(inline)]
 181 pub use bar::Bar;
 182 # pub mod bar { pub struct Bar; }
 183 # fn main() {}
 184 ```
 185
 186 Instead, `Bar` will appear in a `Structs` section, just like `Bar` was defined at the
 187 top level, rather than `pub use`'d.
 188
 189 Let's change our original example, by making `bar` private:
 190
 191 ```rust,no_run
 192 pub use bar::Bar;
 193
 194 /// bar docs
 195 mod bar {
 196     /// the docs for Bar
 197     pub struct Bar;
 198 }
 199 # fn main() {}
 200 ```
 201
 202 Here, because `bar` is not public, `Bar` wouldn't have its own page, so there's nowhere
 203 to link to. `rustdoc` will inline these definitions, and so we end up in the same case
 204 as the `#[doc(inline)]` above; `Bar` is in a `Structs` section, as if it were defined at
 205 the top level. If we add the `no_inline` form of the attribute:
 206
 207 ```rust,no_run
 208 #[doc(no_inline)]
 209 pub use bar::Bar;
 210
 211 /// bar docs
 212 mod bar {
 213     /// the docs for Bar
 214     pub struct Bar;
 215 }
 216 # fn main() {}
 217 ```
 218
 219 Now we'll have a `Re-exports` line, and `Bar` will not link to anywhere.
 220
 221 One special case: In Rust 2018 and later, if you `pub use` one of your dependencies, `rustdoc` will
 222 not eagerly inline it as a module unless you add `#[doc(inline)]`.
 223
 224 ### `hidden`
 225
 226 <span id="dochidden"></span>
 227
 228 Any item annotated with `#[doc(hidden)]` will not appear in the documentation, unless
 229 the `strip-hidden` pass is removed.
 230
 231 ### `alias`
 232
 233 This attribute adds an alias in the search index.
 234
 235 Let's take an example:
 236
 237 ```rust,no_run
 238 #[doc(alias = "TheAlias")]
 239 pub struct SomeType;
 240 ```
 241
 242 So now, if you enter "TheAlias" in the search, it'll display `SomeType`.
 243 Of course, if you enter `SomeType` it'll return `SomeType` as expected!
 244
 245 #### FFI example
 246
 247 This doc attribute is especially useful when writing bindings for a C library.
 248 For example, let's say we have a C function that looks like this:
 249
 250 ```c
 251 int lib_name_do_something(Obj *obj);
 252 ```
 253
 254 It takes a pointer to an `Obj` type and returns an integer. In Rust, it might
 255 be written like this:
 256
 257 ```ignore (using non-existing ffi types)
 258 pub struct Obj {
 259     inner: *mut ffi::Obj,
 260 }
 261
 262 impl Obj {
 263     pub fn do_something(&mut self) -> i32 {
 264         unsafe { ffi::lib_name_do_something(self.inner) }
 265     }
 266 }
 267 ```
 268
 269 The function has been turned into a method to make it more convenient to use.
 270 However, if you want to look for the Rust equivalent of `lib_name_do_something`,
 271 you have no way to do so.
 272
 273 To get around this limitation, we just add `#[doc(alias = "lib_name_do_something")]`
 274 on the `do_something` method and then it's all good!
 275 Users can now look for `lib_name_do_something` in our crate directly and find
 276 `Obj::do_something`.