Auto merge of rust-lang#63803 - GuillaumeGomez:stabilize-doctest, r=ollie27,QuietMisdreavus,Mark-Simulacrum

[rustdoc] stabilize cfg(doctest)

Fixes rust-lang#62210.

Since we removed rustdoc from providing cfg(test) on test runs, it's been replaced by cfg(doctest). It'd be nice to have it in not too far in the future.

Author: bors

src/doc/rustdoc/src/documentation-tests.md

@@ -379,3 +379,49 @@ 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.
+
+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, you need to 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(pub usize);
+
+/// ```compile_fail
+/// let x = my_crate::MyStruct(-5);
+/// ```
+#[cfg(doctest)]
+pub struct MyStructOnlyTakesUsize;
+```
+
+Note that the struct `MyStructOnlyTakesUsize` here isn't actually part of your public crate
+API. The use of `#[cfg(doctest)]` makes sure that this struct only exists while rustdoc is
+collecting doctests. This means that its doctest is executed when `--test` is passed to rustdoc,
+but is hidden from the public documentation.
+
+Another possible use of `cfg(doctest)` is to test doctests that are included in your README file
+without including it in your main documentation. For example, you could write this into your
+`lib.rs` to test your README as part of your doctests:
+
+```rust,ignore
+#![feature(extern_doc)]
+
+#[doc(include="../README.md")]
+#[cfg(doctest)]
+pub struct ReadmeDoctests;
+```
+
+This will include your README as documentation on the hidden struct `ReadmeDoctests`, which will
+then be tested alongside the rest of your doctests.

src/doc/rustdoc/src/unstable-features.md

@@ -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

src/libsyntax/feature_gate/accepted.rs

@@ -251,6 +251,8 @@ declare_features! (
     (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

src/libsyntax/feature_gate/active.rs

@@ -506,9 +506,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),
 

src/libsyntax/feature_gate/builtin_attrs.rs

@@ -31,7 +31,6 @@ const GATED_CFGS: &[(Symbol, Symbol, GateFn)] = &[
     (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)]

src/test/rustdoc-ui/cfg-test.rs

@@ -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:
 ///
 /// ```

src/test/rustdoc-ui/cfg-test.stdout

@@ -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
 

src/test/rustdoc/cfg-doctest.rs

@@ -1,5 +1,3 @@
-#![feature(cfg_doctest)]
-
 // @!has cfg_doctest/struct.SomeStruct.html
 // @!has cfg_doctest/index.html '//a/@href' 'struct.SomeStruct.html'