Support ignore for lint examples.

Author: ehuss

compiler/rustc_session/src/lint.rs

@@ -319,8 +319,10 @@ impl LintBuffer {
 ///
 /// The `{{produces}}` tag will be automatically replaced with the output from
 /// the example by the build system. You can build and view the rustc book
-/// with `x.py doc --stage=1 src/doc/rustc --open` (use --stage=0 if just
-/// changing the wording of an existing lint).
+/// with `x.py doc --stage=1 src/doc/rustc --open`. If the lint example is too
+/// complex to run as a simple example (for example, it needs an extern
+/// crate), mark it with `ignore` and manually paste the expected output below
+/// the example.
 #[macro_export]
 macro_rules! declare_lint {
     ($(#[$attr:meta])* $vis: vis $NAME: ident, $Level: ident, $desc: expr) => (

compiler/rustc_session/src/lint/builtin.rs

@@ -128,7 +128,7 @@ declare_lint! {
     ///
     /// ### Example
     ///
-    /// ```rust,compile_fail
+    /// ```rust,ignore (needs separate file)
     /// fn main() {
     ///     include!("foo.txt");
     /// }
@@ -344,7 +344,7 @@ declare_lint! {
     ///
     /// ### Example
     ///
-    /// ```rust,compile_fail
+    /// ```rust,ignore (needs extern crate)
     /// #![deny(unused_crate_dependencies)]
     /// ```
     ///
@@ -1984,7 +1984,7 @@ declare_lint! {
     ///
     /// ### Example
     ///
-    /// ```rust,compile_fail
+    /// ```rust,ignore (needs extern crate)
     /// #![deny(macro_use_extern_crate)]
     ///
     /// #[macro_use]
@@ -2378,7 +2378,19 @@ declare_lint! {
     /// }
     /// ```
     ///
-    /// {{produces}}
+    /// This will produce:
+    ///
+    /// ```text
+    /// warning: formatting may not be suitable for sub-register argument
+    ///  --> src/main.rs:6:19
+    ///   |
+    /// 6 |         asm!("mov {0}, {0}", in(reg) 0i16);
+    ///   |                   ^^^  ^^^           ---- for this argument
+    ///   |
+    ///   = note: `#[warn(asm_sub_register)]` on by default
+    ///   = help: use the `x` modifier to have the register formatted as `ax`
+    ///   = help: or use the `r` modifier to keep the default formatting of `rax`
+    /// ```
     ///
     /// ### Explanation
     ///

src/tools/lint-docs/src/lib.rs

@@ -19,6 +19,13 @@ impl Lint {
     fn doc_contains(&self, text: &str) -> bool {
         self.doc.iter().any(|line| line.contains(text))
     }
+
+    fn is_ignored(&self) -> bool {
+        self.doc
+            .iter()
+            .filter(|line| line.starts_with("```rust"))
+            .all(|line| line.contains(",ignore"))
+    }
 }
 
 #[derive(Clone, Copy, PartialEq)]
@@ -208,13 +215,8 @@ fn generate_output_example(
     // try to avoid adding to this list.
     if matches!(
         lint.name.as_str(),
-        "unused_features"
-            | "unstable_features"
-            | "incomplete_include"
-            | "unused_crate_dependencies"
-            | "exported_private_dependencies"
-            | "proc_macro_derive_resolution_fallback"
-            | "macro_use_extern_crate"
+        "unused_features" // broken lint
+        | "unstable_features" // deprecated
     ) {
         return Ok(());
     }
@@ -223,13 +225,22 @@ fn generate_output_example(
         return Ok(());
     }
     check_style(lint)?;
-    replace_produces(lint, rustc_path, verbose)?;
+    // Unfortunately some lints have extra requirements that this simple test
+    // setup can't handle (like extern crates). An alternative is to use a
+    // separate test suite, and use an include mechanism such as mdbook's
+    // `{{#rustdoc_include}}`.
+    if !lint.is_ignored() {
+        replace_produces(lint, rustc_path, verbose)?;
+    }
     Ok(())
 }
 
 /// Checks the doc style of the lint.
 fn check_style(lint: &Lint) -> Result<(), Box<dyn Error>> {
-    for expected in &["### Example", "### Explanation", "{{produces}}"] {
+    for &expected in &["### Example", "### Explanation", "{{produces}}"] {
+        if expected == "{{produces}}" && lint.is_ignored() {
+            continue;
+        }
         if !lint.doc_contains(expected) {
             return Err(format!("lint docs should contain the line `{}`", expected).into());
         }