Re: map.el documentation

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Arash Esbati <arash@gnu.org>,  emacs-devel@gnu.org
> Date: Thu, 23 Jan 2025 11:33:55 +0100
> 
> >>>>> On Thu, 23 Jan 2025 12:11:43 +0200, Eli Zaretskii <eliz@gnu.org> said:
> 
>     Eli> The doc string never says map-insert should replace any existing 
> alist
>     Eli> elements.  Perhaps that is what you expected, based on some mental
>     Eli> model of the internal implementation details, but it was not promised
>     Eli> by the doc string.  Moreover, calling map-elt after that works as
>     Eli> expected:
> 
>     Eli>   (let ((my-map (map-insert '((y . 2) (x . 1)) 'x 3)))
>     Eli>     (map-elt my-map 'x))
>     Eli>     => 3
> 
>     Eli> So I see no problem here, at least not yet.
> 
> Iʼve just pushed a shortdoc documentation group for "map.el",
> hopefully that will help clear up such issues in future. I have a few
> docstring changes Iʼm working on as well. It would be great if
> Someone™ wrote some stuff for the elisp manual.

Last I heard, Someone™ has left this project for greener pastures.

Note that I recently made some minor changes in the doc strings of
map.el on the release branch.

> I must admit, the semantics of `map-insert' feel more natural to me
> than `map-put!', but I guess both are needed.

Right.