Skip to content

Commit

Permalink
Rollup merge of #106287 - Nilstrieb:its-bugging-me-how-we-dont-have-d…
Browse files Browse the repository at this point in the history
…ocs, r=jyn514

Add some docs to `bug`, `span_bug` and `delay_span_bug`

cc `@mejrs` as you wanted me to do this, does this look good and understandable?
  • Loading branch information
matthiaskrgr authored Jan 6, 2023
2 parents afe8c45 + 0047e25 commit 7568c49
Show file tree
Hide file tree
Showing 4 changed files with 34 additions and 3 deletions.
2 changes: 2 additions & 0 deletions compiler/rustc_errors/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -978,6 +978,7 @@ impl Handler {
self.inner.borrow_mut().span_bug(span, msg)
}

/// For documentation on this, see `Session::delay_span_bug`.
#[track_caller]
pub fn delay_span_bug(
&self,
Expand Down Expand Up @@ -1529,6 +1530,7 @@ impl HandlerInner {
self.emit_diagnostic(diag.set_span(sp));
}

/// For documentation on this, see `Session::delay_span_bug`.
#[track_caller]
fn delay_span_bug(
&mut self,
Expand Down
18 changes: 18 additions & 0 deletions compiler/rustc_middle/src/macros.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,13 @@
/// A macro for triggering an ICE.
/// Calling `bug` instead of panicking will result in a nicer error message and should
/// therefore be prefered over `panic`/`unreachable` or others.
///
/// If you have a span available, you should use [`span_bug`] instead.
///
/// If the bug should only be emitted when compilation didn't fail, [`Session::delay_span_bug`] may be useful.
///
/// [`Session::delay_span_bug`]: rustc_session::Session::delay_span_bug
/// [`span_bug`]: crate::span_bug
#[macro_export]
macro_rules! bug {
() => ( $crate::bug!("impossible case reached") );
Expand All @@ -8,6 +18,14 @@ macro_rules! bug {
});
}

/// A macro for triggering an ICE with a span.
/// Calling `span_bug!` instead of panicking will result in a nicer error message and point
/// at the code the compiler was compiling when it ICEd. This is the preferred way to trigger
/// ICEs.
///
/// If the bug should only be emitted when compilation didn't fail, [`Session::delay_span_bug`] may be useful.
///
/// [`Session::delay_span_bug`]: rustc_session::Session::delay_span_bug
#[macro_export]
macro_rules! span_bug {
($span:expr, $msg:expr) => ({ $crate::util::bug::span_bug_fmt($span, ::std::format_args!($msg)) });
Expand Down
3 changes: 1 addition & 2 deletions compiler/rustc_middle/src/util/bug.rs
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,7 @@ fn opt_span_bug_fmt<S: Into<MultiSpan>>(
(Some(tcx), None) => tcx.sess.diagnostic().bug(&msg),
(None, _) => panic_any(msg),
}
});
unreachable!();
})
}

/// A query to trigger a `delay_span_bug`. Clearly, if one has a `tcx` one can already trigger a
Expand Down
14 changes: 13 additions & 1 deletion compiler/rustc_session/src/session.rs
Original file line number Diff line number Diff line change
Expand Up @@ -590,7 +590,19 @@ impl Session {
pub fn warn(&self, msg: impl Into<DiagnosticMessage>) {
self.diagnostic().warn(msg)
}
/// Delay a span_bug() call until abort_if_errors()

/// 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).
///
/// If no span is available, use [`DUMMY_SP`].
///
/// [`DUMMY_SP`]: rustc_span::DUMMY_SP
#[track_caller]
pub fn delay_span_bug<S: Into<MultiSpan>>(
&self,
Expand Down

0 comments on commit 7568c49

Please sign in to comment.