]> git.proxmox.com Git - rustc.git/blob - src/doc/rustdoc/src/unstable-features.md
New upstream version 1.52.0~beta.3+dfsg1
[rustc.git] / src / doc / rustdoc / src / unstable-features.md
1 # Unstable features
2
3 Rustdoc is under active development, and like the Rust compiler, some features are only available
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
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
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
46 ### `#[doc(cfg)]`: Recording what platforms or features are required for code to be present
47
48 You can use `#[doc(cfg(...))]` to tell Rustdoc exactly which platform items appear on.
49 This has two effects:
50
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.
54
55 `#[doc(cfg)]` is intended to be used alongside [`#[cfg(doc)]`][cfg-doc].
56 For example, `#[cfg(any(windows, doc))]` will preserve the item either on Windows or during the
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:
59
60 ```rust
61 #![feature(doc_cfg)]
62
63 /// Token struct that can only be used on Windows.
64 #[cfg(any(windows, doc))]
65 #[doc(cfg(windows))]
66 pub struct WindowsToken;
67
68 /// Token struct that can only be used on Unix.
69 #[cfg(any(unix, doc))]
70 #[doc(cfg(unix))]
71 pub struct UnixToken;
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;
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
87 [cfg-doc]: ./advanced-features.md
88 [unstable-doc-cfg]: ../unstable-book/language-features/doc-cfg.html
89 [issue-doc-cfg]: https://github.com/rust-lang/rust/issues/43781
90
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
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.
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.
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
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
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
248 ### `--extern-html-root-url`: control how rustdoc links to non-local crates
249
250 Using this flag looks like this:
251
252 ```bash
253 $ rustdoc src/lib.rs -Z unstable-options --extern-html-root-url some-crate=https://example.com/some-crate/1.0.1
254 ```
255
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.
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.
275
276 ### `--index-page`: provide a top-level landing page for docs
277
278 This feature allows you to generate an index-page with a given markdown file. A good example of it
279 is the [rust documentation index](https://doc.rust-lang.org/nightly/index.html).
280
281 With this, you'll have a page which you can custom as much as you want at the top of your crates.
282
283 Using `index-page` option enables `enable-index-page` option as well.
284
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.
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.
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.
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.
342
343 ## `-w`/`--output-format`: output format
344
345 When using
346 [`--show-coverage`](https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html#--show-coverage-get-statistics-about-code-documentation-coverage),
347 passing `--output-format json` will display the coverage information in JSON format. For example,
348 here is the JSON for a file with one documented item and one undocumented item:
349
350 ```rust
351 /// This item has documentation
352 pub fn foo() {}
353
354 pub fn no_documentation() {}
355 ```
356
357 ```json
358 {"no_std.rs":{"total":3,"with_docs":1,"total_examples":3,"with_examples":0}}
359 ```
360
361 Note that the third item is the crate root, which in this case is undocumented.
362
363 When not using `--show-coverage`, `--output-format json` emits documentation in the experimental
364 [JSON format](https://github.com/rust-lang/rfcs/pull/2963). `--output-format html` has no effect,
365 and is also accepted on stable toolchains.
366
367 ### `--enable-per-target-ignores`: allow `ignore-foo` style filters for doctests
368
369 Using this flag looks like this:
370
371 ```bash
372 $ rustdoc src/lib.rs -Z unstable-options --enable-per-target-ignores
373 ```
374
375 This flag allows you to tag doctests with compiletest style `ignore-foo` filters that prevent
376 rustdoc from running that test if the target triple string contains foo. For example:
377
378 ```rust
379 ///```ignore-foo,ignore-bar
380 ///assert!(2 == 2);
381 ///```
382 struct Foo;
383 ```
384
385 This will not be run when the build target is `super-awesome-foo` or `less-bar-awesome`.
386 If the flag is not enabled, then rustdoc will consume the filter, but do nothing with it, and
387 the above example will be run for all targets.
388 If you want to preserve backwards compatibility for older versions of rustdoc, you can use
389
390 ```rust
391 ///```ignore,ignore-foo
392 ///assert!(2 == 2);
393 ///```
394 struct Foo;
395 ```
396
397 In older versions, this will be ignored on all targets, but on newer versions `ignore-gnu` will
398 override `ignore`.
399
400 ### `--runtool`, `--runtool-arg`: program to run tests with; args to pass to it
401
402 Using these options looks like this:
403
404 ```bash
405 $ rustdoc src/lib.rs -Z unstable-options --runtool runner --runtool-arg --do-thing --runtool-arg --do-other-thing
406 ```
407
408 These options can be used to run the doctest under a program, and also pass arguments to
409 that program. For example, if you want to run your doctests under valgrind you might run
410
411 ```bash
412 $ rustdoc src/lib.rs -Z unstable-options --runtool valgrind
413 ```
414
415 Another use case would be to run a test inside an emulator, or through a Virtual Machine.
416
417 ### `--show-coverage`: get statistics about code documentation coverage
418
419 This option allows you to get a nice overview over your code documentation coverage, including both
420 doc-comments and code examples in the doc-comments. Example:
421
422 ```bash
423 $ rustdoc src/lib.rs -Z unstable-options --show-coverage
424 +-------------------------------------+------------+------------+------------+------------+
425 | File | Documented | Percentage | Examples | Percentage |
426 +-------------------------------------+------------+------------+------------+------------+
427 | lib.rs | 4 | 100.0% | 1 | 25.0% |
428 +-------------------------------------+------------+------------+------------+------------+
429 | Total | 4 | 100.0% | 1 | 25.0% |
430 +-------------------------------------+------------+------------+------------+------------+
431 ```
432
433 You can also use this option with the `--output-format` one:
434
435 ```bash
436 $ rustdoc src/lib.rs -Z unstable-options --show-coverage --output-format json
437 {"lib.rs":{"total":4,"with_docs":4,"total_examples":4,"with_examples":1}}
438 ```
439
440 Calculating code examples follows these rules:
441
442 1. These items aren't accounted by default:
443 * struct/union field
444 * enum variant
445 * constant
446 * static
447 * typedef
448 2. If one of the previously listed items has a code example, then it'll be counted.