From d1920a70c03bb6af2ab3f6dfcc21bfdc1fb3d3e9 Mon Sep 17 00:00:00 2001 From: Nicholas Nethercote Date: Thu, 8 Feb 2024 16:09:30 +1100 Subject: [PATCH] Fix inconsistencies in the diagnostic API methods. - Remove low-value comments about functionality that is obvious. - Add missing `track_caller` attributes -- every method should have one. - Adjust `rustc_lint_diagnostic` attributes. Every method involving a `impl Into` or `impl Into` argument should have one, except for those producing bugs, which aren't user-facing. --- compiler/rustc_errors/src/lib.rs | 53 +++++++++++++------------------- 1 file changed, 21 insertions(+), 32 deletions(-) diff --git a/compiler/rustc_errors/src/lib.rs b/compiler/rustc_errors/src/lib.rs index 0c982f290d2e9..37901bd02b4f8 100644 --- a/compiler/rustc_errors/src/lib.rs +++ b/compiler/rustc_errors/src/lib.rs @@ -930,20 +930,19 @@ impl DiagCtxt { // Functions beginning with `struct_`/`create_` create a diagnostic. Other // functions create and emit a diagnostic all in one go. impl DiagCtxt { - /// Construct a builder at the `Bug` level with the `msg`. - #[rustc_lint_diagnostics] + // No `#[rustc_lint_diagnostics]` because bug messages aren't user-facing. #[track_caller] pub fn struct_bug(&self, msg: impl Into) -> DiagnosticBuilder<'_, BugAbort> { DiagnosticBuilder::new(self, Bug, msg) } - #[rustc_lint_diagnostics] + // No `#[rustc_lint_diagnostics]` because bug messages aren't user-facing. + #[track_caller] pub fn bug(&self, msg: impl Into) -> ! { self.struct_bug(msg).emit() } - /// Construct a builder at the `Bug` level at the given `span` with the `msg`. - #[rustc_lint_diagnostics] + // No `#[rustc_lint_diagnostics]` because bug messages aren't user-facing. #[track_caller] pub fn struct_span_bug( &self, @@ -953,6 +952,8 @@ impl DiagCtxt { self.struct_bug(msg).with_span(span) } + // No `#[rustc_lint_diagnostics]` because bug messages aren't user-facing. + #[track_caller] pub fn span_bug(&self, span: impl Into, msg: impl Into) -> ! { self.struct_span_bug(span, msg).emit() } @@ -966,11 +967,10 @@ impl DiagCtxt { } #[track_caller] - pub fn emit_bug<'a>(&'a self, bug: impl IntoDiagnostic<'a, diagnostic_builder::BugAbort>) -> ! { + pub fn emit_bug<'a>(&'a self, bug: impl IntoDiagnostic<'a, BugAbort>) -> ! { self.create_bug(bug).emit() } - /// Construct a builder at the `Fatal` level with the `msg`. #[rustc_lint_diagnostics] #[track_caller] pub fn struct_fatal( @@ -981,11 +981,11 @@ impl DiagCtxt { } #[rustc_lint_diagnostics] + #[track_caller] pub fn fatal(&self, msg: impl Into) -> ! { self.struct_fatal(msg).emit() } - /// Construct a builder at the `Fatal` level at the given `span` and with the `msg`. #[rustc_lint_diagnostics] #[track_caller] pub fn struct_span_fatal( @@ -1031,7 +1031,6 @@ impl DiagCtxt { self.create_almost_fatal(fatal).emit() } - /// Construct a builder at the `Error` level with the `msg`. // FIXME: This method should be removed (every error should have an associated error code). #[rustc_lint_diagnostics] #[track_caller] @@ -1040,11 +1039,11 @@ impl DiagCtxt { } #[rustc_lint_diagnostics] + #[track_caller] pub fn err(&self, msg: impl Into) -> ErrorGuaranteed { self.struct_err(msg).emit() } - /// Construct a builder at the `Error` level at the given `span` and with the `msg`. #[rustc_lint_diagnostics] #[track_caller] pub fn struct_span_err( @@ -1075,24 +1074,18 @@ impl DiagCtxt { self.create_err(err).emit() } - /// Ensures that compilation cannot succeed. - /// - /// If this function has been called but no errors have been emitted and - /// compilation succeeds, it will cause an internal compiler error (ICE). - /// - /// This can be used in code paths that should never run on successful compilations. - /// For example, it can be used to create an [`ErrorGuaranteed`] - /// (but you should prefer threading through the [`ErrorGuaranteed`] from an error emission - /// directly). + /// Ensures that an error is printed. See `Level::DelayedBug`. + // No `#[rustc_lint_diagnostics]` because bug messages aren't user-facing. #[track_caller] pub fn delayed_bug(&self, msg: impl Into) -> ErrorGuaranteed { DiagnosticBuilder::::new(self, DelayedBug, msg).emit() } - /// Like `delayed_bug`, but takes an additional span. + /// Ensures that an error is printed. See `Level::DelayedBug`. /// /// Note: this function used to be called `delay_span_bug`. It was renamed /// to match similar functions like `span_err`, `span_warn`, etc. + // No `#[rustc_lint_diagnostics]` because bug messages aren't user-facing. #[track_caller] pub fn span_delayed_bug( &self, @@ -1103,13 +1096,12 @@ impl DiagCtxt { } /// Ensures that a diagnostic is printed. See `Level::GoodPathDelayedBug`. + // No `#[rustc_lint_diagnostics]` because bug messages aren't user-facing. + #[track_caller] pub fn good_path_delayed_bug(&self, msg: impl Into) { DiagnosticBuilder::<()>::new(self, GoodPathDelayedBug, msg).emit() } - /// Construct a builder at the `Warning` level with the `msg`. - /// - /// An `emit` call on the builder will only emit if `can_emit_warnings` is `true`. #[rustc_lint_diagnostics] #[track_caller] pub fn struct_warn(&self, msg: impl Into) -> DiagnosticBuilder<'_, ()> { @@ -1117,13 +1109,11 @@ impl DiagCtxt { } #[rustc_lint_diagnostics] + #[track_caller] pub fn warn(&self, msg: impl Into) { self.struct_warn(msg).emit() } - /// Construct a builder at the `Warning` level at the given `span` and with the `msg`. - /// - /// An `emit` call on the builder will only emit if `can_emit_warnings` is `true`. #[rustc_lint_diagnostics] #[track_caller] pub fn struct_span_warn( @@ -1153,7 +1143,6 @@ impl DiagCtxt { self.create_warn(warning).emit() } - /// Construct a builder at the `Note` level with the `msg`. #[rustc_lint_diagnostics] #[track_caller] pub fn struct_note(&self, msg: impl Into) -> DiagnosticBuilder<'_, ()> { @@ -1161,12 +1150,13 @@ impl DiagCtxt { } #[rustc_lint_diagnostics] + #[track_caller] pub fn note(&self, msg: impl Into) { self.struct_note(msg).emit() } - #[track_caller] #[rustc_lint_diagnostics] + #[track_caller] pub fn struct_span_note( &self, span: impl Into, @@ -1175,8 +1165,8 @@ impl DiagCtxt { DiagnosticBuilder::new(self, Note, msg).with_span(span) } - #[track_caller] #[rustc_lint_diagnostics] + #[track_caller] pub fn span_note(&self, span: impl Into, msg: impl Into) { self.struct_span_note(span, msg).emit() } @@ -1194,20 +1184,18 @@ impl DiagCtxt { self.create_note(note).emit() } - /// Construct a builder at the `Help` level with the `msg`. #[rustc_lint_diagnostics] + #[track_caller] pub fn struct_help(&self, msg: impl Into) -> DiagnosticBuilder<'_, ()> { DiagnosticBuilder::new(self, Help, msg) } - /// Construct a builder at the `Allow` level with the `msg`. #[rustc_lint_diagnostics] #[track_caller] pub fn struct_allow(&self, msg: impl Into) -> DiagnosticBuilder<'_, ()> { DiagnosticBuilder::new(self, Allow, msg) } - /// Construct a builder at the `Expect` level with the `msg`. #[rustc_lint_diagnostics] #[track_caller] pub fn struct_expect( @@ -1576,6 +1564,7 @@ pub enum Level { ForceWarning(Option), /// A warning about the code being compiled. Does not prevent compilation from finishing. + /// Will be skipped if `can_emit_warnings` is false. Warning, /// A message giving additional context.