From a72767970adbe3600d1b66eff118ba4dd732c804 Mon Sep 17 00:00:00 2001 From: "Panashe M. Fundira" Date: Wed, 27 Jul 2016 13:12:35 -0400 Subject: [PATCH 1/4] Update docs for assert! and debug_assert! --- src/libcore/macros.rs | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index 43868d124a22e..e3207a0a86c4f 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros.rs @@ -32,8 +32,19 @@ macro_rules! panic { /// Ensure that a boolean expression is `true` at runtime. /// -/// This will invoke the `panic!` macro if the provided expression cannot be -/// evaluated to `true` at runtime. +/// This will ensure the termination of the program if the provided expression +/// cannot be evaluated to `true` at runtime by means of an unrecoverable error +/// (not necessarily a `panic!`, can also be an `abort`). +/// +/// Assertions are always checked in both debug and release builds, and cannot +/// be disabled. +/// +/// Unsafe code relies on `assert!` to enforce run-time invariants that, if +/// violated could lead to unsafety. +/// +/// Other use-cases of `assert!` include +/// [testing](https://doc.rust-lang.org/book/testing.html) and enforcing +/// run-time invariants in safe code (whose violation cannot result in unsafety). /// /// This macro has a second version, where a custom panic message can be provided. /// @@ -123,6 +134,13 @@ macro_rules! assert_eq { /// expensive to be present in a release build but may be helpful during /// development. /// +/// An unchecked assertion allows a program in an inconsistent state to keep +/// running, which might have unexpected consequences but does not introduce +/// unsafety as long as this only happens in safe code. The performance cost +/// of assertions, is however, not measurable in general. Replacing `assert!` +/// with `debug_assert!` is thus only encourage after thorough profiling, and +/// more importantly, only in safe code! +/// /// # Examples /// /// ``` From 91acc3977bdb62b52698b488c63070adbf29af30 Mon Sep 17 00:00:00 2001 From: "Panashe M. Fundira" Date: Wed, 27 Jul 2016 15:01:43 -0400 Subject: [PATCH 2/4] Correct minor typo in debug_assert doc --- src/libcore/macros.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index e3207a0a86c4f..c8606b0f16361 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros.rs @@ -138,7 +138,7 @@ macro_rules! assert_eq { /// running, which might have unexpected consequences but does not introduce /// unsafety as long as this only happens in safe code. The performance cost /// of assertions, is however, not measurable in general. Replacing `assert!` -/// with `debug_assert!` is thus only encourage after thorough profiling, and +/// with `debug_assert!` is thus only encouraged after thorough profiling, and /// more importantly, only in safe code! /// /// # Examples From 8760b1dd264bfd4f00a772e3229d02b9bb0e25f4 Mon Sep 17 00:00:00 2001 From: "Panashe M. Fundira" Date: Wed, 27 Jul 2016 15:03:23 -0400 Subject: [PATCH 3/4] Revert section about panic! in assert! doc --- src/libcore/macros.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index c8606b0f16361..260d974e45d6c 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros.rs @@ -32,9 +32,8 @@ macro_rules! panic { /// Ensure that a boolean expression is `true` at runtime. /// -/// This will ensure the termination of the program if the provided expression -/// cannot be evaluated to `true` at runtime by means of an unrecoverable error -/// (not necessarily a `panic!`, can also be an `abort`). +/// This will invoke the `panic!` macro if the provided expression cannot be +/// evaluated to `true` at runtime. /// /// Assertions are always checked in both debug and release builds, and cannot /// be disabled. From 9a7367b96035ab1ff7593f929c852181de1bcbfb Mon Sep 17 00:00:00 2001 From: "Panashe M. Fundira" Date: Wed, 27 Jul 2016 15:16:11 -0400 Subject: [PATCH 4/4] Mention debug_assert! in assert! doc --- src/libcore/macros.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index 260d974e45d6c..b0c79a3a88547 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros.rs @@ -36,7 +36,8 @@ macro_rules! panic { /// evaluated to `true` at runtime. /// /// Assertions are always checked in both debug and release builds, and cannot -/// be disabled. +/// be disabled. See `debug_assert!` for assertions that are not enabled in +/// release builds by default. /// /// Unsafe code relies on `assert!` to enforce run-time invariants that, if /// violated could lead to unsafety.