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_no_source`
  96
  97 By default, `rustdoc` will include the source code of your program, with links
  98 to it in the docs. But if you include this:
  99
 100 ```rust,ignore
 101 #![doc(html_no_source)]
 102 ```
 103
 104 it will not.
 105
 106 ### `test(no_crate_inject)`
 107
 108 By default, `rustdoc` will automatically add a line with `extern crate my_crate;` into each doctest.
 109 But if you include this:
 110
 111 ```rust,ignore
 112 #![doc(test(no_crate_inject))]
 113 ```
 114
 115 it will not.
 116
 117 ### `test(attr(...))`
 118
 119 This form of the `doc` attribute allows you to add arbitrary attributes to all your doctests. For
 120 example, if you want your doctests to fail if they produce any warnings, you could add this:
 121
 122 ```rust,ignore
 123 #![doc(test(attr(deny(warnings))))]
 124 ```
 125
 126 ## At the item level
 127
 128 These forms of the `#[doc]` attribute are used on individual items, to control how
 129 they are documented.
 130
 131 ## `#[doc(no_inline)]`/`#[doc(inline)]`
 132
 133 These attributes are used on `use` statements, and control where the documentation shows
 134 up. For example, consider this Rust code:
 135
 136 ```rust,ignore
 137 pub use bar::Bar;
 138
 139 /// bar docs
 140 pub mod bar {
 141     /// the docs for Bar
 142     pub struct Bar;
 143 }
 144 ```
 145
 146 The documentation will generate a "Re-exports" section, and say `pub use bar::Bar;`, where
 147 `Bar` is a link to its page.
 148
 149 If we change the `use` line like this:
 150
 151 ```rust,ignore
 152 #[doc(inline)]
 153 pub use bar::Bar;
 154 ```
 155
 156 Instead, `Bar` will appear in a `Structs` section, just like `Bar` was defined at the
 157 top level, rather than `pub use`'d.
 158
 159 Let's change our original example, by making `bar` private:
 160
 161 ```rust,ignore
 162 pub use bar::Bar;
 163
 164 /// bar docs
 165 mod bar {
 166     /// the docs for Bar
 167     pub struct Bar;
 168 }
 169 ```
 170
 171 Here, because `bar` is not public, `Bar` wouldn't have its own page, so there's nowhere
 172 to link to. `rustdoc` will inline these definitions, and so we end up in the same case
 173 as the `#[doc(inline)]` above; `Bar` is in a `Structs` section, as if it were defined at
 174 the top level. If we add the `no_inline` form of the attribute:
 175
 176 ```rust,ignore
 177 #[doc(no_inline)]
 178 pub use bar::Bar;
 179
 180 /// bar docs
 181 mod bar {
 182     /// the docs for Bar
 183     pub struct Bar;
 184 }
 185 ```
 186
 187 Now we'll have a `Re-exports` line, and `Bar` will not link to anywhere.
 188
 189 One special case: In Rust 2018 and later, if you `pub use` one of your dependencies, `rustdoc` will
 190 not eagerly inline it as a module unless you add `#[doc(inline)}`.
 191
 192 ## `#[doc(hidden)]`
 193
 194 Any item annotated with `#[doc(hidden)]` will not appear in the documentation, unless
 195 the `strip-hidden` pass is removed.
 196
 197 ## `#[doc(primitive)]`
 198
 199 Since primitive types are defined in the compiler, there's no place to attach documentation
 200 attributes. This attribute is used by the standard library to provide a way to generate
 201 documentation for primitive types.