Skip to content
Permalink
Browse files

stabilize cfg(doctest)

  • Loading branch information...
GuillaumeGomez committed Aug 1, 2019
1 parent b9de4ef commit 116185e0329fbcde6af633c0a972882c97ecb9e3
@@ -379,3 +379,31 @@ However, it's preferable to use fenced code blocks over indented code blocks.
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.

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
/// 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
@@ -211,36 +211,6 @@ pub struct BigX;
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
@@ -241,6 +241,8 @@ declare_features! (
(accepted, underscore_const_names, "1.37.0", Some(54912), None),
/// Allows free and inherent `async fn`s, `async` blocks, and `<expr>.await` expressions.
(accepted, async_await, "1.39.0", Some(50547), None),
/// Allows the use of `#[cfg(doctest)]`, set when rustdoc is collecting doctests.
(accepted, cfg_doctest, "1.39.0", Some(62210), None),

// -------------------------------------------------------------------------
// feature-group-end: accepted features
@@ -520,9 +520,6 @@ declare_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),

@@ -30,7 +30,6 @@ const GATED_CFGS: &[(Symbol, Symbol, GateFn)] = &[
(sym::target_thread_local, sym::cfg_target_thread_local, cfg_fn!(cfg_target_thread_local)),
(sym::target_has_atomic, 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)]
@@ -5,8 +5,6 @@
// 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:
///
/// ```
@@ -1,7 +1,7 @@

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

@@ -1,5 +1,3 @@
#![feature(cfg_doctest)]

// @!has cfg_doctest/struct.SomeStruct.html
// @!has cfg_doctest/index.html '//a/@href' 'struct.SomeStruct.html'

This file was deleted.

This file was deleted.

0 comments on commit 116185e

Please sign in to comment.
You can’t perform that action at this time.