Auto merge of #11425 - willcrichton:scrape-examples-documentation, r=…

…weihanglo

Update documentation for -Zrustdoc-scrape-examples in the Cargo Book

### What does this PR try to resolve?

Description in the title. Fixes #11424.

### How should we test and review this PR?

Here's a screenshot of the updated documentation:

<img width="814" alt="Screen Shot 2022-11-25 at 6 24 49 PM" src="https://user-images.githubusercontent.com/663326/204065460-4e06c638-7e3d-4c00-a805-7cb4b5a3803b.png">

r? `@weihanglo`

src/doc/src/reference/unstable.md

@@ -1154,15 +1154,44 @@ path = "src/main.rs"
 * RFC: [#3123](https://github.com/rust-lang/rfcs/pull/3123)
 * Tracking Issue: [#9910](https://github.com/rust-lang/cargo/issues/9910)
 
-The `-Z rustdoc-scrape-examples` argument tells Rustdoc to search crates in the current workspace
-for calls to functions. Those call-sites are then included as documentation. The flag can take an
-argument of `all` or `examples` which configures which crate in the workspace to analyze for examples.
-For instance:
+The `-Z rustdoc-scrape-examples` flag tells Rustdoc to search crates in the current workspace
+for calls to functions. Those call-sites are then included as documentation. You can use the flag
+like this:
 
 ```
-cargo doc -Z unstable-options -Z rustdoc-scrape-examples=examples
+cargo doc -Z unstable-options -Z rustdoc-scrape-examples
+```
+
+By default, Cargo will scrape from the packages that are being documented, as well as scrape from
+examples for the packages (i.e. those corresponding to the `--examples` flag). You can individually
+enable or disable targets from being scraped with the `doc-scrape-examples` flag, such as:
+
+```toml
+# Disable scraping examples from a library
+[lib]
+doc-scrape-examples = false
+
+# Enable scraping examples from a binary
+[[bin]]
+name = "my-bin"
+doc-scrape-examples = true
 ```
 
+**Note on tests:** enabling `doc-scrape-examples` on test targets will not currently have any effect. Scraping
+examples from tests is a work-in-progress.
+
+**Note on dev-dependencies:** documenting a library does not normally require the crate's dev-dependencies. However,
+example units do require dev-deps. For backwards compatibility, `-Z rustdoc-scrape-examples` will *not* introduce a 
+dev-deps requirement for `cargo doc`. Therefore examples will *not* be scraped from example targets under the 
+following conditions:
+
+1. No target being documented requires dev-deps, AND
+2. At least one crate being documented requires dev-deps, AND
+3. The `doc-scrape-examples` parameter is unset for `[[example]]` targets.
+
+If you want examples to be scraped from example targets, then you must not satisfy one of the above conditions.
+
+
 ### check-cfg
 
 * RFC: [#3013](https://github.com/rust-lang/rfcs/pull/3013)