Subject: bug#75170: add-to-alist: new function

From: Arash Esbati <[email-masked]>
Date: Wed, 22 Jan 2025 22:56:24 +0100

Eli Zaretskii <[email-masked]> 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.

P.S. Sorry for hijacking this thread, maybe we should move this
discussion somewhere else.

Best, Arash