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 16:10:58 +0100
> 
> >>>>> On Thu, 23 Jan 2025 16:59:52 +0200, Eli Zaretskii <eliz@gnu.org> said:
> 
>     >> From: Arash Esbati <arash@gnu.org>
>     >> Cc: Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
>     >> Date: Thu, 23 Jan 2025 14:45:59 +0100
>     >> 
>     >> Robert Pluim <rpluim@gmail.com> writes:
>     >> 
>     >> > Thatʼs how (setf (a/plist-get ....)) works, yes.
>     >> >
>     >> > I could argue thatʼs a bug in the `list' method for `map-insert', it
>     >> > conses the new key/value onto the map, when it could just use the
>     >> > default method which does `map-put!' on a copy of the map.
>     >> >
>     >> > The only in-house usage of `map-insert' is in ert.el. I donʼt think
>     >> > making `map-insert' update an existing mapping would break anything
>     >> > there, but itʼs probably too late to change it now.
>     >> 
>     >> I agree, it is probably too late.  I could argue this an inaccuracy in
>     >> the docstrings.  It should just say what you said above: For an alist,
>     >> the new key/value is consed onto the map
> 
>     Eli> Sorry, I disagree: that'd be revealing the details of the
>     Eli> implementation, and the doc string is not the right place for it.
> 
>     >> Maybe Someone™ who's touching the docstrings can consider this :-)
> 
>     Eli> He already did.
> 
> Then where do we put the explanations about things to look out for
> when using arrays with "map.el"?

What things?

I only replied to the suggestion to consider adding implementation
details of map-insert to its doc string.  If there are other issues
and suggestions, let's hear them.