Rollup merge of rust-lang#45767 - QuietMisdreavus:who-docs-the-doc-to…

…ol, r=frewsxcv

rustdoc book: talk about #![doc(test(no_crate_inject))] and #![doc(test(attr(...)))]

While investigating rust-lang#45750 i noticed that `#![doc(test(attr(...)))]` wasn't documented at all. Since this is useful for making your examples follow the same coding guidelines as your code, i wanted to add it to the Rustdoc Book. I also added `#![doc(test(no_crate_inject))]` since it's used in the same place and might be useful for macro-heavy crates. I added mentions for these to "The `doc` attribute" as well as "Documentation tests" since it's useful information in both places.

Technically the step reordering in the second commit is gated on rust-lang#45764, since before that lands attributes from the doctest come before the ones from `#![doc(test(attr(...)))]`.

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

@@ -38,17 +38,19 @@ function! Forcing you to write `main` for every example, no matter how small,
 adds friction. So `rustdoc` processes your examples slightly before
 running them. Here's the full algorithm rustdoc uses to preprocess examples:
 
-1. Any leading `#![foo]` attributes are left intact as crate attributes.
-2. Some common `allow` attributes are inserted, including
+1. Some common `allow` attributes are inserted, including
    `unused_variables`, `unused_assignments`, `unused_mut`,
    `unused_attributes`, and `dead_code`. Small examples often trigger
    these lints.
-3. If the example does not contain `extern crate`, then `extern crate
+2. Any attributes specified with `#![doc(test(attr(...)))]` are added.
+3. Any leading `#![foo]` attributes are left intact as crate attributes.
+4. If the example does not contain `extern crate`, and
+   `#![doc(test(no_crate_inject))]` was not specified, then `extern crate
    <mycrate>;` is inserted (note the lack of `#[macro_use]`).
-4. Finally, if the example does not contain `fn main`, the remainder of the
+5. Finally, if the example does not contain `fn main`, the remainder of the
    text is wrapped in `fn main() { your_code }`.
 
-For more about that caveat in rule 3, see "Documeting Macros" below.
+For more about that caveat in rule 4, see "Documeting Macros" below.
 
 ## Hiding portions of the example
 
@@ -261,4 +263,4 @@ are added.
 The `no_run` attribute will compile your code, but not run it. This is
 important for examples such as "Here's how to retrieve a web page,"
 which you would want to ensure compiles, but might be run in a test
-environment that has no network access.
+environment that has no network access.

src/doc/rustdoc/src/the-doc-attribute.md

@@ -103,6 +103,26 @@ to it in the docs. But if you include this:
 
 it will not.
 
+### `test(no_crate_inject)`
+
+By default, `rustdoc` will automatically add a line with `extern crate my_crate;` into each doctest.
+But if you include this:
+
+```rust,ignore
+#![doc(test(no_crate_inject))]
+```
+
+it will not.
+
+### `test(attr(...))`
+
+This form of the `doc` attribute allows you to add arbitrary attributes to all your doctests. For
+example, if you want your doctests to fail if they produce any warnings, you could add this:
+
+```rust,ignore
+#![doc(test(attr(deny(warnings))))]
+```
+
 ## At the item level
 
 These forms of the `#[doc]` attribute are used on individual items, to control how