Add a page on force-warns in unstable book

2 files changed, 22 insertions, 1 deletions

diff --git a/compiler/rustc_middle/src/lint.rs b/compiler/rustc_middle/src/lint.rs
index 85080354e4d..4c7ea937ceb 100644
--- a/compiler/rustc_middle/src/lint.rs
+++ b/compiler/rustc_middle/src/lint.rs
@@ -365,7 +365,7 @@ pub fn struct_lint_level<'s, 'd>(
                 sess.diag_note_once(
                     &mut err,
                     DiagnosticMessageId::from(lint),
-                    "Warning forced by `force-warns` commandline option",
+                    "warning forced by `force-warns` commandline option",
                 );
             }
         }
diff --git a/src/doc/unstable-book/src/compiler-flags/force-warns.md b/src/doc/unstable-book/src/compiler-flags/force-warns.md
new file mode 100644
index 00000000000..0028c25beb4
--- /dev/null
+++ b/src/doc/unstable-book/src/compiler-flags/force-warns.md
@@ -0,0 +1,21 @@
+# `force-warns`
+
+The tracking issue for this feature is: [#85512](https://github.com/rust-lang/rust/issues/85512).
+
+------------------------
+
+This feature allows you to cause any lint to produce a warning even if the lint has a different level by default or another level is set somewhere else. For instance, the `force-warns` option can be used to make a lint (e.g., `dead_code`) produce a warning even if that lint is allowed in code with `#![allow(dead_code)]`.
+
+## Example
+
+```rust,ignore (partial-example)
+#![allow(dead_code)]
+
+fn dead_function() {}
+// This would normally not produce a warning even though the 
+// function is not used, because dead code is being allowed
+
+fn main() {}
+```
+
+We can force a warning to be produced by providing `--force-warns dead_code` to rustc.