]>
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 | ||
41 | ### Linking to items by type | |
42 | ||
43 | As designed in [RFC 1946], Rustdoc can parse paths to items when you use them as links. To resolve | |
44 | these type names, it uses the items currently in-scope, either by declaration or by `use` statement. | |
45 | For modules, the "active scope" depends on whether the documentation is written outside the module | |
46 | (as `///` comments on the `mod` statement) or inside the module (at `//!` comments inside the file | |
47 | or block). For all other items, it uses the enclosing module's scope. | |
48 | ||
49 | [RFC 1946]: https://github.com/rust-lang/rfcs/pull/1946 | |
50 | ||
51 | For example, in the following code: | |
52 | ||
53 | ```rust | |
54 | /// Does the thing. | |
55 | pub fn do_the_thing(_: SomeType) { | |
532ac7d7 | 56 | println!("Let's do the thing!"); |
0531ce1d XL |
57 | } |
58 | ||
59 | /// Token you use to [`do_the_thing`]. | |
60 | pub struct SomeType; | |
61 | ``` | |
62 | ||
63 | The link to ``[`do_the_thing`]`` in `SomeType`'s docs will properly link to the page for `fn | |
64 | do_the_thing`. Note that here, rustdoc will insert the link target for you, but manually writing the | |
65 | target out also works: | |
66 | ||
67 | ```rust | |
68 | pub mod some_module { | |
532ac7d7 XL |
69 | /// Token you use to do the thing. |
70 | pub struct SomeStruct; | |
0531ce1d XL |
71 | } |
72 | ||
73 | /// Does the thing. Requires one [`SomeStruct`] for the thing to work. | |
74 | /// | |
75 | /// [`SomeStruct`]: some_module::SomeStruct | |
76 | pub fn do_the_thing(_: some_module::SomeStruct) { | |
532ac7d7 | 77 | println!("Let's do the thing!"); |
0531ce1d XL |
78 | } |
79 | ``` | |
80 | ||
81 | For more details, check out [the RFC][RFC 1946], and see [the tracking issue][43466] for more | |
82 | information about what parts of the feature are available. | |
83 | ||
84 | [43466]: https://github.com/rust-lang/rust/issues/43466 | |
85 | ||
86 | ## Extensions to the `#[doc]` attribute | |
87 | ||
88 | These features operate by extending the `#[doc]` attribute, and thus can be caught by the compiler | |
89 | and enabled with a `#![feature(...)]` attribute in your crate. | |
90 | ||
91 | ### Documenting platform-/feature-specific information | |
92 | ||
93 | Because of the way Rustdoc documents a crate, the documentation it creates is specific to the target | |
94 | rustc compiles for. Anything that's specific to any other target is dropped via `#[cfg]` attribute | |
95 | processing early in the compilation process. However, Rustdoc has a trick up its sleeve to handle | |
96 | platform-specific code if it *does* receive it. | |
97 | ||
98 | Because Rustdoc doesn't need to fully compile a crate to binary, it replaces function bodies with | |
99 | `loop {}` to prevent having to process more than necessary. This means that any code within a | |
100 | function that requires platform-specific pieces is ignored. Combined with a special attribute, | |
101 | `#[doc(cfg(...))]`, you can tell Rustdoc exactly which platform something is supposed to run on, | |
102 | ensuring that doctests are only run on the appropriate platforms. | |
103 | ||
104 | The `#[doc(cfg(...))]` attribute has another effect: When Rustdoc renders documentation for that | |
105 | item, it will be accompanied by a banner explaining that the item is only available on certain | |
106 | platforms. | |
107 | ||
b7449926 | 108 | For Rustdoc to document an item, it needs to see it, regardless of what platform it's currently |
60c5eb7d | 109 | running on. To aid this, Rustdoc sets the flag `#[cfg(doc)]` when running on your crate. |
b7449926 XL |
110 | Combining this with the target platform of a given item allows it to appear when building your crate |
111 | normally on that platform, as well as when building documentation anywhere. | |
0531ce1d | 112 | |
60c5eb7d | 113 | For example, `#[cfg(any(windows, doc))]` will preserve the item either on Windows or during the |
b7449926 XL |
114 | documentation process. Then, adding a new attribute `#[doc(cfg(windows))]` will tell Rustdoc that |
115 | the item is supposed to be used on Windows. For example: | |
0531ce1d XL |
116 | |
117 | ```rust | |
118 | #![feature(doc_cfg)] | |
119 | ||
120 | /// Token struct that can only be used on Windows. | |
60c5eb7d | 121 | #[cfg(any(windows, doc))] |
0531ce1d XL |
122 | #[doc(cfg(windows))] |
123 | pub struct WindowsToken; | |
124 | ||
125 | /// Token struct that can only be used on Unix. | |
60c5eb7d | 126 | #[cfg(any(unix, doc))] |
0531ce1d XL |
127 | #[doc(cfg(unix))] |
128 | pub struct UnixToken; | |
129 | ``` | |
130 | ||
131 | In this sample, the tokens will only appear on their respective platforms, but they will both appear | |
132 | in documentation. | |
133 | ||
134 | `#[doc(cfg(...))]` was introduced to be used by the standard library and currently requires the | |
135 | `#![feature(doc_cfg)]` feature gate. For more information, see [its chapter in the Unstable | |
136 | Book][unstable-doc-cfg] and [its tracking issue][issue-doc-cfg]. | |
137 | ||
138 | [unstable-doc-cfg]: ../unstable-book/language-features/doc-cfg.html | |
139 | [issue-doc-cfg]: https://github.com/rust-lang/rust/issues/43781 | |
140 | ||
141 | ### Adding your trait to the "Important Traits" dialog | |
142 | ||
143 | Rustdoc keeps a list of a few traits that are believed to be "fundamental" to a given type when | |
144 | implemented on it. These traits are intended to be the primary interface for their types, and are | |
145 | often the only thing available to be documented on their types. For this reason, Rustdoc will track | |
146 | when a given type implements one of these traits and call special attention to it when a function | |
147 | returns one of these types. This is the "Important Traits" dialog, visible as a circle-i button next | |
148 | to the function, which, when clicked, shows the dialog. | |
149 | ||
150 | In the standard library, the traits that qualify for inclusion are `Iterator`, `io::Read`, and | |
151 | `io::Write`. However, rather than being implemented as a hard-coded list, these traits have a | |
152 | special marker attribute on them: `#[doc(spotlight)]`. This means that you could apply this | |
153 | attribute to your own trait to include it in the "Important Traits" dialog in documentation. | |
154 | ||
155 | The `#[doc(spotlight)]` attribute currently requires the `#![feature(doc_spotlight)]` feature gate. | |
156 | For more information, see [its chapter in the Unstable Book][unstable-spotlight] and [its tracking | |
157 | issue][issue-spotlight]. | |
158 | ||
159 | [unstable-spotlight]: ../unstable-book/language-features/doc-spotlight.html | |
160 | [issue-spotlight]: https://github.com/rust-lang/rust/issues/45040 | |
161 | ||
162 | ### Exclude certain dependencies from documentation | |
163 | ||
164 | The standard library uses several dependencies which, in turn, use several types and traits from the | |
165 | standard library. In addition, there are several compiler-internal crates that are not considered to | |
166 | be part of the official standard library, and thus would be a distraction to include in | |
167 | documentation. It's not enough to exclude their crate documentation, since information about trait | |
168 | implementations appears on the pages for both the type and the trait, which can be in different | |
169 | crates! | |
170 | ||
171 | To prevent internal types from being included in documentation, the standard library adds an | |
172 | attribute to their `extern crate` declarations: `#[doc(masked)]`. This causes Rustdoc to "mask out" | |
173 | types from these crates when building lists of trait implementations. | |
174 | ||
175 | The `#[doc(masked)]` attribute is intended to be used internally, and requires the | |
176 | `#![feature(doc_masked)]` feature gate. For more information, see [its chapter in the Unstable | |
177 | Book][unstable-masked] and [its tracking issue][issue-masked]. | |
178 | ||
179 | [unstable-masked]: ../unstable-book/language-features/doc-masked.html | |
180 | [issue-masked]: https://github.com/rust-lang/rust/issues/44027 | |
181 | ||
182 | ### Include external files as API documentation | |
183 | ||
184 | As designed in [RFC 1990], Rustdoc can read an external file to use as a type's documentation. This | |
185 | is useful if certain documentation is so long that it would break the flow of reading the source. | |
416331ca XL |
186 | Instead of writing it all inline, writing `#[doc(include = "sometype.md")]` will ask Rustdoc to |
187 | instead read that file and use it as if it were written inline. | |
0531ce1d XL |
188 | |
189 | [RFC 1990]: https://github.com/rust-lang/rfcs/pull/1990 | |
190 | ||
191 | `#[doc(include = "...")]` currently requires the `#![feature(external_doc)]` feature gate. For more | |
192 | information, see [its chapter in the Unstable Book][unstable-include] and [its tracking | |
193 | issue][issue-include]. | |
194 | ||
195 | [unstable-include]: ../unstable-book/language-features/external-doc.html | |
196 | [issue-include]: https://github.com/rust-lang/rust/issues/44732 | |
197 | ||
a1dfa0c6 XL |
198 | ### Add aliases for an item in documentation search |
199 | ||
200 | This feature allows you to add alias(es) to an item when using the `rustdoc` search through the | |
201 | `doc(alias)` attribute. Example: | |
202 | ||
203 | ```rust,no_run | |
204 | #![feature(doc_alias)] | |
205 | ||
206 | #[doc(alias = "x")] | |
207 | #[doc(alias = "big")] | |
208 | pub struct BigX; | |
209 | ``` | |
210 | ||
211 | Then, when looking for it through the `rustdoc` search, if you enter "x" or | |
212 | "big", search will show the `BigX` struct first. | |
213 | ||
0531ce1d XL |
214 | ## Unstable command-line arguments |
215 | ||
216 | These features are enabled by passing a command-line flag to Rustdoc, but the flags in question are | |
217 | themselves marked as unstable. To use any of these options, pass `-Z unstable-options` as well as | |
218 | the flag in question to Rustdoc on the command-line. To do this from Cargo, you can either use the | |
219 | `RUSTDOCFLAGS` environment variable or the `cargo rustdoc` command. | |
220 | ||
221 | ### `--markdown-before-content`: include rendered Markdown before the content | |
222 | ||
223 | Using this flag looks like this: | |
224 | ||
225 | ```bash | |
226 | $ rustdoc src/lib.rs -Z unstable-options --markdown-before-content extra.md | |
227 | $ rustdoc README.md -Z unstable-options --markdown-before-content extra.md | |
228 | ``` | |
229 | ||
230 | Just like `--html-before-content`, this allows you to insert extra content inside the `<body>` tag | |
231 | but before the other content `rustdoc` would normally produce in the rendered documentation. | |
232 | However, instead of directly inserting the file verbatim, `rustdoc` will pass the files through a | |
233 | Markdown renderer before inserting the result into the file. | |
234 | ||
235 | ### `--markdown-after-content`: include rendered Markdown after the content | |
236 | ||
237 | Using this flag looks like this: | |
238 | ||
239 | ```bash | |
240 | $ rustdoc src/lib.rs -Z unstable-options --markdown-after-content extra.md | |
241 | $ rustdoc README.md -Z unstable-options --markdown-after-content extra.md | |
242 | ``` | |
243 | ||
244 | Just like `--html-after-content`, this allows you to insert extra content before the `</body>` tag | |
245 | but after the other content `rustdoc` would normally produce in the rendered documentation. | |
246 | However, instead of directly inserting the file verbatim, `rustdoc` will pass the files through a | |
247 | Markdown renderer before inserting the result into the file. | |
248 | ||
249 | ### `--playground-url`: control the location of the playground | |
250 | ||
251 | Using this flag looks like this: | |
252 | ||
253 | ```bash | |
254 | $ rustdoc src/lib.rs -Z unstable-options --playground-url https://play.rust-lang.org/ | |
255 | ``` | |
256 | ||
257 | When rendering a crate's docs, this flag gives the base URL of the Rust Playground, to use for | |
258 | generating `Run` buttons. Unlike `--markdown-playground-url`, this argument works for standalone | |
259 | Markdown files *and* Rust crates. This works the same way as adding `#![doc(html_playground_url = | |
260 | "url")]` to your crate root, as mentioned in [the chapter about the `#[doc]` | |
261 | attribute][doc-playground]. Please be aware that the official Rust Playground at | |
262 | https://play.rust-lang.org does not have every crate available, so if your examples require your | |
263 | crate, make sure the playground you provide has your crate available. | |
264 | ||
265 | [doc-playground]: the-doc-attribute.html#html_playground_url | |
266 | ||
267 | If both `--playground-url` and `--markdown-playground-url` are present when rendering a standalone | |
268 | Markdown file, the URL given to `--markdown-playground-url` will take precedence. If both | |
269 | `--playground-url` and `#![doc(html_playground_url = "url")]` are present when rendering crate docs, | |
270 | the attribute will take precedence. | |
271 | ||
272 | ### `--crate-version`: control the crate version | |
273 | ||
274 | Using this flag looks like this: | |
275 | ||
276 | ```bash | |
277 | $ rustdoc src/lib.rs -Z unstable-options --crate-version 1.3.37 | |
278 | ``` | |
279 | ||
280 | When `rustdoc` receives this flag, it will print an extra "Version (version)" into the sidebar of | |
281 | the crate root's docs. You can use this flag to differentiate between different versions of your | |
282 | library's documentation. | |
283 | ||
0531ce1d XL |
284 | ### `--sort-modules-by-appearance`: control how items on module pages are sorted |
285 | ||
286 | Using this flag looks like this: | |
287 | ||
288 | ```bash | |
289 | $ rustdoc src/lib.rs -Z unstable-options --sort-modules-by-appearance | |
290 | ``` | |
291 | ||
292 | Ordinarily, when `rustdoc` prints items in module pages, it will sort them alphabetically (taking | |
293 | some consideration for their stability, and names that end in a number). Giving this flag to | |
294 | `rustdoc` will disable this sorting and instead make it print the items in the order they appear in | |
295 | the source. | |
296 | ||
0531ce1d XL |
297 | ### `--resource-suffix`: modifying the name of CSS/JavaScript in crate docs |
298 | ||
299 | Using this flag looks like this: | |
300 | ||
301 | ```bash | |
302 | $ rustdoc src/lib.rs -Z unstable-options --resource-suffix suf | |
303 | ``` | |
304 | ||
305 | When rendering docs, `rustdoc` creates several CSS and JavaScript files as part of the output. Since | |
306 | all these files are linked from every page, changing where they are can be cumbersome if you need to | |
307 | specially cache them. This flag will rename all these files in the output to include the suffix in | |
308 | the filename. For example, `light.css` would become `light-suf.css` with the above command. | |
309 | ||
310 | ### `--display-warnings`: display warnings when documenting or running documentation tests | |
311 | ||
312 | Using this flag looks like this: | |
313 | ||
314 | ```bash | |
315 | $ rustdoc src/lib.rs -Z unstable-options --display-warnings | |
316 | $ rustdoc --test src/lib.rs -Z unstable-options --display-warnings | |
317 | ``` | |
318 | ||
319 | The intent behind this flag is to allow the user to see warnings that occur within their library or | |
320 | their documentation tests, which are usually suppressed. However, [due to a | |
321 | bug][issue-display-warnings], this flag doesn't 100% work as intended. See the linked issue for | |
322 | details. | |
323 | ||
324 | [issue-display-warnings]: https://github.com/rust-lang/rust/issues/41574 | |
325 | ||
b7449926 | 326 | ### `--extern-html-root-url`: control how rustdoc links to non-local crates |
0531ce1d XL |
327 | |
328 | Using this flag looks like this: | |
329 | ||
330 | ```bash | |
b7449926 | 331 | $ rustdoc src/lib.rs -Z unstable-options --extern-html-root-url some-crate=https://example.com/some-crate/1.0.1 |
0531ce1d XL |
332 | ``` |
333 | ||
b7449926 XL |
334 | Ordinarily, when rustdoc wants to link to a type from a different crate, it looks in two places: |
335 | docs that already exist in the output directory, or the `#![doc(doc_html_root)]` set in the other | |
336 | crate. However, if you want to link to docs that exist in neither of those places, you can use these | |
337 | flags to control that behavior. When the `--extern-html-root-url` flag is given with a name matching | |
338 | one of your dependencies, rustdoc use that URL for those docs. Keep in mind that if those docs exist | |
339 | in the output directory, those local docs will still override this flag. | |
0531ce1d XL |
340 | |
341 | ### `-Z force-unstable-if-unmarked` | |
342 | ||
343 | Using this flag looks like this: | |
344 | ||
345 | ```bash | |
346 | $ rustdoc src/lib.rs -Z force-unstable-if-unmarked | |
347 | ``` | |
348 | ||
349 | This is an internal flag intended for the standard library and compiler that applies an | |
350 | `#[unstable]` attribute to any dependent crate that doesn't have another stability attribute. This | |
351 | allows `rustdoc` to be able to generate documentation for the compiler crates and the standard | |
352 | library, as an equivalent command-line argument is provided to `rustc` when building those crates. | |
83c7162d | 353 | |
a1dfa0c6 | 354 | ### `--index-page`: provide a top-level landing page for docs |
83c7162d | 355 | |
a1dfa0c6 XL |
356 | This feature allows you to generate an index-page with a given markdown file. A good example of it |
357 | is the [rust documentation index](https://doc.rust-lang.org/index.html). | |
83c7162d | 358 | |
a1dfa0c6 | 359 | With this, you'll have a page which you can custom as much as you want at the top of your crates. |
83c7162d | 360 | |
a1dfa0c6 | 361 | Using `index-page` option enables `enable-index-page` option as well. |
83c7162d | 362 | |
a1dfa0c6 XL |
363 | ### `--enable-index-page`: generate a default index page for docs |
364 | ||
365 | This feature allows the generation of a default index-page which lists the generated crates. | |
0731742a XL |
366 | |
367 | ### `--static-root-path`: control how static files are loaded in HTML output | |
368 | ||
369 | Using this flag looks like this: | |
370 | ||
371 | ```bash | |
372 | $ rustdoc src/lib.rs -Z unstable-options --static-root-path '/cache/' | |
373 | ``` | |
374 | ||
375 | This flag controls how rustdoc links to its static files on HTML pages. If you're hosting a lot of | |
376 | crates' docs generated by the same version of rustdoc, you can use this flag to cache rustdoc's CSS, | |
377 | JavaScript, and font files in a single location, rather than duplicating it once per "doc root" | |
378 | (grouping of crate docs generated into the same output directory, like with `cargo doc`). Per-crate | |
379 | files like the search index will still load from the documentation root, but anything that gets | |
380 | renamed with `--resource-suffix` will load from the given path. | |
9fa01778 XL |
381 | |
382 | ### `--persist-doctests`: persist doctest executables after running | |
383 | ||
384 | Using this flag looks like this: | |
385 | ||
386 | ```bash | |
387 | $ rustdoc src/lib.rs --test -Z unstable-options --persist-doctests target/rustdoctest | |
388 | ``` | |
389 | ||
390 | This flag allows you to keep doctest executables around after they're compiled or run. | |
391 | Usually, rustdoc will immediately discard a compiled doctest after it's been tested, but | |
392 | with this option, you can keep those binaries around for farther testing. | |
532ac7d7 XL |
393 | |
394 | ### `--show-coverage`: calculate the percentage of items with documentation | |
395 | ||
396 | Using this flag looks like this: | |
397 | ||
398 | ```bash | |
399 | $ rustdoc src/lib.rs -Z unstable-options --show-coverage | |
400 | ``` | |
401 | ||
402 | If you want to determine how many items in your crate are documented, pass this flag to rustdoc. | |
403 | When it receives this flag, it will count the public items in your crate that have documentation, | |
404 | and print out the counts and a percentage instead of generating docs. | |
405 | ||
406 | Some methodology notes about what rustdoc counts in this metric: | |
407 | ||
408 | * Rustdoc will only count items from your crate (i.e. items re-exported from other crates don't | |
409 | count). | |
410 | * Docs written directly onto inherent impl blocks are not counted, even though their doc comments | |
411 | are displayed, because the common pattern in Rust code is to write all inherent methods into the | |
412 | same impl block. | |
413 | * Items in a trait implementation are not counted, as those impls will inherit any docs from the | |
414 | trait itself. | |
415 | * By default, only public items are counted. To count private items as well, pass | |
416 | `--document-private-items` at the same time. | |
417 | ||
418 | Public items that are not documented can be seen with the built-in `missing_docs` lint. Private | |
419 | items that are not documented can be seen with Clippy's `missing_docs_in_private_items` lint. | |
e1599b0c XL |
420 | |
421 | ### `--enable-per-target-ignores`: allow `ignore-foo` style filters for doctests | |
422 | ||
423 | Using this flag looks like this: | |
424 | ||
425 | ```bash | |
426 | $ rustdoc src/lib.rs -Z unstable-options --enable-per-target-ignores | |
427 | ``` | |
428 | ||
429 | This flag allows you to tag doctests with compiltest style `ignore-foo` filters that prevent | |
430 | rustdoc from running that test if the target triple string contains foo. For example: | |
431 | ||
432 | ```rust | |
433 | ///```ignore-foo,ignore-bar | |
434 | ///assert!(2 == 2); | |
435 | ///``` | |
436 | struct Foo; | |
437 | ``` | |
438 | ||
439 | This will not be run when the build target is `super-awesome-foo` or `less-bar-awesome`. | |
440 | If the flag is not enabled, then rustdoc will consume the filter, but do nothing with it, and | |
441 | the above example will be run for all targets. | |
442 | If you want to preserve backwards compatibility for older versions of rustdoc, you can use | |
443 | ||
444 | ```rust | |
445 | ///```ignore,ignore-foo | |
446 | ///assert!(2 == 2); | |
447 | ///``` | |
448 | struct Foo; | |
449 | ``` | |
450 | ||
451 | In older versions, this will be ignored on all targets, but on newer versions `ignore-gnu` will | |
452 | override `ignore`. | |
453 | ||
454 | ### `--runtool`, `--runtool-arg`: program to run tests with; args to pass to it | |
455 | ||
456 | Using thses options looks like this: | |
457 | ||
458 | ```bash | |
459 | $ rustdoc src/lib.rs -Z unstable-options --runtool runner --runtool-arg --do-thing --runtool-arg --do-other-thing | |
460 | ``` | |
461 | ||
462 | These options can be used to run the doctest under a program, and also pass arguments to | |
463 | that program. For example, if you want to run your doctests under valgrind you might run | |
464 | ||
465 | ```bash | |
466 | $ rustdoc src/lib.rs -Z unstable-options --runtool valgrind | |
467 | ``` | |
468 | ||
469 | Another use case would be to run a test inside an emulator, or through a Virtual Machine. |