Docstring for `=` could be made less ambiguous w.r.t. numbers

Question

The current docstring of = says:
> compares numbers and collections in a type-independent manner

Which makes it sound like it compares numbers by value, checking whether dots on a number line coincide.

Whereas in reality:

user=> (= 1. 1)
false

The page at https://clojure.org/guides/equality#_summary explains why, but it would be nice to have that information in the docstring as well.

Answer 1

Following the same docstring I saw some confusions with:
> Same as Java x.equals(y) except it also works for nil

and people expecting this to mean the same thing:

(defrecord Foo [a])

(= (Foo. 1)
   {:a 1})
;; => false

(.equals (Foo. 1)
         {:a 1})
;; => true

Comments

I also notice that `=` thinks `(long 1)` and `(short 1)` are equal but not `1` and `1.0`.  So it does *some* case independent comparison, but exactly what is unclear.

---

Another weird example:
    user=> (= 1/1 (clojure.lang.Ratio. (biginteger 1) (biginteger 1)))
    false
    user=> (= 1/2 (clojure.lang.Ratio. (biginteger 1) (biginteger 2)))
    true

---

I am not an authority on this matter, but my educated guess is that Clojure's implementation never intended to support direct calls to the clojure.lang.Ratio constructor.  There is code outside of that constructor when doing math on ratio types that explicitly reduces numerator and denominator to lowest common terms, and returns an integer object, not a ratio object, when the result is an integer.  Thus it seems like your constructor calls are intentionally trying to sidestep that by digging into calls intended to remain part of Clojure's internal implementation, not its supported API.

Answer 2

I do not know the Clojure maintainer's views on this idea, but an approach that would make the details easier to find for many people, without significantly increasing the length of the compiled-into-the-Clojure-image doc string, would be to add a sentence like "For additional details, see https://clojure.org/guides/equality" in the doc string.