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,ignore
  11 /// This is a doc comment.
  12 #[doc = " This is a doc comment."]
  13 ```
  14
  15 (Note the leading space in the attribute version.)
  16
  17 In most cases, `///` is easier to use than `#[doc]`. One case where the latter is easier is
  18 when generating documentation in macros; the `collapse-docs` pass will combine multiple
  19 `#[doc]` attributes into a single doc comment, letting you generate code like this:
  20
  21 ```rust,ignore
  22 #[doc = "This is"]
  23 #[doc = " a "]
  24 #[doc = "doc comment"]
  25 ```
  26
  27 Which can feel more flexible. Note that this would generate this:
  28
  29 ```rust,ignore
  30 #[doc = "This is\n a \ndoc comment"]
  31 ```
  32
  33 but given that docs are rendered via Markdown, it will remove these newlines.
  34
  35 The `doc` attribute has more options though! These don't involve the text of
  36 the output, but instead, various aspects of the presentation of the output.
  37 We've split them into two kinds below: attributes that are useful at the
  38 crate level, and ones that are useful at the item level.
  39
  40 ## At the crate level
  41
  42 These options control how the docs look at a macro level.
  43
  44 ### `html_favicon_url`
  45
  46 This form of the `doc` attribute lets you control the favicon of your docs.
  47
  48 ```rust,ignore
  49 #![doc(html_favicon_url = "https://example.com/favicon.ico")]
  50 ```
  51
  52 This will put `<link rel="shortcut icon" href="{}">` into your docs, where
  53 the string for the attribute goes into the `{}`.
  54
  55 If you don't use this attribute, there will be no favicon.
  56
  57 ### `html_logo_url`
  58
  59 This form of the `doc` attribute lets you control the logo in the upper
  60 left hand side of the docs.
  61
  62 ```rust,ignore
  63 #![doc(html_logo_url = "https://example.com/logo.jpg")]
  64 ```
  65
  66 This will put `<a href='index.html'><img src='{}' alt='logo' width='100'></a>` into
  67 your docs, where the string for the attribute goes into the `{}`.
  68
  69 If you don't use this attribute, there will be no logo.
  70
  71 ### `html_playground_url`
  72
  73 This form of the `doc` attribute lets you control where the "run" buttons
  74 on your documentation examples make requests to.
  75
  76 ```rust,ignore
  77 #![doc(html_playground_url = "https://playground.example.com/")]
  78 ```
  79
  80 Now, when you press "run", the button will make a request to this domain.
  81
  82 If you don't use this attribute, there will be no run buttons.
  83
  84 ### `issue_tracker_base_url`
  85
  86 This form of the `doc` attribute is mostly only useful for the standard library;
  87 When a feature is unstable, an issue number for tracking the feature must be
  88 given. `rustdoc` uses this number, plus the base URL given here, to link to
  89 the tracking issue.
  90
  91 ```rust,ignore
  92 #![doc(issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/")]
  93 ```
  94
  95 ### `html_root_url`
  96
  97 The `#[doc(html_root_url = "…")]` attribute value indicates the URL for
  98 generating links to external crates. When rustdoc needs to generate a link to
  99 an item in an external crate, it will first check if the extern crate has been
 100 documented locally on-disk, and if so link directly to it. Failing that, it
 101 will use the URL given by the `--extern-html-root-url` command-line flag if
 102 available. If that is not available, then it will use the `html_root_url`
 103 value in the extern crate if it is available. If that is not available, then
 104 the extern items will not be linked.
 105
 106 ```rust,ignore
 107 #![doc(html_root_url = "https://docs.rs/serde/1.0")]
 108 ```
 109
 110 ### `html_no_source`
 111
 112 By default, `rustdoc` will include the source code of your program, with links
 113 to it in the docs. But if you include this:
 114
 115 ```rust,ignore
 116 #![doc(html_no_source)]
 117 ```
 118
 119 it will not.
 120
 121 ### `test(no_crate_inject)`
 122
 123 By default, `rustdoc` will automatically add a line with `extern crate my_crate;` into each doctest.
 124 But if you include this:
 125
 126 ```rust,ignore
 127 #![doc(test(no_crate_inject))]
 128 ```
 129
 130 it will not.
 131
 132 ### `test(attr(...))`
 133
 134 This form of the `doc` attribute allows you to add arbitrary attributes to all your doctests. For
 135 example, if you want your doctests to fail if they produce any warnings, you could add this:
 136
 137 ```rust,ignore
 138 #![doc(test(attr(deny(warnings))))]
 139 ```
 140
 141 ## At the item level
 142
 143 These forms of the `#[doc]` attribute are used on individual items, to control how
 144 they are documented.
 145
 146 ## `#[doc(no_inline)]`/`#[doc(inline)]`
 147
 148 These attributes are used on `use` statements, and control where the documentation shows
 149 up. For example, consider this Rust code:
 150
 151 ```rust,ignore
 152 pub use bar::Bar;
 153
 154 /// bar docs
 155 pub mod bar {
 156     /// the docs for Bar
 157     pub struct Bar;
 158 }
 159 ```
 160
 161 The documentation will generate a "Re-exports" section, and say `pub use bar::Bar;`, where
 162 `Bar` is a link to its page.
 163
 164 If we change the `use` line like this:
 165
 166 ```rust,ignore
 167 #[doc(inline)]
 168 pub use bar::Bar;
 169 ```
 170
 171 Instead, `Bar` will appear in a `Structs` section, just like `Bar` was defined at the
 172 top level, rather than `pub use`'d.
 173
 174 Let's change our original example, by making `bar` private:
 175
 176 ```rust,ignore
 177 pub use bar::Bar;
 178
 179 /// bar docs
 180 mod bar {
 181     /// the docs for Bar
 182     pub struct Bar;
 183 }
 184 ```
 185
 186 Here, because `bar` is not public, `Bar` wouldn't have its own page, so there's nowhere
 187 to link to. `rustdoc` will inline these definitions, and so we end up in the same case
 188 as the `#[doc(inline)]` above; `Bar` is in a `Structs` section, as if it were defined at
 189 the top level. If we add the `no_inline` form of the attribute:
 190
 191 ```rust,ignore
 192 #[doc(no_inline)]
 193 pub use bar::Bar;
 194
 195 /// bar docs
 196 mod bar {
 197     /// the docs for Bar
 198     pub struct Bar;
 199 }
 200 ```
 201
 202 Now we'll have a `Re-exports` line, and `Bar` will not link to anywhere.
 203
 204 One special case: In Rust 2018 and later, if you `pub use` one of your dependencies, `rustdoc` will
 205 not eagerly inline it as a module unless you add `#[doc(inline)]`.
 206
 207 ## `#[doc(hidden)]`
 208
 209 Any item annotated with `#[doc(hidden)]` will not appear in the documentation, unless
 210 the `strip-hidden` pass is removed.
 211
 212 ## `#[doc(primitive)]`
 213
 214 Since primitive types are defined in the compiler, there's no place to attach documentation
 215 attributes. This attribute is used by the standard library to provide a way to generate
 216 documentation for primitive types.
 217
 218 ## `#[cfg(rustdoc)]`: Documenting platform-/feature-specific information
 219
 220 For conditional compilation, Rustdoc treats your crate the same way the compiler does: Only things
 221 from the host target are available (or from the given `--target` if present), and everything else is
 222 "filtered out" from the crate. This can cause problems if your crate is providing different things
 223 on different targets and you want your documentation to reflect all the available items you
 224 provide.
 225
 226 If you want to make sure an item is seen by Rustdoc regardless of what platform it's targeting,
 227 you can apply `#[cfg(rustdoc)]` to it. Rustdoc sets this whenever it's building documentation, so
 228 anything that uses that flag will make it into documentation it generates. To apply this to an item
 229 with other `#[cfg]` filters on it, you can write something like `#[cfg(any(windows, rustdoc))]`.
 230 This will preserve the item either when built normally on Windows, or when being documented
 231 anywhere.
 232
 233 Please note that this feature won't be passed when building doctests.
 234
 235 Example:
 236
 237 ```rust
 238 /// Token struct that can only be used on Windows.
 239 #[cfg(any(windows, rustdoc))]
 240 pub struct WindowsToken;
 241 /// Token struct that can only be used on Unix.
 242 #[cfg(any(unix, rustdoc))]
 243 pub struct UnixToken;
 244 ```
 245
 246 Here, the respective tokens can only be used by dependent crates on their respective platforms, but
 247 they will both appear in documentation.