Rollup merge of #81402 - ehuss:md-tidy, r=jyn514

tidy: Run tidy style against markdown files.

This adds tidy checks for markdown files.  I think it is useful to have some style enforcement (for the same reasons the style is enforced on other files).  I think it is worthwhile to avoid `ignore` on rust examples since having broken code in documentation is frustrating.  Avoiding trailing whitespace is good because it has semantic meaning in markdown, which I think should be avoided.

compiler/rustc_infer/src/infer/lexical_region_resolve/README.md

@@ -1,4 +1,3 @@
-
 Lexical Region Resolution was removed in https://github.com/rust-lang/rust/pull/64790.
 
 Rust now uses Non-lexical lifetimes. For more info, please see the [borrowck

src/doc/rustc/src/exploit-mitigations.md

@@ -378,7 +378,7 @@ C library default allocator<sup id="fnref:5" role="doc-noteref"><a
 href="#fn:5" class="footnote">5</a></sup> since version 1.32.0
 (2019-01-17)[39].
 
-```ignore
+```rust,no_run
 fn main() {
     let mut x = Box::new([0; 1024]);
 

src/doc/rustc/src/lints/levels.md

@@ -62,7 +62,7 @@ warning: unused variable: `x`
 A 'deny' lint produces an error if you violate it. For example, this code
 runs into the `exceeding_bitshifts` lint.
 
-```rust,ignore
+```rust,no_run
 fn main() {
     100u8 << 10;
 }
@@ -232,7 +232,7 @@ pub fn foo() {}
 This is the maximum level for all lints. So for example, if we take our
 code sample from the "deny" lint level above:
 
-```rust,ignore
+```rust,no_run
 fn main() {
     100u8 << 10;
 }

src/doc/rustc/src/lints/listing/index.md

@@ -2,4 +2,4 @@
 
 This section lists out all of the lints, grouped by their default lint levels.
 
-You can also see this list by running `rustc -W help`.
+You can also see this list by running `rustc -W help`.

src/doc/rustc/src/what-is-rustc.md

@@ -39,7 +39,7 @@ $ .\hello.exe # on Windows
 Note that we only ever pass `rustc` the *crate root*, not every file we wish
 to compile. For example, if we had a `main.rs` that looked like this:
 
-```rust,ignore
+```rust,ignore (needs-multiple-files)
 mod foo;
 
 fn main() {
@@ -49,7 +49,7 @@ fn main() {
 
 And a `foo.rs` that had this:
 
-```rust,ignore
+```rust,no_run
 pub fn hello() {
     println!("Hello, world!");
 }

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

@@ -47,16 +47,15 @@ all type errors and name resolution errors with function bodies. Note that this
 work for anything outside a function body: since Rustdoc documents your types, it has to
 know what those types are! For example, this code will work regardless of the platform:
 
-<!-- `ignore` because doc-tests are run with `rustc`, not `rustdoc` -->
-```ignore
+```rust,ignore (platform-specific,rustdoc-specific-behavior)
 pub fn f() {
     use std::os::windows::ffi::OsStrExt;
 }
 ```
 
 but this will not, because the unknown type is part of the function signature:
 
-```ignore
+```rust,ignore (platform-specific,rustdoc-specific-behavior)
 pub fn f() -> std::os::windows::ffi::EncodeWide<'static> {
     unimplemented!()
 }

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

@@ -5,12 +5,13 @@ that examples within your documentation are up to date and working.
 
 The basic idea is this:
 
-```ignore
+```rust,no_run
 /// # Examples
 ///
 /// ```
 /// let x = 5;
 /// ```
+# fn f() {}
 ```
 
 The triple backticks start and end code blocks. If this were in a file named `foo.rs`,
@@ -78,12 +79,13 @@ Sometimes, you need some setup code, or other things that would distract
 from your example, but are important to make the tests work. Consider
 an example block that looks like this:
 
-```ignore
+```rust,no_run
 /// ```
 /// /// Some documentation.
 /// # fn foo() {} // this function will be hidden
 /// println!("Hello, World!");
 /// ```
+# fn f() {}
 ```
 
 It will render like this:
@@ -196,12 +198,13 @@ When writing an example, it is rarely useful to include a complete error
 handling, as it would add significant amounts of boilerplate code. Instead, you
 may want the following:
 
-```ignore
+```rust,no_run
 /// ```
 /// use std::io;
 /// let mut input = String::new();
 /// io::stdin().read_line(&mut input)?;
 /// ```
+# fn f() {}
 ```
 
 The problem is that `?` returns a `Result<T, E>` and test functions don't
@@ -210,7 +213,7 @@ return anything, so this will give a mismatched types error.
 You can get around this limitation by manually adding a `main` that returns
 `Result<T, E>`, because `Result<T, E>` implements the `Termination` trait:
 
-```ignore
+```rust,no_run
 /// A doc test using ?
 ///
 /// ```
@@ -222,12 +225,13 @@ You can get around this limitation by manually adding a `main` that returns
 ///     Ok(())
 /// }
 /// ```
+# fn f() {}
 ```
 
 Together with the `# ` from the section above, you arrive at a solution that
 appears to the reader as the initial idea but works with doc tests:
 
-```ignore
+```rust,no_run
 /// ```
 /// use std::io;
 /// # fn main() -> io::Result<()> {
@@ -236,18 +240,20 @@ appears to the reader as the initial idea but works with doc tests:
 /// # Ok(())
 /// # }
 /// ```
+# fn f() {}
 ```
 
 As of version 1.34.0, one can also omit the `fn main()`, but you will have to
 disambiguate the error type:
 
-```ignore
+```rust,no_run
 /// ```
 /// use std::io;
 /// let mut input = String::new();
 /// io::stdin().read_line(&mut input)?;
 /// # Ok::<(), io::Error>(())
 /// ```
+# fn f() {}
 ```
 
 This is an unfortunate consequence of the `?` operator adding an implicit
@@ -417,7 +423,7 @@ Another possible use of `#[cfg(doctest)]` is to test doctests that are included
 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
+```rust,no_run
 #![feature(external_doc)]
 
 #[doc(include = "../README.md")]

src/doc/rustdoc/src/how-to-write-documentation.md

@@ -7,7 +7,7 @@ implementation detail, or leaves readers with unanswered questions.
 
 There are a few tenets to Rust documentation that can help guide anyone through
 the process of documenting libraries so that everyone has an ample opportunity
-to use the code.  
+to use the code.
 
 This chapter covers not only how to write documentation but specifically
 how to write **good** documentation.  It is important to be as clear
@@ -19,39 +19,39 @@ then it should be documented.
 
 Documenting a crate should begin with front-page documentation.  As an
 example, the [`hashbrown`] crate level documentation summarizes the role of
-the crate, provides links to explain technical details, and explains why you 
-would want to use the crate.  
+the crate, provides links to explain technical details, and explains why you
+would want to use the crate.
 
-After introducing the crate, it is important that the front-page gives 
+After introducing the crate, it is important that the front-page gives
 an example of how to use the crate in a real world setting.  Stick to the
 library's role in the example, but do so without shortcuts to benefit users who
-may copy and paste the example to get started. 
+may copy and paste the example to get started.
 
 [`futures`] uses inline comments to explain line by line
-the complexities of using a [`Future`], because a person's first exposure to 
+the complexities of using a [`Future`], because a person's first exposure to
 rust's [`Future`] may be this example.
 
-The [`backtrace`] documentation walks through the whole process, explaining 
+The [`backtrace`] documentation walks through the whole process, explaining
 changes made to the `Cargo.toml` file, passing command line arguments to the
-compiler, and shows a quick example of backtrace in the wild.  
+compiler, and shows a quick example of backtrace in the wild.
 
 Finally, the front-page can eventually become a comprehensive reference
 how to use a crate, like [`regex`].  In this front page, all
-requirements are outlined, the edge cases shown, and practical examples 
+requirements are outlined, the edge cases shown, and practical examples
 provided.  The front page goes on to show how to use regular expressions
 then concludes with crate features.
 
 Don't worry about comparing your crate, which is just beginning, to other more
 developed crates.  To get the documentation to something more polished, start
-incrementally and put in an introduction, example, and features.  Rome was not 
+incrementally and put in an introduction, example, and features.  Rome was not
 built in a day!
 
 The first lines within the `lib.rs` will compose the front-page, and they
 use a different convention than the rest of the rustdocs.  Lines should
 start with `//!` which indicate module-level or crate-level documentation.
 Here's a quick example of the difference:
 
-```rust,ignore
+```rust,no_run
 //! Fast and easy queue abstraction.
 //!
 //! Provides an abstraction over a queue.  When the abstraction is used
@@ -64,13 +64,13 @@ Here's a quick example of the difference:
 /// This module makes it easy.
 pub mod easy {
 
-    /// Use the abstract function to do this specific thing.
-    pub fn abstract() {}
+    /// Use the abstraction function to do this specific thing.
+    pub fn abstraction() {}
 
 }
 ```
 
-Ideally, this first line of documentation is a sentence without highly 
+Ideally, this first line of documentation is a sentence without highly
 technical details, but with a good description of where this crate fits
 within the rust ecosystem.  Users should know whether this crate meets their use
 case after reading this line.
@@ -95,7 +95,7 @@ It is recommended that each item's documentation follows this basic structure:
 
 This basic structure should be straightforward to follow when writing your
 documentation; while you might think that a code example is trivial,
-the examples are really important because they can help users understand 
+the examples are really important because they can help users understand
 what an item is, how it is used, and for what purpose it exists.
 
 Let's see an example coming from the [standard library] by taking a look at the
@@ -133,7 +133,7 @@ for argument in env::args() {
 [`args_os`]: ./fn.args_os.html
 ``````
 
-Everything before the first empty line will be reused to describe the component 
+Everything before the first empty line will be reused to describe the component
 in searches and module overviews.  For example, the function `std::env::args()`
 above will be shown on the [`std::env`] module documentation.  It is good
 practice to keep the summary to one line: concise writing is a goal of good
@@ -225,7 +225,7 @@ details on the exact syntax supported.
 [commonmark markdown specification]: https://commonmark.org/
 [commonmark quick reference]: https://commonmark.org/help/
 [env::args]: https://doc.rust-lang.org/stable/std/env/fn.args.html
-[`Future`]: https://doc.rust-lang.org/std/future/trait.Future.html 
+[`Future`]: https://doc.rust-lang.org/std/future/trait.Future.html
 [`futures`]: https://docs.rs/futures/0.3.5/futures/
 [`hashbrown`]: https://docs.rs/hashbrown/0.8.2/hashbrown/
 [`regex`]: https://docs.rs/regex/1.3.9/regex/

src/doc/rustdoc/src/lints.md

@@ -3,10 +3,11 @@
 `rustdoc` provides lints to help you writing and testing your documentation. You
 can use them like any other lints by doing this:
 
-```rust,ignore
+```rust
 #![allow(missing_docs)] // allows the lint, no diagnostics will be reported
 #![warn(missing_docs)] // warn if there are missing docs
 #![deny(missing_docs)] // error if there are missing docs
+# //! Crate docs.
 ```
 
 Here is the list of the lints provided by `rustdoc`:

src/doc/rustdoc/src/passes.md

@@ -32,8 +32,9 @@ Without this pass, these items will remain in the output.
 
 When you write a doc comment like this:
 
-```rust,ignore
+```rust,no_run
 /// This is a documentation comment.
+# fn f() {}
 ```
 
 There's a space between the `///` and that `T`. That spacing isn't intended
@@ -52,9 +53,10 @@ documentation string.
 
 For example:
 
-```rust,ignore
+```rust,no_run
 #[doc = "This is the first line."]
 #[doc = "This is the second line."]
+# fn f() {}
 ```
 
 Gets collapsed into a single doc string of
@@ -68,7 +70,7 @@ This is the second line.
 
 This removes documentation for any non-public items, so for example:
 
-```rust,ignore
+```rust,no_run
 /// These are private docs.
 struct Private;
 

src/doc/rustdoc/src/references.md

@@ -3,15 +3,15 @@
 There are many great `rustdoc` references out there.
 If you know of other great resources, please submit a pull request!
 
-## Official 
+## Official
 
 - [Learn Rust]
 - [Rust By Example]
 - [Rust Reference]
 - [RFC 1574: More API Documentation Conventions]
 - [RFC 1946: Intra Rustdoc Links]
 
-## Community 
+## Community
 - [API Guidelines]
 - [Github tagged RFCs]
 - [Github tagged issues]
@@ -28,4 +28,4 @@ If you know of other great resources, please submit a pull request!
 [RFC 1946: Intra Rustdoc Links]: https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html
 [RFC (stalled) front page styleguide]: https://github.com/rust-lang/rfcs/pull/1687
 [Rust By Example]: https://doc.rust-lang.org/stable/rust-by-example/meta/doc.html
-[Rust Reference]: https://doc.rust-lang.org/stable/reference/comments.html#doc-comments
+[Rust Reference]: https://doc.rust-lang.org/stable/reference/comments.html#doc-comments