Re: map.el documentation

[Robert Pluim]

>>>>> 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"?

Robert
--