`find` docstring enhancement proposal

Question

The docstring for clojure.core/find states

Returns the map entry for key, or nil if key not present.

Formatted lower-cased with a space, it is not immediately apparent that 'map entry' is a term of art referring to a specific thing. 'map entry' might be mis-interpreted as a casual synonym for 'the entry of a map associated to a key', i.e., the value.

Proposal #1
Reword the find docstring to be more precise about what is returned.

Returns a clojure.lang.MapEntry containing key and the associated value, or nil if key not present.

Proposal #2
If you don't want to make a commitment to returning a MapEntry, reword to

Returns a sequential collection containing key and the associated value, or nil if key not present.

Answer 1

See https://clojure.org/reference/data_structures#Maps (and other places on that page) where "entry" is referred to and, in particular:

"...a sequence of map entries, which are key/value pairs"

See also https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Map.html where "entry" is referred to several times and also defined as a key/value pair.

Searching the web for map entry -java seems to indicate this is pretty common terminology in other languages as well.

Comments

Since the notion of MapEntry-able Thing is common to `find` and `conj` (and its nature, independent of Map$Entry, is clearer now with ClojureScript in the mix), it should be introduced more forthrightly on the page Sean cited, https://clojure.org/reference/data_structures#Maps. The page need not even get any longer, but merely elevate the by-the-way sentence from the hash computation paragraph.

The `find` docstring is subtle. One of many! We may as well regard the subtlety fondly.