clojure.core/assert docstring is incorrect

Question

The {{assert}} macro has two arities, documented as {{(assert x)}} and {{(assert x message)}}

The docstring is:
{quote}
Evaluates expr and throws an exception if it does not evaluate to logical true.
{quote}

This is quite misleading since {{assert}} actually throws an {{Error}}. It is tempting to use {{assert}} assuming that a failure will lead to a stacktrace in logs, like any other {{Exception}}, but the reality is that the JVM will terminate.

The behaviour is correct, {{assert}} should cause a program to exit if the asserted condition is true but I regularly come across incorrect uses.

I'll work up a patch if people agree this is an issue.

Comments

Fixed in 1.12

Answer 1

Comment made by: marc

There is one further omission in the docstring (both current and proposed) - neither mention that the behavior of assert depends on the value of the clojure.core/**assert** dynamic var.

Comments

Fixed in 1.12

Answer 2

Comment made by: gordonsyme

clj-2225-20170913.patch updates the assert macro docstring. I've wrapped the docstring at 70 characters, it seems to be a fairly common width used throughout the rest of the file.

Answer 3

Reference: https://clojure.atlassian.net/browse/CLJ-2225 (reported by gordonsyme)

Answer 4

Comment made by: alexmiller

Error is a subclass of Throwable, just like Exception and has no special behavior (although it does have the special intended meaning that most programs should not catch it). Whether or not your program does catch it, or exit, or log, is totally up to your program and not a property of being an Error.

The only change that I think might make sense here is to be more specific about the exception type.