Skip to content

Commit 3f06bf9

Browse files
Rollup merge of #35072 - munyari:assert_debug, r=steveklabnik
Update docs for assert! and debug_assert! Refer to #34455
2 parents 01505a3 + 9a7367b commit 3f06bf9

File tree

1 file changed

+18
-0
lines changed

1 file changed

+18
-0
lines changed

src/libcore/macros.rs

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,17 @@ macro_rules! panic {
3535
/// This will invoke the `panic!` macro if the provided expression cannot be
3636
/// evaluated to `true` at runtime.
3737
///
38+
/// Assertions are always checked in both debug and release builds, and cannot
39+
/// be disabled. See `debug_assert!` for assertions that are not enabled in
40+
/// release builds by default.
41+
///
42+
/// Unsafe code relies on `assert!` to enforce run-time invariants that, if
43+
/// violated could lead to unsafety.
44+
///
45+
/// Other use-cases of `assert!` include
46+
/// [testing](https://doc.rust-lang.org/book/testing.html) and enforcing
47+
/// run-time invariants in safe code (whose violation cannot result in unsafety).
48+
///
3849
/// This macro has a second version, where a custom panic message can be provided.
3950
///
4051
/// # Examples
@@ -123,6 +134,13 @@ macro_rules! assert_eq {
123134
/// expensive to be present in a release build but may be helpful during
124135
/// development.
125136
///
137+
/// An unchecked assertion allows a program in an inconsistent state to keep
138+
/// running, which might have unexpected consequences but does not introduce
139+
/// unsafety as long as this only happens in safe code. The performance cost
140+
/// of assertions, is however, not measurable in general. Replacing `assert!`
141+
/// with `debug_assert!` is thus only encouraged after thorough profiling, and
142+
/// more importantly, only in safe code!
143+
///
126144
/// # Examples
127145
///
128146
/// ```

0 commit comments

Comments
 (0)