From 943c3bc3db590b8549f76eee814bef58b68a37f8 Mon Sep 17 00:00:00 2001
From: Michael Howell <michael@notriddle.com>
Date: Sat, 23 Nov 2024 17:10:08 -0700
Subject: [PATCH 1/2] Add note about caveat for `cfg(doc)`

For example, we definitely wouldn't want to do this in libcore.
---
 clippy_lints/src/doc/mod.rs | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/clippy_lints/src/doc/mod.rs b/clippy_lints/src/doc/mod.rs
index fd6ae21a5f85..993335e8248c 100644
--- a/clippy_lints/src/doc/mod.rs
+++ b/clippy_lints/src/doc/mod.rs
@@ -539,11 +539,15 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks if included files in doc comments are included only for `cfg(doc)`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// These files are not useful for compilation but will still be included.
     /// Also, if any of these non-source code file is updated, it will trigger a
     /// recompilation.
     ///
+    /// Excluding this will currently result in the file being left out if
+    /// the item's docs are inlined from another crate. This may be fixed in a
+    /// future version of rustdoc.
+    ///
     /// ### Example
     /// ```ignore
     /// #![doc = include_str!("some_file.md")]
@@ -554,7 +558,7 @@ declare_clippy_lint! {
     /// ```
     #[clippy::version = "1.84.0"]
     pub DOC_INCLUDE_WITHOUT_CFG,
-    pedantic,
+    restriction,
     "check if files included in documentation are behind `cfg(doc)`"
 }
 

From 418dfb2257c3a2c516b648695b92367dde2a9cd3 Mon Sep 17 00:00:00 2001
From: Michael Howell <michael@notriddle.com>
Date: Sun, 24 Nov 2024 11:23:14 -0700
Subject: [PATCH 2/2] Add Known problems section

---
 clippy_lints/src/doc/mod.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/clippy_lints/src/doc/mod.rs b/clippy_lints/src/doc/mod.rs
index 993335e8248c..88ac871acf68 100644
--- a/clippy_lints/src/doc/mod.rs
+++ b/clippy_lints/src/doc/mod.rs
@@ -544,6 +544,8 @@ declare_clippy_lint! {
     /// Also, if any of these non-source code file is updated, it will trigger a
     /// recompilation.
     ///
+    /// ### Known problems
+    ///
     /// Excluding this will currently result in the file being left out if
     /// the item's docs are inlined from another crate. This may be fixed in a
     /// future version of rustdoc.