@@ -35,6 +35,17 @@ macro_rules! panic {
35
35
/// This will invoke the `panic!` macro if the provided expression cannot be
36
36
/// evaluated to `true` at runtime.
37
37
///
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
+ ///
38
49
/// This macro has a second version, where a custom panic message can be provided.
39
50
///
40
51
/// # Examples
@@ -123,6 +134,13 @@ macro_rules! assert_eq {
123
134
/// expensive to be present in a release build but may be helpful during
124
135
/// development.
125
136
///
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
+ ///
126
144
/// # Examples
127
145
///
128
146
/// ```
0 commit comments