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
9 [Unstable Book]: ../unstable-book/index.html
11 ## Nightly-gated functionality
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
18 ### Error numbers for `compile-fail` doctests
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
25 [doctest-attributes]: documentation-tests.html#attributes
29 extern { fn some_func<T>(x: T); }
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
38 Attempting to use these error numbers on stable will result in the code sample being interpreted as
41 ## Extensions to the `#[doc]` attribute
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.
46 ### `#[doc(cfg)]`: Recording what platforms or features are required for code to be present
48 You can use `#[doc(cfg(...))]` to tell Rustdoc exactly which platform items appear on.
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.
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:
63 /// Token struct that can only be used on Windows.
64 #[cfg(any(windows, doc))]
66 pub struct WindowsToken;
68 /// Token struct that can only be used on Unix.
69 #[cfg(any(unix, doc))]
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;
80 In this sample, the tokens will only appear on their respective platforms, but they will both appear
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].
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
91 ### Adding your trait to the "Important Traits" dialog
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.
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.
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].
109 [unstable-spotlight]: ../unstable-book/language-features/doc-spotlight.html
110 [issue-spotlight]: https://github.com/rust-lang/rust/issues/45040
112 ### Exclude certain dependencies from documentation
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
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.
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].
129 [unstable-masked]: ../unstable-book/language-features/doc-masked.html
130 [issue-masked]: https://github.com/rust-lang/rust/issues/44027
132 ### Include external files as API documentation
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.
139 [RFC 1990]: https://github.com/rust-lang/rfcs/pull/1990
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].
145 [unstable-include]: ../unstable-book/language-features/external-doc.html
146 [issue-include]: https://github.com/rust-lang/rust/issues/44732
148 ## Unstable command-line arguments
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.
155 ### `--markdown-before-content`: include rendered Markdown before the content
157 Using this flag looks like this:
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
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.
169 ### `--markdown-after-content`: include rendered Markdown after the content
171 Using this flag looks like this:
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
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.
183 ### `--playground-url`: control the location of the playground
185 Using this flag looks like this:
188 $ rustdoc src/lib.rs -Z unstable-options --playground-url https://play.rust-lang.org/
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.
199 [doc-playground]: the-doc-attribute.html#html_playground_url
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.
206 ### `--sort-modules-by-appearance`: control how items on module pages are sorted
208 Using this flag looks like this:
211 $ rustdoc src/lib.rs -Z unstable-options --sort-modules-by-appearance
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
219 ### `--resource-suffix`: modifying the name of CSS/JavaScript in crate docs
221 Using this flag looks like this:
224 $ rustdoc src/lib.rs -Z unstable-options --resource-suffix suf
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.
232 ### `--display-warnings`: display warnings when documenting or running documentation tests
234 Using this flag looks like this:
237 $ rustdoc src/lib.rs -Z unstable-options --display-warnings
238 $ rustdoc --test src/lib.rs -Z unstable-options --display-warnings
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
246 [issue-display-warnings]: https://github.com/rust-lang/rust/issues/41574
248 ### `--extern-html-root-url`: control how rustdoc links to non-local crates
250 Using this flag looks like this:
253 $ rustdoc src/lib.rs -Z unstable-options --extern-html-root-url some-crate=https://example.com/some-crate/1.0.1
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.
263 ### `-Z force-unstable-if-unmarked`
265 Using this flag looks like this:
268 $ rustdoc src/lib.rs -Z force-unstable-if-unmarked
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.
276 ### `--index-page`: provide a top-level landing page for docs
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).
281 With this, you'll have a page which you can custom as much as you want at the top of your crates.
283 Using `index-page` option enables `enable-index-page` option as well.
285 ### `--enable-index-page`: generate a default index page for docs
287 This feature allows the generation of a default index-page which lists the generated crates.
289 ### `--static-root-path`: control how static files are loaded in HTML output
291 Using this flag looks like this:
294 $ rustdoc src/lib.rs -Z unstable-options --static-root-path '/cache/'
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.
304 ### `--persist-doctests`: persist doctest executables after running
306 Using this flag looks like this:
309 $ rustdoc src/lib.rs --test -Z unstable-options --persist-doctests target/rustdoctest
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.
316 ### `--show-coverage`: calculate the percentage of items with documentation
318 Using this flag looks like this:
321 $ rustdoc src/lib.rs -Z unstable-options --show-coverage
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.
328 Some methodology notes about what rustdoc counts in this metric:
330 * Rustdoc will only count items from your crate (i.e. items re-exported from other crates don't
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
335 * Items in a trait implementation are not counted, as those impls will inherit any docs from the
337 * By default, only public items are counted. To count private items as well, pass
338 `--document-private-items` at the same time.
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.
343 ## `-w`/`--output-format`: output format
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:
351 /// This item has documentation
354 pub fn no_documentation() {}
358 {"no_std.rs":{"total":3,"with_docs":1,"total_examples":3,"with_examples":0}}
361 Note that the third item is the crate root, which in this case is undocumented.
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.
367 ### `--enable-per-target-ignores`: allow `ignore-foo` style filters for doctests
369 Using this flag looks like this:
372 $ rustdoc src/lib.rs -Z unstable-options --enable-per-target-ignores
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:
379 ///```ignore-foo,ignore-bar
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
391 ///```ignore,ignore-foo
397 In older versions, this will be ignored on all targets, but on newer versions `ignore-gnu` will
400 ### `--runtool`, `--runtool-arg`: program to run tests with; args to pass to it
402 Using these options looks like this:
405 $ rustdoc src/lib.rs -Z unstable-options --runtool runner --runtool-arg --do-thing --runtool-arg --do-other-thing
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
412 $ rustdoc src/lib.rs -Z unstable-options --runtool valgrind
415 Another use case would be to run a test inside an emulator, or through a Virtual Machine.
417 ### `--show-coverage`: get statistics about code documentation coverage
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:
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 +-------------------------------------+------------+------------+------------+------------+
433 You can also use this option with the `--output-format` one:
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}}
440 Calculating code examples follows these rules:
442 1. These items aren't accounted by default:
448 2. If one of the previously listed items has a code example, then it'll be counted.