From 3e71f4dd2306cc8b5f04f55f8e587bc020303573 Mon Sep 17 00:00:00 2001
From: Matt Palmer <mpalmer@hezmatt.org>
Date: Fri, 12 May 2023 18:18:13 +1000
Subject: [PATCH] Extra context for unreachable_pub lint (fixes #110922)
While experienced Rustaceans no doubt know this sort of thing already, as more of a newbie I had trouble understanding why I was triggering the lint.
Hopefully this expanded explanation saves someone else some head-scratching.
---
compiler/rustc_lint/src/builtin.rs | 12 ++++++++----
1 file changed, 8 insertions(+), 4 deletions(-)
diff --git a/compiler/rustc_lint/src/builtin.rs b/compiler/rustc_lint/src/builtin.rs
index 3025cce7ba7..0b21a6889f2 100644
--- a/compiler/rustc_lint/src/builtin.rs
+++ b/compiler/rustc_lint/src/builtin.rs
@@ -1313,10 +1313,14 @@ declare_lint! {
///
/// ### Explanation
///
- /// A bare `pub` visibility may be misleading if the item is not actually
- /// publicly exported from the crate. The `pub(crate)` visibility is
- /// recommended to be used instead, which more clearly expresses the intent
- /// that the item is only visible within its own crate.
+ /// The `pub` keyword both expresses an intent for an item to be publicly available, and also
+ /// signals to the compiler to make the item publicly accessible. The intent can only be
+ /// satisfied, however, if all items which contain this item are *also* publicly accessible.
+ /// Thus, this lint serves to identify situations where the intent does not match the reality.
+ ///
+ /// If you wish the item to be accessible elsewhere within the crate, but not outside it, the
+ /// `pub(crate)` visibility is recommended to be used instead. This more clearly expresses the
+ /// intent that the item is only visible within its own crate.
///
/// This lint is "allow" by default because it will trigger for a large
/// amount existing Rust code, and has some false-positives. Eventually it