Add comments about TRACK_DIAGNOSTIC use.

Also add an assertion for the levels allowed with `has_future_breakage`.

Author: nnethercote

compiler/rustc_errors/src/lib.rs

@@ -1304,10 +1304,12 @@ impl DiagCtxtInner {
             // Future breakages aren't emitted if they're Level::Allow,
             // but they still need to be constructed and stashed below,
             // so they'll trigger the must_produce_diag check.
-            self.suppressed_expected_diag = true;
+            assert!(matches!(diagnostic.level, Error | Warning | Allow));
             self.future_breakage_diagnostics.push(diagnostic.clone());
         }
 
+        // We call TRACK_DIAGNOSTIC with an empty closure for the cases that
+        // return early *and* have some kind of side-effect.
         match diagnostic.level {
             Fatal | Error if self.treat_next_err_as_bug() => {
                 // `Fatal` and `Error` can be promoted to `Bug`.
@@ -1331,6 +1333,10 @@ impl DiagCtxtInner {
                     return if let Some(guar) = self.has_errors_or_lint_errors() {
                         Some(guar)
                     } else {
+                        // Is saving the diagnostic in `delayed_bugs` a notable
+                        // side-effect? Should `TRACK_DIAGNOSTIC` be called?
+                        // Unclear. Currently we err on the side of "no" to avoid
+                        // having to clone the diagnostic.
                         let backtrace = std::backtrace::Backtrace::capture();
                         // This `unchecked_error_guaranteed` is valid. It is where the
                         // `ErrorGuaranteed` for delayed bugs originates.
@@ -1344,11 +1350,17 @@ impl DiagCtxtInner {
             }
             Warning if !self.flags.can_emit_warnings => {
                 if diagnostic.has_future_breakage() {
+                    // The side-effect is at the top of this method.
                     TRACK_DIAGNOSTIC(diagnostic, &mut |_| None);
                 }
                 return None;
             }
             Allow => {
+                if diagnostic.has_future_breakage() {
+                    // The side-effect is at the top of this method.
+                    TRACK_DIAGNOSTIC(diagnostic, &mut |_| None);
+                    self.suppressed_expected_diag = true;
+                }
                 return None;
             }
             Expect(expect_id) | ForceWarning(Some(expect_id)) => {
@@ -1357,6 +1369,9 @@ impl DiagCtxtInner {
                 // buffered until the `LintExpectationId` is replaced by a
                 // stable one by the `LintLevelsBuilder`.
                 if let LintExpectationId::Unstable { .. } = expect_id {
+                    // We don't call TRACK_DIAGNOSTIC because we wait for the
+                    // unstable ID to be updated, whereupon the diagnostic will
+                    // be passed into this method again.
                     self.unstable_expect_diagnostics.push(diagnostic);
                     return None;
                 }