Emit DOC_INCLUDE lint instead of a hard warning

compiler/rustc_lint_defs/src/lib.rs

@@ -448,17 +448,24 @@ macro_rules! declare_tool_lint {
         $(#[$attr:meta])* $vis:vis $tool:ident ::$NAME:ident, $Level: ident, $desc: expr
         $(, @future_incompatible = FutureIncompatibleInfo { $($field:ident : $val:expr),* $(,)*  }; )?
     ) => (
-        $crate::declare_tool_lint!{$(#[$attr])* $vis $tool::$NAME, $Level, $desc, false}
+        $crate::declare_tool_lint!{
+            $(#[$attr])* $vis $tool::$NAME, $Level, $desc, false
+            $(, @future_incompatible = FutureIncompatibleInfo { $($field : $val),* };)?
+        }
     );
     (
         $(#[$attr:meta])* $vis:vis $tool:ident ::$NAME:ident, $Level:ident, $desc:expr,
         report_in_external_macro: $rep:expr
+        $(, @future_incompatible = FutureIncompatibleInfo { $($field:ident : $val:expr),* $(,)*  }; )?
     ) => (
-         $crate::declare_tool_lint!{$(#[$attr])* $vis $tool::$NAME, $Level, $desc, $rep}
+         $crate::declare_tool_lint!{$(#[$attr])* $vis $tool::$NAME, $Level, $desc, $rep
+         $(, @future_incompatible = FutureIncompatibleInfo { $($field:ident : $val:expr),* $(,)*  }; )?
+         }
     );
     (
         $(#[$attr:meta])* $vis:vis $tool:ident ::$NAME:ident, $Level:ident, $desc:expr,
         $external:expr
+         $(, @future_incompatible = FutureIncompatibleInfo { $($field:ident : $val:expr),* $(,)*  }; )?
     ) => (
         $(#[$attr])*
         $vis static $NAME: &$crate::Lint = &$crate::Lint {
@@ -467,10 +474,14 @@ macro_rules! declare_tool_lint {
             desc: $desc,
             edition_lint_opts: None,
             report_in_external_macro: $external,
-            future_incompatible: None,
+            $(future_incompatible: Some($crate::FutureIncompatibleInfo {
+                $($field: $val,)*
+                ..$crate::FutureIncompatibleInfo::default_fields_for_macro()
+            }),)?
             is_plugin: true,
             feature_gate: None,
             crate_level_only: false,
+            ..$crate::Lint::default_fields_for_macro()
         };
     );
 }

src/doc/rustdoc/src/lints.md

@@ -340,6 +340,22 @@ error in a future release.
 
 ```rust
 #![feature(external_doc)]
-#[doc(include = "README.md")]
-pub fn foo() {}
+#![doc(include = "./external-doc.rs")]
+```
+
+Which will give:
+
+```text
+warning: `#[doc(include)]` is deprecated and will be removed in a future release
+ --> external-doc.rs:2:1
+  |
+2 | #![doc(include = "./external-doc.rs")]
+  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  |
+  = note: `#[warn(rustdoc::doc_include)]` on by default
+  = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
+  = note: for more information, see issue #44732 <https://github.com/rust-lang/rust/issues/44732>
+help: use `#![feature(extended_key_value_attributes)]` instead
+  |
+2 | #![doc = include_str!("./external-doc.rs")]
 ```

src/librustdoc/clean/inline.rs

@@ -7,7 +7,7 @@ use rustc_data_structures::fx::FxHashSet;
 use rustc_hir as hir;
 use rustc_hir::def::{DefKind, Res};
 use rustc_hir::def_id::{DefId, CRATE_DEF_INDEX};
-use rustc_hir::Mutability;
+use rustc_hir::{HirId, Mutability};
 use rustc_metadata::creader::LoadedMacro;
 use rustc_middle::ty::{self, TyCtxt};
 use rustc_mir::const_eval::is_min_const_fn;
@@ -122,7 +122,8 @@ crate fn try_inline(
     };
 
     let target_attrs = load_attrs(cx, did);
-    let attrs = box merge_attrs(cx, Some(parent_module), target_attrs, attrs_clone, did.is_local());
+    let local_item = DocContext::as_local_hir_id(cx.tcx, did);
+    let attrs = box merge_attrs(cx, Some(parent_module), target_attrs, attrs_clone, local_item);
 
     cx.inlined.insert(did);
     let what_rustc_thinks = clean::Item::from_def_id_and_parts(did, Some(name), kind, cx);
@@ -290,22 +291,22 @@ fn merge_attrs(
     parent_module: Option<DefId>,
     old_attrs: Attrs<'_>,
     new_attrs: Option<Attrs<'_>>,
-    local: bool,
+    item: Option<HirId>,
 ) -> clean::Attributes {
     // NOTE: If we have additional attributes (from a re-export),
     // always insert them first. This ensure that re-export
     // doc comments show up before the original doc comments
     // when we render them.
     if let Some(inner) = new_attrs {
         if let Some(new_id) = parent_module {
-            Attributes::from_ast(cx.tcx, old_attrs, Some((inner, new_id)), local)
+            Attributes::from_ast(cx.tcx, old_attrs, Some((inner, new_id)), item)
         } else {
             let mut both = inner.to_vec();
             both.extend_from_slice(old_attrs);
-            clean_attrs(&both, local, cx)
+            clean_attrs(&both, item, cx)
         }
     } else {
-        clean_attrs(old_attrs, local, cx)
+        clean_attrs(old_attrs, item, cx)
     }
 }
 
@@ -416,8 +417,8 @@ crate fn build_impl(
 
     debug!("build_impl: impl {:?} for {:?}", trait_.def_id(), for_.def_id());
 
-    let attrs =
-        box merge_attrs(cx, parent_module.into(), load_attrs(cx, did), attrs, did.is_local());
+    let local_item = DocContext::as_local_hir_id(tcx, did);
+    let attrs = box merge_attrs(cx, parent_module.into(), load_attrs(cx, did), attrs, local_item);
     debug!("merged_attrs={:?}", attrs);
 
     ret.push(clean::Item::from_def_id_and_attrs_and_parts(

src/librustdoc/clean/mod.rs

@@ -15,6 +15,7 @@ use rustc_data_structures::fx::{FxHashMap, FxHashSet};
 use rustc_hir as hir;
 use rustc_hir::def::{CtorKind, DefKind, Res};
 use rustc_hir::def_id::{CrateNum, DefId, CRATE_DEF_INDEX, LOCAL_CRATE};
+use rustc_hir::HirId;
 use rustc_index::vec::{Idx, IndexVec};
 use rustc_infer::infer::region_constraints::{Constraint, RegionConstraintData};
 use rustc_middle::bug;
@@ -110,7 +111,7 @@ impl Clean<ExternalCrate> for CrateNum {
             if let Res::Def(DefKind::Mod, def_id) = res {
                 // We already warned about any attributes on the module when cleaning it.
                 // Don't warn a second time.
-                let attrs = clean_attrs(cx.tcx.get_attrs(def_id), false, cx);
+                let attrs = clean_attrs(cx.tcx.get_attrs(def_id), None, cx);
                 let mut prim = None;
                 for attr in attrs.lists(sym::doc) {
                     if let Some(v) = attr.value_str() {
@@ -157,7 +158,7 @@ impl Clean<ExternalCrate> for CrateNum {
 
         let mut as_keyword = |res: Res| {
             if let Res::Def(DefKind::Mod, def_id) = res {
-                let attrs = clean_attrs(tcx.get_attrs(def_id), false, cx);
+                let attrs = clean_attrs(tcx.get_attrs(def_id), None, cx);
                 let mut keyword = None;
                 for attr in attrs.lists(sym::doc) {
                     if attr.has_name(sym::keyword) {
@@ -200,7 +201,7 @@ impl Clean<ExternalCrate> for CrateNum {
             name: tcx.crate_name(*self),
             src: krate_src,
             // The local crate was already cleaned, and all other crates are non-local.
-            attrs: clean_attrs(tcx.get_attrs(root), false, cx),
+            attrs: clean_attrs(tcx.get_attrs(root), None, cx),
             primitives,
             keywords,
         }
@@ -240,7 +241,11 @@ impl Clean<Item> for doctree::Module<'_> {
     }
 }
 
-fn clean_attrs(attrs: &[ast::Attribute], local: bool, cx: &mut DocContext<'_>) -> Attributes {
+fn clean_attrs(
+    attrs: &[ast::Attribute],
+    local: Option<HirId>,
+    cx: &mut DocContext<'_>,
+) -> Attributes {
     Attributes::from_ast(cx.tcx, attrs, None, local)
 }
 
@@ -2125,7 +2130,7 @@ fn clean_extern_crate(
     // FIXME: using `from_def_id_and_kind` breaks `rustdoc/masked` for some reason
     vec![Item {
         name: Some(name),
-        attrs: box clean_attrs(attrs, true, cx),
+        attrs: box clean_attrs(attrs, Some(krate.hir_id()), cx),
         span: krate.span.clean(cx),
         def_id: crate_def_id,
         visibility: krate.vis.clean(cx),

src/librustdoc/clean/types.rs

@@ -21,6 +21,7 @@ use rustc_hir as hir;
 use rustc_hir::def::{CtorKind, Res};
 use rustc_hir::def_id::{CrateNum, DefId, DefIndex};
 use rustc_hir::lang_items::LangItem;
+use rustc_hir::HirId;
 use rustc_hir::{BodyId, Mutability};
 use rustc_index::vec::IndexVec;
 use rustc_middle::ty::{self, TyCtxt};
@@ -150,11 +151,12 @@ impl Item {
         kind: ItemKind,
         cx: &mut DocContext<'_>,
     ) -> Item {
+        let local_item = DocContext::as_local_hir_id(cx.tcx, def_id);
         Self::from_def_id_and_attrs_and_parts(
             def_id,
             name,
             kind,
-            box clean_attrs(cx.tcx.get_attrs(def_id), def_id.is_local(), cx),
+            box clean_attrs(cx.tcx.get_attrs(def_id), local_item, cx),
             cx,
         )
     }
@@ -742,7 +744,7 @@ impl Attributes {
         tcx: TyCtxt<'_>,
         attrs: &[ast::Attribute],
         additional_attrs: Option<(&[ast::Attribute], DefId)>,
-        local: bool,
+        item: Option<HirId>,
     ) -> Attributes {
         let mut doc_strings: Vec<DocFragment> = vec![];
         let mut sp = None;
@@ -805,20 +807,21 @@ impl Attributes {
                             }
                         } else if let Some((filename, contents)) = Attributes::extract_include(&mi)
                         {
-                            if local {
-                                let mut diag = handler
-                                    .struct_span_warn(attr.span, "`doc(include)` is deprecated");
-                                diag.span_suggestion_verbose(
-                                    attr.span,
-                                    "use `#![feature(extended_key_value_attributes)]` instead",
-                                    format!(
-                                        "#{}[doc = include_str!(\"{}\")]",
-                                        if attr.style == AttrStyle::Inner { "!" } else { "" },
-                                        filename,
-                                    ),
-                                    Applicability::MaybeIncorrect,
-                                );
-                                diag.emit();
+                            if let Some(hir_id) = item {
+                                tcx.struct_span_lint_hir(crate::lint::DOC_INCLUDE, hir_id, attr.span, |lint_builder| {
+                                    let mut diag = lint_builder.build("`#[doc(include)]` is deprecated and will be removed in a future release");
+                                    diag.span_suggestion_verbose(
+                                        attr.span,
+                                        "use `#![feature(extended_key_value_attributes)]` instead",
+                                        format!(
+                                            "#{}[doc = include_str!(\"{}\")]",
+                                            if attr.style == AttrStyle::Inner { "!" } else { "" },
+                                            filename,
+                                        ),
+                                        Applicability::MaybeIncorrect,
+                                    );
+                                    diag.emit();
+                                });
                             }
 
                             let line = doc_line;

src/librustdoc/doctest.rs

@@ -1093,7 +1093,7 @@ impl<'a, 'hir, 'tcx> HirCollector<'a, 'hir, 'tcx> {
         nested: F,
     ) {
         let attrs = self.tcx.hir().attrs(hir_id);
-        let mut attrs = Attributes::from_ast(self.tcx, attrs, None, true);
+        let mut attrs = Attributes::from_ast(self.tcx, attrs, None, Some(hir_id));
         if let Some(ref cfg) = attrs.cfg {
             if !cfg.matches(&self.sess.parse_sess, Some(&self.sess.features_untracked())) {
                 return;

src/test/rustdoc-ui/doc-include-deprecated.rs

@@ -1,14 +1,20 @@
 // aux-build:doc-include-deprecated.rs
 // check-pass
 #![feature(external_doc)]
-#![doc(include = "auxiliary/docs.md")] //~ WARNING deprecated
+#![doc(include = "auxiliary/docs.md")]
+//~^ WARNING deprecated
+//~| WARNING hard error in a future release
 
 extern crate inner;
 
 pub use inner::HasDocInclude;
 
-#[doc(include = "auxiliary/docs.md")] //~ WARNING deprecated
+#[doc(include = "auxiliary/docs.md")]
+//~^ WARNING deprecated
+//~| WARNING hard error in a future release
 pub use inner::HasDocInclude as _;
 
-#[doc(include = "auxiliary/docs.md")] //~ WARNING deprecated
+#[doc(include = "auxiliary/docs.md")]
+//~^ WARNING deprecated
+//~| WARNING hard error in a future release
 pub use inner::NoDocs;

src/test/rustdoc-ui/doc-include-deprecated.stderr

@@ -1,35 +1,42 @@
-warning: `doc(include)` is deprecated
-  --> $DIR/doc-include-deprecated.rs:10:1
+warning: `#[doc(include)]` is deprecated and will be removed in a future release
+  --> $DIR/doc-include-deprecated.rs:12:1
    |
 LL | #[doc(include = "auxiliary/docs.md")]
    | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |
+   = note: `#[warn(rustdoc::doc_include)]` on by default
+   = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
+   = note: for more information, see issue #44732 <https://github.com/rust-lang/rust/issues/44732>
 help: use `#![feature(extended_key_value_attributes)]` instead
    |
 LL | #[doc = include_str!("auxiliary/docs.md")]
-   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
 
-warning: `doc(include)` is deprecated
-  --> $DIR/doc-include-deprecated.rs:13:1
+warning: `#[doc(include)]` is deprecated and will be removed in a future release
+  --> $DIR/doc-include-deprecated.rs:17:1
    |
 LL | #[doc(include = "auxiliary/docs.md")]
    | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |
+   = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
+   = note: for more information, see issue #44732 <https://github.com/rust-lang/rust/issues/44732>
 help: use `#![feature(extended_key_value_attributes)]` instead
    |
 LL | #[doc = include_str!("auxiliary/docs.md")]
-   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
 
-warning: `doc(include)` is deprecated
+warning: `#[doc(include)]` is deprecated and will be removed in a future release
   --> $DIR/doc-include-deprecated.rs:4:1
    |
 LL | #![doc(include = "auxiliary/docs.md")]
    | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |
+   = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
+   = note: for more information, see issue #44732 <https://github.com/rust-lang/rust/issues/44732>
 help: use `#![feature(extended_key_value_attributes)]` instead
    |
 LL | #![doc = include_str!("auxiliary/docs.md")]
-   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
 
 warning: 3 warnings emitted