Rollup merge of #50669 - QuietMisdreavus:deprecated-attrs, r=GuillaumeGomez

rustdoc: deprecate `#![doc(passes, plugins, no_default_passes)]`

Closes https://github.com/rust-lang/rust/issues/48164

Blocked on https://github.com/rust-lang/rust/pull/50541 - this includes those changes, which were necessary to create the UI test

cc https://github.com/rust-lang/rust/issues/44136

Turns out, there were special attributes to mess with rustdoc passes and plugins! Who knew! Since we deprecated the CLI flags for this functionality, it makes sense that we do the same for the attributes.

This PR also introduces a `#![doc(document_private_items)]` attribute, to match the `--document-private-items` flag introduced in https://github.com/rust-lang/rust/pull/44138 when the passes/plugins flags were deprecated.

I haven't done a search to see whether these attributes are being used at all, but if the flags were any indication, i don't expect to see any users of these.

src/librustdoc/lib.rs

@@ -654,6 +654,20 @@ where R: 'static + Send,
 
         krate.version = crate_version;
 
+        let diag = core::new_handler(error_format, None);
+
+        fn report_deprecated_attr(name: &str, diag: &errors::Handler) {
+            let mut msg = diag.struct_warn(&format!("the `#![doc({})]` attribute is \
+                                                     considered deprecated", name));
+            msg.warn("please see https://github.com/rust-lang/rust/issues/44136");
+
+            if name == "no_default_passes" {
+                msg.help("you may want to use `#![doc(document_private_items)]`");
+            }
+
+            msg.emit();
+        }
+
         // 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("doc") {
@@ -661,18 +675,34 @@ where R: 'static + Send,
             let name = name.as_ref().map(|s| &s[..]);
             if attr.is_word() {
                 if name == Some("no_default_passes") {
+                    report_deprecated_attr("no_default_passes", &diag);
                     default_passes = false;
                 }
             } else if let Some(value) = attr.value_str() {
                 let sink = match name {
-                    Some("passes") => &mut passes,
-                    Some("plugins") => &mut plugins,
+                    Some("passes") => {
+                        report_deprecated_attr("passes = \"...\"", &diag);
+                        &mut passes
+                    },
+                    Some("plugins") => {
+                        report_deprecated_attr("plugins = \"...\"", &diag);
+                        &mut plugins
+                    },
                     _ => continue,
                 };
                 for p in value.as_str().split_whitespace() {
                     sink.push(p.to_string());
                 }
             }
+
+            if attr.is_word() && name == Some("document_private_items") {
+                default_passes = false;
+
+                passes = vec![
+                    String::from("collapse-docs"),
+                    String::from("unindent-comments"),
+                ];
+            }
         }
 
         if default_passes {

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

@@ -0,0 +1,17 @@
+// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+// compile-pass
+
+#![doc(no_default_passes, passes = "collapse-docs unindent-comments")]
+
+struct SomeStruct;
+
+pub struct OtherStruct;

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

@@ -0,0 +1,9 @@
+warning: the `#![doc(no_default_passes)]` attribute is considered deprecated
+  |
+  = warning: please see https://github.com/rust-lang/rust/issues/44136
+  = help: you may want to use `#![doc(document_private_items)]`
+
+warning: the `#![doc(passes = "...")]` attribute is considered deprecated
+  |
+  = warning: please see https://github.com/rust-lang/rust/issues/44136
+