From 3e71f4dd2306cc8b5f04f55f8e587bc020303573 Mon Sep 17 00:00:00 2001 From: Matt Palmer 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 3025cce7ba7e5..0b21a6889f293 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