Some rustc_lint_diagnostic cleanups.

This commit:
- Expands and corrects some comments.
- Does some minor formatting improvements.
- Adds missing `DecorateLint` cases to
  `tests/ui-fulldeps/internal-lints/diagnostics.rs`.

Author: nnethercote

compiler/rustc_feature/src/builtin_attrs.rs

@@ -625,7 +625,8 @@ pub const BUILTIN_ATTRIBUTES: &[BuiltinAttribute] = &[
     // might not be stable during incremental compilation.
     rustc_attr!(rustc_lint_query_instability, Normal, template!(Word), WarnFollowing, INTERNAL_UNSTABLE),
     // Used by the `rustc::untranslatable_diagnostic` and `rustc::diagnostic_outside_of_impl` lints
-    // to assist in changes to diagnostic APIs.
+    // to assist in changes to diagnostic APIs. Any function with this attribute will be checked by
+    // those lints.
     rustc_attr!(rustc_lint_diagnostics, Normal, template!(Word), WarnFollowing, INTERNAL_UNSTABLE),
     // Used by the `rustc::bad_opt_access` lint to identify `DebuggingOptions` and `CodegenOptions`
     // types (as well as any others in future).

compiler/rustc_lint/src/internal.rs

@@ -339,22 +339,25 @@ impl<'tcx> LateLintPass<'tcx> for ExistingDocKeyword {
 }
 
 declare_tool_lint! {
-    /// The `untranslatable_diagnostic` lint detects diagnostics created
-    /// without using translatable Fluent strings.
+    /// The `untranslatable_diagnostic` lint detects messages passed to functions annotated with
+    /// `#[rustc_lint_diagnostics]` without using translatable Fluent strings.
     ///
-    /// More details on translatable diagnostics can be found [here](https://rustc-dev-guide.rust-lang.org/diagnostics/translation.html).
+    /// More details on translatable diagnostics can be found
+    /// [here](https://rustc-dev-guide.rust-lang.org/diagnostics/translation.html).
     pub rustc::UNTRANSLATABLE_DIAGNOSTIC,
     Deny,
     "prevent creation of diagnostics which cannot be translated",
     report_in_external_macro: true
 }
 
 declare_tool_lint! {
-    /// The `diagnostic_outside_of_impl` lint detects diagnostics created manually,
-    /// and inside an `IntoDiagnostic`/`AddToDiagnostic` implementation,
-    /// or a `#[derive(Diagnostic)]`/`#[derive(Subdiagnostic)]` expansion.
+    /// The `diagnostic_outside_of_impl` lint detects calls to functions annotated with
+    /// `#[rustc_lint_diagnostics]` that are outside a `IntoDiagnostic`, `AddToDiagnostic`, or
+    /// `DecorateLint` impl, or a `#[derive(Diagnostic)]`, `#[derive(Subdiagnostic)]`,
+    /// `#[derive(DecorateLint)]` expansion.
     ///
-    /// More details on diagnostics implementations can be found [here](https://rustc-dev-guide.rust-lang.org/diagnostics/diagnostic-structs.html).
+    /// More details on diagnostics implementations can be found
+    /// [here](https://rustc-dev-guide.rust-lang.org/diagnostics/diagnostic-structs.html).
     pub rustc::DIAGNOSTIC_OUTSIDE_OF_IMPL,
     Deny,
     "prevent creation of diagnostics outside of `IntoDiagnostic`/`AddToDiagnostic` impls",
@@ -369,10 +372,15 @@ declare_tool_lint! {
     report_in_external_macro: true
 }
 
-declare_lint_pass!(Diagnostics => [ UNTRANSLATABLE_DIAGNOSTIC, DIAGNOSTIC_OUTSIDE_OF_IMPL, UNTRANSLATABLE_DIAGNOSTIC_TRIVIAL ]);
+declare_lint_pass!(Diagnostics => [
+    UNTRANSLATABLE_DIAGNOSTIC,
+    DIAGNOSTIC_OUTSIDE_OF_IMPL,
+    UNTRANSLATABLE_DIAGNOSTIC_TRIVIAL
+]);
 
 impl LateLintPass<'_> for Diagnostics {
     fn check_expr(&mut self, cx: &LateContext<'_>, expr: &Expr<'_>) {
+        // Return early if it's not a call to a function marked with `#[rustc_lint_diagnostics]`.
         let Some((span, def_id, args)) = typeck_results_of_method_fn(cx, expr) else { return };
         debug!(?span, ?def_id, ?args);
         let has_attr = ty::Instance::resolve(cx.tcx, cx.param_env, def_id, args)
@@ -383,12 +391,19 @@ impl LateLintPass<'_> for Diagnostics {
             return;
         }
 
+        // Calls to `#[rustc_lint_diagnostics]`-marked functions should only occur:
+        // - inside an impl of `IntoDiagnostic`, `AddToDiagnostic`, or `DecorateLint`, or
+        // - inside a function that is itself marked with `#[rustc_lint_diagnostics]`.
+        //
+        // Otherwise, emit a `DIAGNOSTIC_OUTSIDE_OF_IMPL` lint.
         let mut found_parent_with_attr = false;
         let mut found_impl = false;
         for (hir_id, parent) in cx.tcx.hir().parent_iter(expr.hir_id) {
-            if let Some(owner_did) = hir_id.as_owner() {
-                found_parent_with_attr = found_parent_with_attr
-                    || cx.tcx.has_attr(owner_did, sym::rustc_lint_diagnostics);
+            if let Some(owner_did) = hir_id.as_owner()
+                && cx.tcx.has_attr(owner_did, sym::rustc_lint_diagnostics)
+            {
+                found_parent_with_attr = true;
+                break;
             }
 
             debug!(?parent);
@@ -407,6 +422,10 @@ impl LateLintPass<'_> for Diagnostics {
             cx.emit_span_lint(DIAGNOSTIC_OUTSIDE_OF_IMPL, span, DiagOutOfImpl);
         }
 
+        // Calls to `#[rustc_lint_diagnostics]`-marked functions should only be passed
+        // `DiagnosticMessage` or `SubdiagnosticMessage` arguments, unless they are inside a
+        // function that is itself marked with `#[rustc_lint_diagnostics]`. Otherwise, emit an
+        // `UNTRANSLATABLE_DIAGNOSTIC` lint.
         let mut found_diagnostic_message = false;
         for ty in args.types() {
             debug!(?ty);
@@ -506,7 +525,7 @@ declare_tool_lint! {
     report_in_external_macro: true
 }
 
-declare_lint_pass!(BadOptAccess => [ BAD_OPT_ACCESS ]);
+declare_lint_pass!(BadOptAccess => [BAD_OPT_ACCESS]);
 
 impl LateLintPass<'_> for BadOptAccess {
     fn check_expr(&mut self, cx: &LateContext<'_>, expr: &Expr<'_>) {

tests/ui-fulldeps/internal-lints/diagnostics.rs

@@ -13,8 +13,8 @@ extern crate rustc_session;
 extern crate rustc_span;
 
 use rustc_errors::{
-    AddToDiagnostic, Diagnostic, DiagnosticBuilder, DiagnosticMessage, EmissionGuarantee, DiagCtxt,
-    IntoDiagnostic, Level, SubdiagnosticMessageOp,
+    AddToDiagnostic, DecorateLint, Diagnostic, DiagnosticBuilder, DiagnosticMessage,
+    EmissionGuarantee, DiagCtxt, IntoDiagnostic, Level, SubdiagnosticMessageOp,
 };
 use rustc_macros::{Diagnostic, Subdiagnostic};
 use rustc_span::Span;
@@ -77,6 +77,31 @@ impl AddToDiagnostic for TranslatableInAddToDiagnostic {
     }
 }
 
+pub struct UntranslatableInDecorateLint;
+
+impl<'a> DecorateLint<'a, ()> for UntranslatableInDecorateLint {
+    fn decorate_lint<'b, >(self, diag: &'b mut DiagnosticBuilder<'a, ()>) {
+        diag.note("untranslatable diagnostic");
+        //~^ ERROR diagnostics should be created using translatable messages
+    }
+
+    fn msg(&self) -> DiagnosticMessage {
+        unreachable!();
+    }
+}
+
+pub struct TranslatableInDecorateLint;
+
+impl<'a> DecorateLint<'a, ()> for TranslatableInDecorateLint {
+    fn decorate_lint<'b>(self, diag: &'b mut DiagnosticBuilder<'a, ()>) {
+        diag.note(crate::fluent_generated::no_crate_note);
+    }
+
+    fn msg(&self) -> DiagnosticMessage {
+        unreachable!();
+    }
+}
+
 pub fn make_diagnostics<'a>(dcx: &'a DiagCtxt) {
     let _diag = dcx.struct_err(crate::fluent_generated::no_crate_example);
     //~^ ERROR diagnostics should only be created in `IntoDiagnostic`/`AddToDiagnostic` impls

tests/ui-fulldeps/internal-lints/diagnostics.stderr

@@ -16,8 +16,14 @@ error: diagnostics should be created using translatable messages
 LL |         diag.note("untranslatable diagnostic");
    |              ^^^^
 
+error: diagnostics should be created using translatable messages
+  --> $DIR/diagnostics.rs:84:14
+   |
+LL |         diag.note("untranslatable diagnostic");
+   |              ^^^^
+
 error: diagnostics should only be created in `IntoDiagnostic`/`AddToDiagnostic` impls
-  --> $DIR/diagnostics.rs:81:21
+  --> $DIR/diagnostics.rs:106:21
    |
 LL |     let _diag = dcx.struct_err(crate::fluent_generated::no_crate_example);
    |                     ^^^^^^^^^^
@@ -29,16 +35,16 @@ LL | #![deny(rustc::diagnostic_outside_of_impl)]
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 error: diagnostics should only be created in `IntoDiagnostic`/`AddToDiagnostic` impls
-  --> $DIR/diagnostics.rs:84:21
+  --> $DIR/diagnostics.rs:109:21
    |
 LL |     let _diag = dcx.struct_err("untranslatable diagnostic");
    |                     ^^^^^^^^^^
 
 error: diagnostics should be created using translatable messages
-  --> $DIR/diagnostics.rs:84:21
+  --> $DIR/diagnostics.rs:109:21
    |
 LL |     let _diag = dcx.struct_err("untranslatable diagnostic");
    |                     ^^^^^^^^^^
 
-error: aborting due to 5 previous errors
+error: aborting due to 6 previous errors