= - doc perhaps not precise enough

Question

looking at =

(defn ^boolean =
  "Equality. Returns true if x equals y, false if not. Compares
  numbers and collections in a type-independent manner.  Clojure's immutable data
  structures define -equiv (and thus =) as a value, not an identity,
  comparison."
  ([x] true)
  ([x y]
    (if (nil? x)
      (nil? y)
      (or (identical? x y)
        ^boolean (-equiv x y))))
  ([x y & more]
     (if (= x y)
       (if (next more)
         (recur y (first more) (next more))
         (= y (first more)))
       false)))

evaluating the following seams surprising to me:

(= [1] #{1})

because a vector is a collection and a set is also a collection, so when it says

Compares numbers and collections in a type-independent manner.

i think it should say:

Compares numbers, sequentials, maps and sets in a type-independent
manner.

Answer 1

I cannot say whether the doc string will change, but I did write this guide article on equality, after some significant time spent on corner cases of Clojure = behavior, but trying to focus first on a brief description of the main behavior: https://clojure.org/guides/equality

I do not know whether the core Clojure team would be open to adding a link to that article to the official doc string or not, but that would be one way to lead people to the article when they are curious about its contents.

Comments

what a great article!!! lots of stuff i did not know about.

now i for one would love to be able to find this kind of high quality doc about = ( easily )...

also i want to withdraw my original suggestion for how to change the doc at this point, since obviously one can do much better than that! ( be it via link or otherwise.... )

---

I'd be curious to know if you did look for a doc like this, and if so where? A google search for "clojure equality" has this guide as the first hit, and the clojure.org search also finds it as the first result.

---

... hmmm... alright, point well taken,... truth be told, all i did was follow along from my code to the source... and then i read the doc... and then i thought,... well... exactly what i posted about....

... so ....  i see what you mean, perhaps i could have done a more thorough search online, .... still, to me at least the doc does not seam like it is 100% correct the way it currently is.

---

@alexmiller .... so.... did you already get a chance to reflect on this one?..... i still think i was right to point it out... so...

---

Bear in mind that docstrings are compiled into the JAR that ships as "Clojure" so increasing the docstrings has a (small) direct cost for everyone using Clojure, regardless of whether they look at the docstrings.

Historically, the docstrings have always been a short, concise description of the behavior that is expected to be augmented in guides/reference material on clojure.org and the various community-managed documentation sites (or in books).

There are a LOT of clojure.core docstrings that could justifiably be enhanced, either to provide clarifications such as you highlight here, or to add examples, or expand the description, or more clearly define terms used in them -- but all of that adds overhead to the Clojure artifact so none of it should be undertaken lightly. Changes to Clojure itself -- even just docstring changes -- require work from Clojure's core maintenance team at Cognitect so it takes away their time from other things that benefit users of the language.

Expanding the material on clojure.org itself has no such cost (other than the willingness of volunteers to contribute their time to create/expand that material) -- beyond the moderation effort of Alex et al to review and merge such content, which bar is a lot lower than for Clojure itself.

---

@Sean Corfield first of all thanks for answering! ( ... with all of my questions / comments i would sometimes have liked to get a little more ( useful ) feedback ... and i guess you have been the one person who was pretty much always willing to take some time out of their busy schedule .... and to write / give something back.... so i really really appreciate that!!!... i mean..... for example that time when we were talking about datomic and databases.... even though we did not reach the same conclusion... it still felt nice to know that someone out there at least cares a little bit about that sort of stuff too... (... and was willing to have a bit of a discussion about it :-).... ))

iiiiin any case.... so.... this time too, it seams to me, that you make good and valid points... nevertheless i fear that this approach / trade-off does inevitably ( ....among other things.... ) result in a higher entry barrier for beginners....  for example in this video on equality i did.... ( https://www.youtube.com/watch?v=MhzXMiYdUxQ )... you can see exactly what happens when people are just looking around the code... exploring things... and how someone could end up a bit confused / misled by this type of laconic doc.... ( ...also note that this video is pretty long... the part that is relevant here happens around the 30min mark... )

---

It is really up to Rich Hickey and a few others what goes in the doc strings.  They have a definite preference for  concise doc strings.  It has been commented on N times in the past, and seems unlikely to change.  ClojureDocs.org has community-created examples and content to supplement this, but they are not "official", and may contain some misunderstandings.  Another non-official source I have not read yet, but they contain results from lots of study by extremely interested Clojure users, are the book "Joy of Clojure" and "Clojure: The Essential Reference".