Rollup merge of rust-lang#82651 - jyn514:rustdoc-warnings, r=GuillaumeGomez

Cleanup rustdoc warnings

## Clean up error reporting for deprecated passes

Using `error!` here goes all the way back to the original commit, rust-lang#8540. I don't see any reason to use logging; rustdoc should use diagnostics wherever possible. See rust-lang#81932 (comment) for further context.

- Use spans for deprecated attributes
- Use a proper diagnostic for unknown passes, instead of error logging
- Add tests for unknown passes
- Improve some wording in diagnostics

##  Report that `doc(plugins)` doesn't work using diagnostics instead of `eprintln!`

This also adds a test for the output.

This was added in rust-lang#52194. I don't see any particular reason not to use diagnostics here, I think it was just missed in rust-lang#50541.

Author: JohnTitor

compiler/rustc_passes/src/check_attr.rs

@@ -576,7 +576,8 @@ impl CheckAttrVisitor<'tcx> {
                             sym::masked,
                             sym::no_default_passes, // deprecated
                             sym::no_inline,
-                            sym::passes, // deprecated
+                            sym::passes,  // deprecated
+                            sym::plugins, // removed, but rustdoc warns about it itself
                             sym::primitive,
                             sym::spotlight,
                             sym::test,

src/librustdoc/config.rs

@@ -658,9 +658,8 @@ fn check_deprecated_options(matches: &getopts::Matches, diag: &rustc_errors::Han
             {
                 continue;
             }
-            let mut err =
-                diag.struct_warn(&format!("the '{}' flag is considered deprecated", flag));
-            err.warn(
+            let mut err = diag.struct_warn(&format!("the `{}` flag is deprecated", flag));
+            err.note(
                 "see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \
                  for more information",
             );

src/librustdoc/core.rs

@@ -22,7 +22,7 @@ use rustc_session::DiagnosticOutput;
 use rustc_session::Session;
 use rustc_span::source_map;
 use rustc_span::symbol::sym;
-use rustc_span::DUMMY_SP;
+use rustc_span::{Span, DUMMY_SP};
 
 use std::cell::RefCell;
 use std::collections::hash_map::Entry;
@@ -389,7 +389,7 @@ crate fn run_global_ctxt(
     tcx: TyCtxt<'_>,
     resolver: Rc<RefCell<interface::BoxedResolver>>,
     mut default_passes: passes::DefaultPassOption,
-    mut manual_passes: Vec<String>,
+    manual_passes: Vec<String>,
     render_options: RenderOptions,
     output_format: OutputFormat,
 ) -> (clean::Crate, RenderOptions, Cache) {
@@ -490,21 +490,44 @@ crate fn run_global_ctxt(
         }
     }
 
-    fn report_deprecated_attr(name: &str, diag: &rustc_errors::Handler) {
-        let mut msg = diag
-            .struct_warn(&format!("the `#![doc({})]` attribute is considered deprecated", name));
-        msg.warn(
+    fn report_deprecated_attr(name: &str, diag: &rustc_errors::Handler, sp: Span) {
+        let mut msg =
+            diag.struct_span_warn(sp, &format!("the `#![doc({})]` attribute is deprecated", name));
+        msg.note(
             "see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \
              for more information",
         );
 
         if name == "no_default_passes" {
             msg.help("you may want to use `#![doc(document_private_items)]`");
+        } else if name.starts_with("plugins") {
+            msg.warn("`#![doc(plugins = \"...\")]` no longer functions; see CVE-2018-1000622 <https://nvd.nist.gov/vuln/detail/CVE-2018-1000622>");
         }
 
         msg.emit();
     }
 
+    let parse_pass = |name: &str, sp: Option<Span>| {
+        if let Some(pass) = passes::find_pass(name) {
+            Some(ConditionalPass::always(pass))
+        } else {
+            let msg = &format!("ignoring unknown pass `{}`", name);
+            let mut warning = if let Some(sp) = sp {
+                tcx.sess.struct_span_warn(sp, msg)
+            } else {
+                tcx.sess.struct_warn(msg)
+            };
+            if name == "collapse-docs" {
+                warning.note("the `collapse-docs` pass was removed in #80261 <https://github.com/rust-lang/rust/pull/80261>");
+            }
+            warning.emit();
+            None
+        }
+    };
+
+    let mut manual_passes: Vec<_> =
+        manual_passes.into_iter().flat_map(|name| parse_pass(&name, None)).collect();
+
     // Process all of the crate attributes, extracting plugin metadata along
     // with the passes which we are supposed to run.
     for attr in krate.module.as_ref().unwrap().attrs.lists(sym::doc) {
@@ -513,29 +536,25 @@ crate fn run_global_ctxt(
         let name = attr.name_or_empty();
         if attr.is_word() {
             if name == sym::no_default_passes {
-                report_deprecated_attr("no_default_passes", diag);
+                report_deprecated_attr("no_default_passes", diag, attr.span());
                 if default_passes == passes::DefaultPassOption::Default {
                     default_passes = passes::DefaultPassOption::None;
                 }
             }
         } else if let Some(value) = attr.value_str() {
-            let sink = match name {
+            match name {
                 sym::passes => {
-                    report_deprecated_attr("passes = \"...\"", diag);
-                    &mut manual_passes
+                    report_deprecated_attr("passes = \"...\"", diag, attr.span());
                 }
                 sym::plugins => {
-                    report_deprecated_attr("plugins = \"...\"", diag);
-                    eprintln!(
-                        "WARNING: `#![doc(plugins = \"...\")]` \
-                         no longer functions; see CVE-2018-1000622"
-                    );
+                    report_deprecated_attr("plugins = \"...\"", diag, attr.span());
                     continue;
                 }
                 _ => continue,
             };
             for name in value.as_str().split_whitespace() {
-                sink.push(name.to_string());
+                let span = attr.name_value_literal_span().unwrap_or(attr.span());
+                manual_passes.extend(parse_pass(name, Some(span)));
             }
         }
 
@@ -544,17 +563,7 @@ crate fn run_global_ctxt(
         }
     }
 
-    let passes = passes::defaults(default_passes).iter().copied().chain(
-        manual_passes.into_iter().flat_map(|name| {
-            if let Some(pass) = passes::find_pass(&name) {
-                Some(ConditionalPass::always(pass))
-            } else {
-                error!("unknown pass {}, skipping", name);
-                None
-            }
-        }),
-    );
-
+    let passes = passes::defaults(default_passes).iter().copied().chain(manual_passes);
     info!("Executing passes");
 
     for p in passes {

src/test/rustdoc-ui/deprecated-attrs.rs

@@ -1,7 +1,17 @@
 // check-pass
+// compile-flags: --passes unknown-pass
+// error-pattern: ignoring unknown pass `unknown-pass`
 
-#![doc(no_default_passes, passes = "unindent-comments")]
-
-struct SomeStruct;
-
-pub struct OtherStruct;
+#![doc(no_default_passes)]
+//~^ WARNING attribute is deprecated
+//~| NOTE see issue #44136
+//~| HELP use `#![doc(document_private_items)]`
+#![doc(passes = "collapse-docs unindent-comments")]
+//~^ WARNING attribute is deprecated
+//~| NOTE see issue #44136
+//~| WARNING ignoring unknown pass
+//~| NOTE `collapse-docs` pass was removed
+#![doc(plugins = "xxx")]
+//~^ WARNING attribute is deprecated
+//~| NOTE see issue #44136
+//~| WARNING no longer functions; see CVE

src/test/rustdoc-ui/deprecated-attrs.stderr

@@ -1,11 +1,42 @@
-warning: the `#![doc(no_default_passes)]` attribute is considered deprecated
+warning: the `passes` flag is deprecated
    |
-   = warning: see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information
+   = note: see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information
+
+warning: ignoring unknown pass `unknown-pass`
+
+warning: the `#![doc(no_default_passes)]` attribute is deprecated
+  --> $DIR/deprecated-attrs.rs:5:8
+   |
+LL | #![doc(no_default_passes)]
+   |        ^^^^^^^^^^^^^^^^^
+   |
+   = note: see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information
    = help: you may want to use `#![doc(document_private_items)]`
 
-warning: the `#![doc(passes = "...")]` attribute is considered deprecated
+warning: the `#![doc(passes = "...")]` attribute is deprecated
+  --> $DIR/deprecated-attrs.rs:9:8
+   |
+LL | #![doc(passes = "collapse-docs unindent-comments")]
+   |        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = note: see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information
+
+warning: ignoring unknown pass `collapse-docs`
+  --> $DIR/deprecated-attrs.rs:9:17
+   |
+LL | #![doc(passes = "collapse-docs unindent-comments")]
+   |                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = note: the `collapse-docs` pass was removed in #80261 <https://github.com/rust-lang/rust/pull/80261>
+
+warning: the `#![doc(plugins = "...")]` attribute is deprecated
+  --> $DIR/deprecated-attrs.rs:14:8
+   |
+LL | #![doc(plugins = "xxx")]
+   |        ^^^^^^^^^^^^^^^
    |
-   = warning: see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information
+   = note: see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information
+   = warning: `#![doc(plugins = "...")]` no longer functions; see CVE-2018-1000622 <https://nvd.nist.gov/vuln/detail/CVE-2018-1000622>
 
-warning: 2 warnings emitted
+warning: 5 warnings emitted