Recommend against using the form rethrow(e) (#33296)

This misrepresents the program state and is largely obsoleted by the
catch_stack functionality.

Author: c42f

base/error.jl

@@ -43,10 +43,18 @@ function error(s::Vararg{Any,N}) where {N}
 end
 
 """
-    rethrow([e])
-
-Throw an object without changing the current exception backtrace. The default argument is
-the current exception (if called within a `catch` block).
+    rethrow()
+
+Rethrow the current exception from within a `catch` block. The rethrown
+exception will continue propagation as if it had not been caught.
+
+!!! note
+    The alternative form `rethrow(e)` allows you to associate an alternative
+    exception object `e` with the current backtrace. However this misrepresents
+    the program state at the time of the error so you're encouraged to instead
+    throw a new exception using `throw(e)`. In Julia 1.1 and above, using
+    `throw(e)` will preserve the root cause exception on the stack, as
+    described in [`catch_stack`](@ref).
 """
 rethrow() = ccall(:jl_rethrow, Bottom, ())
 rethrow(e) = ccall(:jl_rethrow_other, Bottom, (Any,), e)