From 3350aeffe399a9966a726971dc5fc4269a6c7f4e Mon Sep 17 00:00:00 2001 From: Lukasz Samson Date: Wed, 28 May 2025 10:50:28 +0200 Subject: [PATCH 1/2] Improve documentation on Exception.message and Exception.blame --- lib/elixir/lib/exception.ex | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/lib/elixir/lib/exception.ex b/lib/elixir/lib/exception.ex index fef7b7f1dd..d272a60191 100644 --- a/lib/elixir/lib/exception.ex +++ b/lib/elixir/lib/exception.ex @@ -82,6 +82,11 @@ defmodule Exception do @doc """ Gets the message for an `exception`. + + This function will invoke the `c:message/1` callback on the exception + module to retrieve the message. If the callback raises an exception or + returns a non-binary value, this function will rescue the error and + return a descriptive error message instead. """ @spec message(t) :: String.t() def message(%module{__exception__: true} = exception) do @@ -153,7 +158,7 @@ defmodule Exception do end @doc """ - Normalizes and formats throw/errors/exits and stacktraces. + Normalizes and formats throws/errors/exits and stacktraces. It relies on `format_banner/3` and `format_stacktrace/1` to generate the final format. @@ -193,14 +198,17 @@ defmodule Exception do end @doc """ - Attaches information to exceptions for extra debugging. + Attaches information to throws/errors/exits for extra debugging. This operation is potentially expensive, as it reads data from the file system, parses beam files, evaluates code and so on. - If the exception module implements the optional `c:blame/2` - callback, it will be invoked to perform the computation. + If `kind` argument is `:error` and the `error` is an Erlang exception, this function will + normalize it. If the `error` argument is an Elixir exception, this function will invoke + the optional `c:blame/2` callback on the exception module if it is implemented. + Unlike `message/1`, this function will not rescue errors - if the callback raises an exception, + the error will propagate to the caller. """ @doc since: "1.5.0" @spec blame(:error, any, stacktrace) :: {t, stacktrace} From 7811909cafbb7811a514e1f067ca2b06c8914af4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Wed, 28 May 2025 11:04:03 +0200 Subject: [PATCH 2/2] Update lib/elixir/lib/exception.ex --- lib/elixir/lib/exception.ex | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/elixir/lib/exception.ex b/lib/elixir/lib/exception.ex index d272a60191..5d8b63ad4b 100644 --- a/lib/elixir/lib/exception.ex +++ b/lib/elixir/lib/exception.ex @@ -208,7 +208,8 @@ defmodule Exception do normalize it. If the `error` argument is an Elixir exception, this function will invoke the optional `c:blame/2` callback on the exception module if it is implemented. Unlike `message/1`, this function will not rescue errors - if the callback raises an exception, - the error will propagate to the caller. + the error will propagate to the caller. It is your choice if you want to rescue and return + the original exception, return a different exception, or let it cascade. """ @doc since: "1.5.0" @spec blame(:error, any, stacktrace) :: {t, stacktrace}