improve documentation of rustdoc doctest feature

Author: GuillaumeGomez

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

@@ -382,22 +382,22 @@ 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
+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.
+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(usize);
+pub struct MyStruct(pub usize);
 
 /// ```compile_fail
 /// let x = my_crate::MyStruct(-5);
@@ -406,7 +406,22 @@ pub struct MyStruct(usize);
 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.
+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.
 
-[documentation tests]: documentation-tests.html
+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,no_run (includes-extra-file)
+#![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.