For clarity I will insert the first lines of the docstrings here:

map-elt is a Lisp closure in ‘map.el’.
>
> (map-elt MAP KEY &optional DEFAULT)
>
>   Probably introduced at or before Emacs version 26.1.
>
> Lookup KEY in MAP and return its associated value.
> If KEY is not found, return DEFAULT which defaults to nil.
>
> TESTFN is deprecated.  Its default depends on the MAP argument.
>
> In the base definition, MAP can be an alist, plist, hash-table,
> or array.
>

First I agree with Michael that this docstring assumes a lot of knowledge
from the programmer.
The sentence "its default depends on the MAP argument" could be more
explicit, to make the docstring friendly to new elisp programmers.
e.g. mention eq for alists (and also the TESTFN's for the other ones)

Second calling the TESTFN deprecated is misleading if it a basic
requirement for the basic thing I am trying to achieve (i.e. matching a
string).
So it should probably mention that it is not required if you want to use
the MAP's default TESTFN, but otherwise it is required (while deprecated
sounds to me like there shouldn't be a need to use it)

Thanks for your answer!




On Thu, 25 Mar 2021 at 03:39, Michael Heerdegen <michael_heerdegen@web.de>
wrote:

> "Basil L. Contovounesios" <contovob@tcd.ie> writes:
>
> > dalanicolai <dalanicolai@gmail.com> writes:
> >
> > > The docstring of the map-elt function from the map.el package (version
> > > 3.0) mentions that TESTFN is deprecated because "its default depends on
> > > the MAP argument". However when I try e.g.
> > >
> > > (map-elt '(("A1" . 3)) "A1")
> > >
> > > it returns nil.
> >
> > This is expected, as alist keys are tested with eq by default.
> >
> > That's what the docstring is trying to warn about: alists default to
> > testing with eq, but can also use eql, equal, or anything else.
>
> Is it that obvious?  We have `assoc' and `assq' built-in - to me it's
> not obvious that "alist keys are tested with eq by default".  It's the
> default for `alist-get', ok, which is used by the implementation, but
> not everybody will know that.  I would add a sentence about that.
>
> Michael.
>