Re: map.el documentation (was: bug#75170: add-to-alist: new function)

[Eli Zaretskii]

I've moved this discussion from an unrelated discussion on the bug
tracker.

> From: Arash Esbati <arash@gnu.org>
> Cc: rpluim@gmail.com,  stefankangas@gmail.com,  winkler@gnu.org,
>   monnier@gnu.org,  ams@gnu.org,  75170@debbugs.gnu.org,  acorallo@gnu.org
> Date: Wed, 22 Jan 2025 22:56:24 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Let's begin by fixing the doc strings, then.  We can consider adding
> > to manual later, but the built-in documentation must be clear enough
> > to use map.el.
> 
> For example, I was looking at the docstring of `map-insert':
> 
>   (map-insert MAP KEY VALUE)
> 
>   Return a new map like MAP except that it associates KEY with VALUE.
> 
> For me, something like this would have been easier to grasp:
> 
>   Cons KEY/VALUE in front of MAP replacing value associated to KEY with VALUE.
> 
> Next, I eval'ed:
> 
>   (map-insert '((y . 1)) 'a 2)
>   => ((a . 2) (y . 1))
> 
>   (map-insert '((y . 2) (x . 1)) 'x 3)
>   => ((x . 3) (y . 2) (x . 1))
> 
> And sort of gave up since I was expecting ((x . 3) (y . 2)).  But again,
> maybe it's just me having problems understanding the docstring.

The doc string never says map-insert should replace any existing alist
elements.  Perhaps that is what you expected, based on some mental
model of the internal implementation details, but it was not promised
by the doc string.  Moreover, calling map-elt after that works as
expected:

  (let ((my-map (map-insert '((y . 2) (x . 1)) 'x 3)))
    (map-elt my-map 'x))
    => 3

So I see no problem here, at least not yet.