From fa4e3aac198d14dbc5c66877af1127501fd87616 Mon Sep 17 00:00:00 2001
From: y21 <30553356+y21@users.noreply.github.com>
Date: Sat, 9 Mar 2024 00:50:46 +0100
Subject: [PATCH] add documentation to the `span_lint_hir` functions

---
 clippy.toml                     |  4 ++--
 clippy_utils/src/diagnostics.rs | 38 +++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/clippy.toml b/clippy.toml
index 8c405ac6a4e..3a68fa1670d 100644
--- a/clippy.toml
+++ b/clippy.toml
@@ -1,7 +1,7 @@
 avoid-breaking-exported-api = false
 
-# use the various `span_lint_*` methods instead, which also add a link to the docs
+# use the various `clippy_utils::diagnostics::span_lint_*` functions instead, which also add a link to the docs
 disallowed-methods = [
     "rustc_lint::context::LintContext::span_lint",
-    "rustc_middle::ty::context::TyCtxt::node_span_lint"
+    "rustc_middle::ty::context::TyCtxt::node_span_lint",
 ]
diff --git a/clippy_utils/src/diagnostics.rs b/clippy_utils/src/diagnostics.rs
index 6ed46e5dde0..303b23ba3a0 100644
--- a/clippy_utils/src/diagnostics.rs
+++ b/clippy_utils/src/diagnostics.rs
@@ -152,6 +152,25 @@ where
     });
 }
 
+/// Like [`span_lint`], but allows providing the `HirId` of the node that caused us to emit this
+/// lint.
+///
+/// The `HirId` is used for checking lint level attributes.
+///
+/// For example:
+/// ```ignore
+/// fn f() { /* '1 */
+///
+///     #[allow(clippy::some_lint)]
+///     let _x = /* '2 */;
+/// }
+/// ```
+/// If `some_lint` does its analysis in `LintPass::check_fn` (at `'1`) and emits a lint at `'2`
+/// using [`span_lint`], then allowing the lint at `'2` as attempted in the snippet will not work!
+/// Even though that is where the warning points at, which would be confusing to users.
+///
+/// Instead, use this function and also pass the `HirId` of the node at `'2`, which will let the
+/// compiler check lint level attributes at `'2` as one would expect, and the `#[allow]` will work.
 pub fn span_lint_hir(cx: &LateContext<'_>, lint: &'static Lint, hir_id: HirId, sp: Span, msg: &str) {
     #[expect(clippy::disallowed_methods)]
     cx.tcx.node_span_lint(lint, hir_id, sp, msg.to_string(), |diag| {
@@ -159,6 +178,25 @@ pub fn span_lint_hir(cx: &LateContext<'_>, lint: &'static Lint, hir_id: HirId, s
     });
 }
 
+/// Like [`span_lint_and_then`], but allows providing the `HirId` of the node that caused us to emit
+/// this lint.
+///
+/// The `HirId` is used for checking lint level attributes.
+///
+/// For example:
+/// ```ignore
+/// fn f() { /* '1 */
+///
+///     #[allow(clippy::some_lint)]
+///     let _x = /* '2 */;
+/// }
+/// ```
+/// If `some_lint` does its analysis in `LintPass::check_fn` (at `'1`) and emits a lint at `'2`
+/// using [`span_lint_and_then`], then allowing the lint at `'2` as attempted in the snippet will
+/// not work! Even though that is where the warning points at, which would be confusing to users.
+///
+/// Instead, use this function and also pass the `HirId` of the node at `'2`, which will let the
+/// compiler check lint level attributes at `'2` as one would expect, and the `#[allow]` will work.
 pub fn span_lint_hir_and_then(
     cx: &LateContext<'_>,
     lint: &'static Lint,