message: Update documentation for -Zrustdoc-scrape-examples in the Cargo Book
diff: @@ -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)
  