]>
Commit | Line | Data |
---|---|---|
3b2f2976 XL |
1 | # The `#[doc]` attribute |
2 | ||
3 | The `#[doc]` attribute lets you control various aspects of how `rustdoc` does | |
2c00a5a8 | 4 | its job. |
3b2f2976 XL |
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 | ||
6a06907d | 10 | ```rust,no_run |
3b2f2976 XL |
11 | /// This is a doc comment. |
12 | #[doc = " This is a doc comment."] | |
6a06907d | 13 | # fn f() {} |
3b2f2976 XL |
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 | ||
6a06907d | 22 | ```rust,no_run |
3b2f2976 XL |
23 | #[doc = "This is"] |
24 | #[doc = " a "] | |
25 | #[doc = "doc comment"] | |
6a06907d | 26 | # fn f() {} |
3b2f2976 XL |
27 | ``` |
28 | ||
29 | Which can feel more flexible. Note that this would generate this: | |
30 | ||
6a06907d | 31 | ```rust,no_run |
3b2f2976 | 32 | #[doc = "This is\n a \ndoc comment"] |
6a06907d | 33 | # fn f() {} |
3b2f2976 XL |
34 | ``` |
35 | ||
36 | but given that docs are rendered via Markdown, it will remove these newlines. | |
37 | ||
17df50a5 XL |
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 | ||
3b2f2976 XL |
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 | ||
74b04a01 | 52 | These options control how the docs look at a crate level. |
3b2f2976 XL |
53 | |
54 | ### `html_favicon_url` | |
55 | ||
56 | This form of the `doc` attribute lets you control the favicon of your docs. | |
57 | ||
6a06907d | 58 | ```rust,no_run |
3b2f2976 XL |
59 | #![doc(html_favicon_url = "https://example.com/favicon.ico")] |
60 | ``` | |
61 | ||
62 | This will put `<link rel="shortcut 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 | ||
6a06907d | 72 | ```rust,no_run |
3b2f2976 XL |
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 | ||
6a06907d | 86 | ```rust,no_run |
3b2f2976 XL |
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 | ||
6a06907d | 101 | ```rust,no_run |
3b2f2976 XL |
102 | #![doc(issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/")] |
103 | ``` | |
104 | ||
48663c56 XL |
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 | ||
6a06907d | 116 | ```rust,no_run |
48663c56 XL |
117 | #![doc(html_root_url = "https://docs.rs/serde/1.0")] |
118 | ``` | |
119 | ||
3b2f2976 XL |
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 | ||
6a06907d | 125 | ```rust,no_run |
3b2f2976 XL |
126 | #![doc(html_no_source)] |
127 | ``` | |
128 | ||
129 | it will not. | |
130 | ||
abe05a73 XL |
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 | ||
6a06907d | 136 | ```rust,no_run |
abe05a73 XL |
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 | ||
6a06907d | 147 | ```rust,no_run |
abe05a73 XL |
148 | #![doc(test(attr(deny(warnings))))] |
149 | ``` | |
150 | ||
3b2f2976 XL |
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 | ## `#[doc(no_inline)]`/`#[doc(inline)]` | |
157 | ||
158 | These attributes are used on `use` statements, and control where the documentation shows | |
159 | up. For example, consider this Rust code: | |
160 | ||
6a06907d | 161 | ```rust,no_run |
3b2f2976 XL |
162 | pub use bar::Bar; |
163 | ||
164 | /// bar docs | |
165 | pub mod bar { | |
166 | /// the docs for Bar | |
167 | pub struct Bar; | |
168 | } | |
6a06907d | 169 | # fn main() {} |
3b2f2976 XL |
170 | ``` |
171 | ||
2c00a5a8 | 172 | The documentation will generate a "Re-exports" section, and say `pub use bar::Bar;`, where |
3b2f2976 XL |
173 | `Bar` is a link to its page. |
174 | ||
175 | If we change the `use` line like this: | |
176 | ||
6a06907d | 177 | ```rust,no_run |
3b2f2976 XL |
178 | #[doc(inline)] |
179 | pub use bar::Bar; | |
6a06907d XL |
180 | # pub mod bar { pub struct Bar; } |
181 | # fn main() {} | |
3b2f2976 XL |
182 | ``` |
183 | ||
184 | Instead, `Bar` will appear in a `Structs` section, just like `Bar` was defined at the | |
185 | top level, rather than `pub use`'d. | |
186 | ||
187 | Let's change our original example, by making `bar` private: | |
188 | ||
6a06907d | 189 | ```rust,no_run |
3b2f2976 XL |
190 | pub use bar::Bar; |
191 | ||
192 | /// bar docs | |
193 | mod bar { | |
194 | /// the docs for Bar | |
195 | pub struct Bar; | |
196 | } | |
6a06907d | 197 | # fn main() {} |
3b2f2976 XL |
198 | ``` |
199 | ||
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: | |
204 | ||
6a06907d | 205 | ```rust,no_run |
3b2f2976 XL |
206 | #[doc(no_inline)] |
207 | pub use bar::Bar; | |
208 | ||
209 | /// bar docs | |
210 | mod bar { | |
211 | /// the docs for Bar | |
212 | pub struct Bar; | |
213 | } | |
6a06907d | 214 | # fn main() {} |
3b2f2976 XL |
215 | ``` |
216 | ||
2c00a5a8 | 217 | Now we'll have a `Re-exports` line, and `Bar` will not link to anywhere. |
3b2f2976 | 218 | |
13cf67c4 | 219 | One special case: In Rust 2018 and later, if you `pub use` one of your dependencies, `rustdoc` will |
dc9dc135 | 220 | not eagerly inline it as a module unless you add `#[doc(inline)]`. |
13cf67c4 | 221 | |
3b2f2976 XL |
222 | ## `#[doc(hidden)]` |
223 | ||
224 | Any item annotated with `#[doc(hidden)]` will not appear in the documentation, unless | |
225 | the `strip-hidden` pass is removed. |