]>
Commit | Line | Data |
---|---|---|
0531ce1d XL |
1 | # Unstable features |
2 | ||
b7449926 | 3 | Rustdoc is under active development, and like the Rust compiler, some features are only available |
9fa01778 XL |
4 | on nightly releases. Some of these features are new and need some more testing before they're able to be |
5 | released to the world at large, and some of them are tied to features in the Rust compiler that are unstable. Several features here require a matching `#![feature(...)]` attribute to | |
0531ce1d XL |
6 | enable, and thus are more fully documented in the [Unstable Book]. Those sections will link over |
7 | there as necessary. | |
8 | ||
9 | [Unstable Book]: ../unstable-book/index.html | |
10 | ||
11 | ## Nightly-gated functionality | |
12 | ||
13 | These features just require a nightly build to operate. Unlike the other features on this page, | |
14 | these don't need to be "turned on" with a command-line flag or a `#![feature(...)]` attribute in | |
15 | your crate. This can give them some subtle fallback modes when used on a stable release, so be | |
16 | careful! | |
17 | ||
18 | ### Error numbers for `compile-fail` doctests | |
19 | ||
20 | As detailed in [the chapter on documentation tests][doctest-attributes], you can add a | |
21 | `compile_fail` attribute to a doctest to state that the test should fail to compile. However, on | |
22 | nightly, you can optionally add an error number to state that a doctest should emit a specific error | |
23 | number: | |
24 | ||
25 | [doctest-attributes]: documentation-tests.html#attributes | |
26 | ||
27 | ``````markdown | |
28 | ```compile_fail,E0044 | |
29 | extern { fn some_func<T>(x: T); } | |
30 | ``` | |
31 | `````` | |
32 | ||
33 | This is used by the error index to ensure that the samples that correspond to a given error number | |
34 | properly emit that error code. However, these error codes aren't guaranteed to be the only thing | |
35 | that a piece of code emits from version to version, so this is unlikely to be stabilized in the | |
36 | future. | |
37 | ||
38 | Attempting to use these error numbers on stable will result in the code sample being interpreted as | |
39 | plain text. | |
40 | ||
0531ce1d XL |
41 | ## Extensions to the `#[doc]` attribute |
42 | ||
43 | These features operate by extending the `#[doc]` attribute, and thus can be caught by the compiler | |
44 | and enabled with a `#![feature(...)]` attribute in your crate. | |
45 | ||
29967ef6 | 46 | ### `#[doc(cfg)]`: Recording what platforms or features are required for code to be present |
0531ce1d | 47 | |
29967ef6 XL |
48 | You can use `#[doc(cfg(...))]` to tell Rustdoc exactly which platform items appear on. |
49 | This has two effects: | |
0531ce1d | 50 | |
29967ef6 XL |
51 | 1. doctests will only run on the appropriate platforms, and |
52 | 2. When Rustdoc renders documentation for that item, it will be accompanied by a banner explaining | |
53 | that the item is only available on certain platforms. | |
0531ce1d | 54 | |
29967ef6 | 55 | `#[doc(cfg)]` is intended to be used alongside [`#[cfg(doc)]`][cfg-doc]. |
60c5eb7d | 56 | For example, `#[cfg(any(windows, doc))]` will preserve the item either on Windows or during the |
b7449926 XL |
57 | documentation process. Then, adding a new attribute `#[doc(cfg(windows))]` will tell Rustdoc that |
58 | the item is supposed to be used on Windows. For example: | |
0531ce1d XL |
59 | |
60 | ```rust | |
61 | #![feature(doc_cfg)] | |
62 | ||
63 | /// Token struct that can only be used on Windows. | |
60c5eb7d | 64 | #[cfg(any(windows, doc))] |
0531ce1d XL |
65 | #[doc(cfg(windows))] |
66 | pub struct WindowsToken; | |
67 | ||
68 | /// Token struct that can only be used on Unix. | |
60c5eb7d | 69 | #[cfg(any(unix, doc))] |
0531ce1d XL |
70 | #[doc(cfg(unix))] |
71 | pub struct UnixToken; | |
29967ef6 XL |
72 | |
73 | /// Token struct that is only available with the `serde` feature | |
74 | #[cfg(feature = "serde")] | |
75 | #[doc(cfg(feature = "serde"))] | |
76 | #[derive(serde::Deserialize)] | |
77 | pub struct SerdeToken; | |
0531ce1d XL |
78 | ``` |
79 | ||
80 | In this sample, the tokens will only appear on their respective platforms, but they will both appear | |
81 | in documentation. | |
82 | ||
83 | `#[doc(cfg(...))]` was introduced to be used by the standard library and currently requires the | |
84 | `#![feature(doc_cfg)]` feature gate. For more information, see [its chapter in the Unstable | |
85 | Book][unstable-doc-cfg] and [its tracking issue][issue-doc-cfg]. | |
86 | ||
29967ef6 | 87 | [cfg-doc]: ./advanced-features.md |
0531ce1d XL |
88 | [unstable-doc-cfg]: ../unstable-book/language-features/doc-cfg.html |
89 | [issue-doc-cfg]: https://github.com/rust-lang/rust/issues/43781 | |
90 | ||
3dfed10e XL |
91 | ### Adding your trait to the "Important Traits" dialog |
92 | ||
93 | Rustdoc keeps a list of a few traits that are believed to be "fundamental" to a given type when | |
94 | implemented on it. These traits are intended to be the primary interface for their types, and are | |
95 | often the only thing available to be documented on their types. For this reason, Rustdoc will track | |
96 | when a given type implements one of these traits and call special attention to it when a function | |
97 | returns one of these types. This is the "Important Traits" dialog, visible as a circle-i button next | |
98 | to the function, which, when clicked, shows the dialog. | |
99 | ||
100 | In the standard library, the traits that qualify for inclusion are `Iterator`, `io::Read`, and | |
101 | `io::Write`. However, rather than being implemented as a hard-coded list, these traits have a | |
102 | special marker attribute on them: `#[doc(spotlight)]`. This means that you could apply this | |
103 | attribute to your own trait to include it in the "Important Traits" dialog in documentation. | |
104 | ||
105 | The `#[doc(spotlight)]` attribute currently requires the `#![feature(doc_spotlight)]` feature gate. | |
106 | For more information, see [its chapter in the Unstable Book][unstable-spotlight] and [its tracking | |
107 | issue][issue-spotlight]. | |
108 | ||
109 | [unstable-spotlight]: ../unstable-book/language-features/doc-spotlight.html | |
110 | [issue-spotlight]: https://github.com/rust-lang/rust/issues/45040 | |
111 | ||
0531ce1d XL |
112 | ### Exclude certain dependencies from documentation |
113 | ||
114 | The standard library uses several dependencies which, in turn, use several types and traits from the | |
115 | standard library. In addition, there are several compiler-internal crates that are not considered to | |
116 | be part of the official standard library, and thus would be a distraction to include in | |
117 | documentation. It's not enough to exclude their crate documentation, since information about trait | |
118 | implementations appears on the pages for both the type and the trait, which can be in different | |
119 | crates! | |
120 | ||
121 | To prevent internal types from being included in documentation, the standard library adds an | |
122 | attribute to their `extern crate` declarations: `#[doc(masked)]`. This causes Rustdoc to "mask out" | |
123 | types from these crates when building lists of trait implementations. | |
124 | ||
125 | The `#[doc(masked)]` attribute is intended to be used internally, and requires the | |
126 | `#![feature(doc_masked)]` feature gate. For more information, see [its chapter in the Unstable | |
127 | Book][unstable-masked] and [its tracking issue][issue-masked]. | |
128 | ||
129 | [unstable-masked]: ../unstable-book/language-features/doc-masked.html | |
130 | [issue-masked]: https://github.com/rust-lang/rust/issues/44027 | |
131 | ||
132 | ### Include external files as API documentation | |
133 | ||
134 | As designed in [RFC 1990], Rustdoc can read an external file to use as a type's documentation. This | |
135 | is useful if certain documentation is so long that it would break the flow of reading the source. | |
416331ca XL |
136 | Instead of writing it all inline, writing `#[doc(include = "sometype.md")]` will ask Rustdoc to |
137 | instead read that file and use it as if it were written inline. | |
0531ce1d XL |
138 | |
139 | [RFC 1990]: https://github.com/rust-lang/rfcs/pull/1990 | |
140 | ||
141 | `#[doc(include = "...")]` currently requires the `#![feature(external_doc)]` feature gate. For more | |
142 | information, see [its chapter in the Unstable Book][unstable-include] and [its tracking | |
143 | issue][issue-include]. | |
144 | ||
145 | [unstable-include]: ../unstable-book/language-features/external-doc.html | |
146 | [issue-include]: https://github.com/rust-lang/rust/issues/44732 | |
147 | ||
148 | ## Unstable command-line arguments | |
149 | ||
150 | These features are enabled by passing a command-line flag to Rustdoc, but the flags in question are | |
151 | themselves marked as unstable. To use any of these options, pass `-Z unstable-options` as well as | |
152 | the flag in question to Rustdoc on the command-line. To do this from Cargo, you can either use the | |
153 | `RUSTDOCFLAGS` environment variable or the `cargo rustdoc` command. | |
154 | ||
155 | ### `--markdown-before-content`: include rendered Markdown before the content | |
156 | ||
157 | Using this flag looks like this: | |
158 | ||
159 | ```bash | |
160 | $ rustdoc src/lib.rs -Z unstable-options --markdown-before-content extra.md | |
161 | $ rustdoc README.md -Z unstable-options --markdown-before-content extra.md | |
162 | ``` | |
163 | ||
164 | Just like `--html-before-content`, this allows you to insert extra content inside the `<body>` tag | |
165 | but before the other content `rustdoc` would normally produce in the rendered documentation. | |
166 | However, instead of directly inserting the file verbatim, `rustdoc` will pass the files through a | |
167 | Markdown renderer before inserting the result into the file. | |
168 | ||
169 | ### `--markdown-after-content`: include rendered Markdown after the content | |
170 | ||
171 | Using this flag looks like this: | |
172 | ||
173 | ```bash | |
174 | $ rustdoc src/lib.rs -Z unstable-options --markdown-after-content extra.md | |
175 | $ rustdoc README.md -Z unstable-options --markdown-after-content extra.md | |
176 | ``` | |
177 | ||
178 | Just like `--html-after-content`, this allows you to insert extra content before the `</body>` tag | |
179 | but after the other content `rustdoc` would normally produce in the rendered documentation. | |
180 | However, instead of directly inserting the file verbatim, `rustdoc` will pass the files through a | |
181 | Markdown renderer before inserting the result into the file. | |
182 | ||
183 | ### `--playground-url`: control the location of the playground | |
184 | ||
185 | Using this flag looks like this: | |
186 | ||
187 | ```bash | |
188 | $ rustdoc src/lib.rs -Z unstable-options --playground-url https://play.rust-lang.org/ | |
189 | ``` | |
190 | ||
191 | When rendering a crate's docs, this flag gives the base URL of the Rust Playground, to use for | |
192 | generating `Run` buttons. Unlike `--markdown-playground-url`, this argument works for standalone | |
193 | Markdown files *and* Rust crates. This works the same way as adding `#![doc(html_playground_url = | |
194 | "url")]` to your crate root, as mentioned in [the chapter about the `#[doc]` | |
195 | attribute][doc-playground]. Please be aware that the official Rust Playground at | |
196 | https://play.rust-lang.org does not have every crate available, so if your examples require your | |
197 | crate, make sure the playground you provide has your crate available. | |
198 | ||
199 | [doc-playground]: the-doc-attribute.html#html_playground_url | |
200 | ||
201 | If both `--playground-url` and `--markdown-playground-url` are present when rendering a standalone | |
202 | Markdown file, the URL given to `--markdown-playground-url` will take precedence. If both | |
203 | `--playground-url` and `#![doc(html_playground_url = "url")]` are present when rendering crate docs, | |
204 | the attribute will take precedence. | |
205 | ||
0531ce1d XL |
206 | ### `--sort-modules-by-appearance`: control how items on module pages are sorted |
207 | ||
208 | Using this flag looks like this: | |
209 | ||
210 | ```bash | |
211 | $ rustdoc src/lib.rs -Z unstable-options --sort-modules-by-appearance | |
212 | ``` | |
213 | ||
214 | Ordinarily, when `rustdoc` prints items in module pages, it will sort them alphabetically (taking | |
215 | some consideration for their stability, and names that end in a number). Giving this flag to | |
216 | `rustdoc` will disable this sorting and instead make it print the items in the order they appear in | |
217 | the source. | |
218 | ||
0531ce1d XL |
219 | ### `--resource-suffix`: modifying the name of CSS/JavaScript in crate docs |
220 | ||
221 | Using this flag looks like this: | |
222 | ||
223 | ```bash | |
224 | $ rustdoc src/lib.rs -Z unstable-options --resource-suffix suf | |
225 | ``` | |
226 | ||
227 | When rendering docs, `rustdoc` creates several CSS and JavaScript files as part of the output. Since | |
228 | all these files are linked from every page, changing where they are can be cumbersome if you need to | |
229 | specially cache them. This flag will rename all these files in the output to include the suffix in | |
230 | the filename. For example, `light.css` would become `light-suf.css` with the above command. | |
231 | ||
232 | ### `--display-warnings`: display warnings when documenting or running documentation tests | |
233 | ||
234 | Using this flag looks like this: | |
235 | ||
236 | ```bash | |
237 | $ rustdoc src/lib.rs -Z unstable-options --display-warnings | |
238 | $ rustdoc --test src/lib.rs -Z unstable-options --display-warnings | |
239 | ``` | |
240 | ||
241 | The intent behind this flag is to allow the user to see warnings that occur within their library or | |
242 | their documentation tests, which are usually suppressed. However, [due to a | |
243 | bug][issue-display-warnings], this flag doesn't 100% work as intended. See the linked issue for | |
244 | details. | |
245 | ||
246 | [issue-display-warnings]: https://github.com/rust-lang/rust/issues/41574 | |
247 | ||
b7449926 | 248 | ### `--extern-html-root-url`: control how rustdoc links to non-local crates |
0531ce1d XL |
249 | |
250 | Using this flag looks like this: | |
251 | ||
252 | ```bash | |
b7449926 | 253 | $ rustdoc src/lib.rs -Z unstable-options --extern-html-root-url some-crate=https://example.com/some-crate/1.0.1 |
0531ce1d XL |
254 | ``` |
255 | ||
b7449926 XL |
256 | Ordinarily, when rustdoc wants to link to a type from a different crate, it looks in two places: |
257 | docs that already exist in the output directory, or the `#![doc(doc_html_root)]` set in the other | |
258 | crate. However, if you want to link to docs that exist in neither of those places, you can use these | |
259 | flags to control that behavior. When the `--extern-html-root-url` flag is given with a name matching | |
260 | one of your dependencies, rustdoc use that URL for those docs. Keep in mind that if those docs exist | |
261 | in the output directory, those local docs will still override this flag. | |
0531ce1d XL |
262 | |
263 | ### `-Z force-unstable-if-unmarked` | |
264 | ||
265 | Using this flag looks like this: | |
266 | ||
267 | ```bash | |
268 | $ rustdoc src/lib.rs -Z force-unstable-if-unmarked | |
269 | ``` | |
270 | ||
271 | This is an internal flag intended for the standard library and compiler that applies an | |
272 | `#[unstable]` attribute to any dependent crate that doesn't have another stability attribute. This | |
273 | allows `rustdoc` to be able to generate documentation for the compiler crates and the standard | |
274 | library, as an equivalent command-line argument is provided to `rustc` when building those crates. | |
83c7162d | 275 | |
a1dfa0c6 | 276 | ### `--index-page`: provide a top-level landing page for docs |
83c7162d | 277 | |
a1dfa0c6 | 278 | This feature allows you to generate an index-page with a given markdown file. A good example of it |
f035d41b | 279 | is the [rust documentation index](https://doc.rust-lang.org/nightly/index.html). |
83c7162d | 280 | |
a1dfa0c6 | 281 | With this, you'll have a page which you can custom as much as you want at the top of your crates. |
83c7162d | 282 | |
a1dfa0c6 | 283 | Using `index-page` option enables `enable-index-page` option as well. |
83c7162d | 284 | |
a1dfa0c6 XL |
285 | ### `--enable-index-page`: generate a default index page for docs |
286 | ||
287 | This feature allows the generation of a default index-page which lists the generated crates. | |
0731742a XL |
288 | |
289 | ### `--static-root-path`: control how static files are loaded in HTML output | |
290 | ||
291 | Using this flag looks like this: | |
292 | ||
293 | ```bash | |
294 | $ rustdoc src/lib.rs -Z unstable-options --static-root-path '/cache/' | |
295 | ``` | |
296 | ||
297 | This flag controls how rustdoc links to its static files on HTML pages. If you're hosting a lot of | |
298 | crates' docs generated by the same version of rustdoc, you can use this flag to cache rustdoc's CSS, | |
299 | JavaScript, and font files in a single location, rather than duplicating it once per "doc root" | |
300 | (grouping of crate docs generated into the same output directory, like with `cargo doc`). Per-crate | |
301 | files like the search index will still load from the documentation root, but anything that gets | |
302 | renamed with `--resource-suffix` will load from the given path. | |
9fa01778 XL |
303 | |
304 | ### `--persist-doctests`: persist doctest executables after running | |
305 | ||
306 | Using this flag looks like this: | |
307 | ||
308 | ```bash | |
309 | $ rustdoc src/lib.rs --test -Z unstable-options --persist-doctests target/rustdoctest | |
310 | ``` | |
311 | ||
312 | This flag allows you to keep doctest executables around after they're compiled or run. | |
313 | Usually, rustdoc will immediately discard a compiled doctest after it's been tested, but | |
314 | with this option, you can keep those binaries around for farther testing. | |
532ac7d7 XL |
315 | |
316 | ### `--show-coverage`: calculate the percentage of items with documentation | |
317 | ||
318 | Using this flag looks like this: | |
319 | ||
320 | ```bash | |
321 | $ rustdoc src/lib.rs -Z unstable-options --show-coverage | |
322 | ``` | |
323 | ||
324 | If you want to determine how many items in your crate are documented, pass this flag to rustdoc. | |
325 | When it receives this flag, it will count the public items in your crate that have documentation, | |
326 | and print out the counts and a percentage instead of generating docs. | |
327 | ||
328 | Some methodology notes about what rustdoc counts in this metric: | |
329 | ||
330 | * Rustdoc will only count items from your crate (i.e. items re-exported from other crates don't | |
331 | count). | |
332 | * Docs written directly onto inherent impl blocks are not counted, even though their doc comments | |
333 | are displayed, because the common pattern in Rust code is to write all inherent methods into the | |
334 | same impl block. | |
335 | * Items in a trait implementation are not counted, as those impls will inherit any docs from the | |
336 | trait itself. | |
337 | * By default, only public items are counted. To count private items as well, pass | |
338 | `--document-private-items` at the same time. | |
339 | ||
340 | Public items that are not documented can be seen with the built-in `missing_docs` lint. Private | |
341 | items that are not documented can be seen with Clippy's `missing_docs_in_private_items` lint. | |
e1599b0c XL |
342 | |
343 | ### `--enable-per-target-ignores`: allow `ignore-foo` style filters for doctests | |
344 | ||
345 | Using this flag looks like this: | |
346 | ||
347 | ```bash | |
348 | $ rustdoc src/lib.rs -Z unstable-options --enable-per-target-ignores | |
349 | ``` | |
350 | ||
29967ef6 | 351 | This flag allows you to tag doctests with compiletest style `ignore-foo` filters that prevent |
e1599b0c XL |
352 | rustdoc from running that test if the target triple string contains foo. For example: |
353 | ||
354 | ```rust | |
355 | ///```ignore-foo,ignore-bar | |
356 | ///assert!(2 == 2); | |
357 | ///``` | |
358 | struct Foo; | |
359 | ``` | |
360 | ||
361 | This will not be run when the build target is `super-awesome-foo` or `less-bar-awesome`. | |
362 | If the flag is not enabled, then rustdoc will consume the filter, but do nothing with it, and | |
363 | the above example will be run for all targets. | |
364 | If you want to preserve backwards compatibility for older versions of rustdoc, you can use | |
365 | ||
366 | ```rust | |
367 | ///```ignore,ignore-foo | |
368 | ///assert!(2 == 2); | |
369 | ///``` | |
370 | struct Foo; | |
371 | ``` | |
372 | ||
373 | In older versions, this will be ignored on all targets, but on newer versions `ignore-gnu` will | |
374 | override `ignore`. | |
375 | ||
376 | ### `--runtool`, `--runtool-arg`: program to run tests with; args to pass to it | |
377 | ||
74b04a01 | 378 | Using these options looks like this: |
e1599b0c XL |
379 | |
380 | ```bash | |
381 | $ rustdoc src/lib.rs -Z unstable-options --runtool runner --runtool-arg --do-thing --runtool-arg --do-other-thing | |
382 | ``` | |
383 | ||
384 | These options can be used to run the doctest under a program, and also pass arguments to | |
385 | that program. For example, if you want to run your doctests under valgrind you might run | |
386 | ||
387 | ```bash | |
388 | $ rustdoc src/lib.rs -Z unstable-options --runtool valgrind | |
389 | ``` | |
390 | ||
391 | Another use case would be to run a test inside an emulator, or through a Virtual Machine. | |
3dfed10e XL |
392 | |
393 | ### `--show-coverage`: get statistics about code documentation coverage | |
394 | ||
395 | This option allows you to get a nice overview over your code documentation coverage, including both | |
396 | doc-comments and code examples in the doc-comments. Example: | |
397 | ||
398 | ```bash | |
399 | $ rustdoc src/lib.rs -Z unstable-options --show-coverage | |
400 | +-------------------------------------+------------+------------+------------+------------+ | |
401 | | File | Documented | Percentage | Examples | Percentage | | |
402 | +-------------------------------------+------------+------------+------------+------------+ | |
403 | | lib.rs | 4 | 100.0% | 1 | 25.0% | | |
404 | +-------------------------------------+------------+------------+------------+------------+ | |
405 | | Total | 4 | 100.0% | 1 | 25.0% | | |
406 | +-------------------------------------+------------+------------+------------+------------+ | |
407 | ``` | |
408 | ||
409 | You can also use this option with the `--output-format` one: | |
410 | ||
411 | ```bash | |
412 | $ rustdoc src/lib.rs -Z unstable-options --show-coverage --output-format json | |
413 | {"lib.rs":{"total":4,"with_docs":4,"total_examples":4,"with_examples":1}} | |
414 | ``` | |
415 | ||
416 | Calculating code examples follows these rules: | |
417 | ||
418 | 1. These items aren't accounted by default: | |
419 | * struct/union field | |
420 | * enum variant | |
421 | * constant | |
422 | * static | |
423 | * typedef | |
424 | 2. If one of the previously listed items has a code example, then it'll be counted. |