Not only are fenced code blocks considered more idiomatic for Rust code,
but there is no way to use directives such as `ignore` or `should_panic` with
indented code blocks.
+
+### Include items only when collecting doctests
+
+Rustdoc's [documentation tests] can do some things that regular unit tests can't, so it can
+sometimes be useful to extend your doctests with samples that wouldn't otherwise need to be in
+documentation. To this end, Rustdoc allows you to have certain items only appear when it's
+collecting doctests, so you can utilize doctest functionality without forcing the test to appear in
+docs, or to find an arbitrary private item to include it on.
+
+When compiling a crate for use in doctests (with `--test` option), rustdoc will set `cfg(doctest)`.
+Note that they will still link against only the public items of your crate; if you need to
+test private items, either make items conditionally public via `cfg(doctest)` or write a unit test.
+
+In this example, we're adding doctests that we know won't compile, to verify that our struct can
+only take in valid data:
+
+```rust
+/// We have a struct here. Remember it doesn't accept negative numbers!
+pub struct MyStruct(usize);
+
+/// ```compile_fail
+/// let x = my_crate::MyStruct(-5);
+/// ```
+#[cfg(doctest)]
+pub struct MyStructOnlyTakesUsize;
+```
+
+Please note that the struct `MyStructOnlyTakesUsize` will not appear in documentation or in the
+public API considering it only exists when running rustdoc with the `--test` option.
+
+[documentation tests]: documentation-tests.html
Then, when looking for it through the `rustdoc` search, if you enter "x" or
"big", search will show the `BigX` struct first.
-### Include items only when collecting doctests
-
-Rustdoc's [documentation tests] can do some things that regular unit tests can't, so it can
-sometimes be useful to extend your doctests with samples that wouldn't otherwise need to be in
-documentation. To this end, Rustdoc allows you to have certain items only appear when it's
-collecting doctests, so you can utilize doctest functionality without forcing the test to appear in
-docs, or to find an arbitrary private item to include it on.
-
-If you add `#![feature(cfg_doctest)]` to your crate, Rustdoc will set `cfg(doctest)` when collecting
-doctests. Note that they will still link against only the public items of your crate; if you need to
-test private items, unit tests are still the way to go.
-
-In this example, we're adding doctests that we know won't compile, to verify that our struct can
-only take in valid data:
-
-```rust
-#![feature(cfg_doctest)]
-
-/// We have a struct here. Remember it doesn't accept negative numbers!
-pub struct MyStruct(usize);
-
-/// ```compile_fail
-/// let x = my_crate::MyStruct(-5);
-/// ```
-#[cfg(doctest)]
-pub struct MyStructOnlyTakesUsize;
-```
-
-[documentation tests]: documentation-tests.html
-
## Unstable command-line arguments
These features are enabled by passing a command-line flag to Rustdoc, but the flags in question are
(accepted, non_exhaustive, "1.40.0", Some(44109), None),
/// Allows calling constructor functions in `const fn`.
(accepted, const_constructor, "1.40.0", Some(61456), None),
+ /// Allows the use of `#[cfg(doctest)]`, set when rustdoc is collecting doctests.
+ (accepted, cfg_doctest, "1.40.0", Some(62210), None),
// -------------------------------------------------------------------------
// feature-group-end: accepted features
/// Allows `async || body` closures.
(active, async_closure, "1.37.0", Some(62290), None),
- /// Allows the use of `#[cfg(doctest)]`; set when rustdoc is collecting doctests.
- (active, cfg_doctest, "1.37.0", Some(62210), None),
-
/// Allows `[x; N]` where `x` is a constant (RFC 2203).
(active, const_in_array_repeat_expressions, "1.37.0", Some(49147), None),
(sym::target_has_atomic, sym::cfg_target_has_atomic, cfg_fn!(cfg_target_has_atomic)),
(sym::target_has_atomic_load_store, sym::cfg_target_has_atomic, cfg_fn!(cfg_target_has_atomic)),
(sym::rustdoc, sym::doc_cfg, cfg_fn!(doc_cfg)),
- (sym::doctest, sym::cfg_doctest, cfg_fn!(cfg_doctest)),
];
#[derive(Debug)]
// Crates like core have doctests gated on `cfg(not(test))` so we need to make
// sure `cfg(test)` is not active when running `rustdoc --test`.
-#![feature(cfg_doctest)]
-
/// this doctest will be ignored:
///
/// ```
running 2 tests
-test $DIR/cfg-test.rs - Bar (line 28) ... ok
-test $DIR/cfg-test.rs - Foo (line 20) ... ok
+test $DIR/cfg-test.rs - Bar (line 26) ... ok
+test $DIR/cfg-test.rs - Foo (line 18) ... ok
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
-#![feature(cfg_doctest)]
-
// @!has cfg_doctest/struct.SomeStruct.html
// @!has cfg_doctest/index.html '//a/@href' 'struct.SomeStruct.html'
+++ /dev/null
-#[cfg(doctest)] //~ ERROR
-pub struct SomeStruct;
-
-fn main() {}
+++ /dev/null
-error[E0658]: `cfg(doctest)` is experimental and subject to change
- --> $DIR/feature-gate-cfg_doctest.rs:1:7
- |
-LL | #[cfg(doctest)]
- | ^^^^^^^
- |
- = note: for more information, see https://github.com/rust-lang/rust/issues/62210
- = help: add `#![feature(cfg_doctest)]` to the crate attributes to enable
-
-error: aborting due to previous error
-
-For more information about this error, try `rustc --explain E0658`.
projects / rust.git / commitdiff