From 8dbb82166923c0fcf8051e65eac560d3e7b81f1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leandro=20Mart=C3=ADnez?= <31046348+lmiq@users.noreply.github.com> Date: Mon, 11 Jul 2022 12:07:49 -0300 Subject: [PATCH 1/6] clarify assert doc entry The `@assert` doc entry is somewhat confusing, first appearing to encourage then discourage its use. This attempts to clarify it for the general user. --- base/error.jl | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/base/error.jl b/base/error.jl index 4459e54def19b..2273080d2c993 100644 --- a/base/error.jl +++ b/base/error.jl @@ -197,15 +197,15 @@ windowserror(p, code::UInt32=Libc.GetLastError(); extrainfo=nothing) = throw(Mai """ @assert cond [text] -Throw an [`AssertionError`](@ref) if `cond` is `false`. Preferred syntax for writing assertions. +Throw an [`AssertionError`](@ref) if `cond` is `false`. Debugging syntax for writing assertions. Message `text` is optionally displayed upon assertion failure. - + !!! warning An assert might be disabled at various optimization levels. Assert should therefore only be used as a debugging tool - and not used for authentication verification (e.g., verifying passwords), - nor should side effects needed for the function to work correctly - be used inside of asserts. + and not used for authentication verification (e.g., verifying passwords). + The return of `@assert` must not trusted for the correct behavior of a function. + # Examples ```jldoctest From a6a493354c1737e701063bb6131b5bc055d6a249 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leandro=20Mart=C3=ADnez?= <31046348+lmiq@users.noreply.github.com> Date: Mon, 11 Jul 2022 19:38:25 -0300 Subject: [PATCH 2/6] rephrase proposal of assert warning reintroduced the side-effects comment --- base/error.jl | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/base/error.jl b/base/error.jl index 2273080d2c993..2157c0c5f2f68 100644 --- a/base/error.jl +++ b/base/error.jl @@ -204,7 +204,8 @@ Message `text` is optionally displayed upon assertion failure. An assert might be disabled at various optimization levels. Assert should therefore only be used as a debugging tool and not used for authentication verification (e.g., verifying passwords). - The return of `@assert` must not trusted for the correct behavior of a function. + The user must not rely on the return value of `@assert` for the correct behavior + of a function, nor should side effects needed for the correct behavior of assert. # Examples From cdf5370605bc4953863479f81a78b01983152c4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leandro=20Mart=C3=ADnez?= <31046348+lmiq@users.noreply.github.com> Date: Tue, 30 Aug 2022 11:13:20 -0300 Subject: [PATCH 3/6] change syntax to tool --- base/error.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/base/error.jl b/base/error.jl index 2157c0c5f2f68..2eff8d3e5e85e 100644 --- a/base/error.jl +++ b/base/error.jl @@ -197,7 +197,7 @@ windowserror(p, code::UInt32=Libc.GetLastError(); extrainfo=nothing) = throw(Mai """ @assert cond [text] -Throw an [`AssertionError`](@ref) if `cond` is `false`. Debugging syntax for writing assertions. +Throw an [`AssertionError`](@ref) if `cond` is `false`. Debugging tool for writing assertions. Message `text` is optionally displayed upon assertion failure. !!! warning From 4b644501dca7c47e7cbc6ed6e2387afa14043de5 Mon Sep 17 00:00:00 2001 From: Jameson Nash Date: Mon, 30 Oct 2023 13:08:42 -0400 Subject: [PATCH 4/6] Update error.jl --- base/error.jl | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/base/error.jl b/base/error.jl index 2eff8d3e5e85e..3a1c927afbea8 100644 --- a/base/error.jl +++ b/base/error.jl @@ -197,16 +197,17 @@ windowserror(p, code::UInt32=Libc.GetLastError(); extrainfo=nothing) = throw(Mai """ @assert cond [text] -Throw an [`AssertionError`](@ref) if `cond` is `false`. Debugging tool for writing assertions. -Message `text` is optionally displayed upon assertion failure. - +Throw an [`AssertionError`](@ref) if `cond` is `false`. This is the prefered syntax for +writing assertions, which are conditions that are assumed to be true, but that the user +might want to check as and aid to debugging if they fail. +The optional message `text` is displayed upon assertion failure. + !!! warning An assert might be disabled at various optimization levels. Assert should therefore only be used as a debugging tool - and not used for authentication verification (e.g., verifying passwords). - The user must not rely on the return value of `@assert` for the correct behavior - of a function, nor should side effects needed for the correct behavior of assert. - + and not used for authentication verification (e.g., verifying passwords or checking array bounds). + The user must not rely on the side effects of `@assert` for the correct behavior + of a function. # Examples ```jldoctest From deb34c533762501ebc155241ed00eff2a119ed22 Mon Sep 17 00:00:00 2001 From: Jameson Nash Date: Mon, 30 Oct 2023 13:10:34 -0400 Subject: [PATCH 5/6] Update error.jl --- base/error.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/base/error.jl b/base/error.jl index 3a1c927afbea8..d6f887aa90b26 100644 --- a/base/error.jl +++ b/base/error.jl @@ -203,10 +203,10 @@ might want to check as and aid to debugging if they fail. The optional message `text` is displayed upon assertion failure. !!! warning - An assert might be disabled at various optimization levels. + An assert might be disabled at some optimization levels. Assert should therefore only be used as a debugging tool and not used for authentication verification (e.g., verifying passwords or checking array bounds). - The user must not rely on the side effects of `@assert` for the correct behavior + The code must not rely on the side effects of running `cond` for the correct behavior of a function. # Examples From 49e669e0a745e1f57fbf669da87c7220ef4fe61c Mon Sep 17 00:00:00 2001 From: Jameson Nash Date: Mon, 30 Oct 2023 13:11:25 -0400 Subject: [PATCH 6/6] Update error.jl --- base/error.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/base/error.jl b/base/error.jl index d6f887aa90b26..ad89748566e71 100644 --- a/base/error.jl +++ b/base/error.jl @@ -197,9 +197,9 @@ windowserror(p, code::UInt32=Libc.GetLastError(); extrainfo=nothing) = throw(Mai """ @assert cond [text] -Throw an [`AssertionError`](@ref) if `cond` is `false`. This is the prefered syntax for +Throw an [`AssertionError`](@ref) if `cond` is `false`. This is the preferred syntax for writing assertions, which are conditions that are assumed to be true, but that the user -might want to check as and aid to debugging if they fail. +might decide to check anyways, as an aid to debugging if they fail. The optional message `text` is displayed upon assertion failure. !!! warning