GNU bug report logs - #34708
alist-get has unclear documentation

Previous Next

Full log

Message #32 received at 34708 <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: "Miguel V. S. Frasson" <mvsfrasson <at> gmail.com>
Cc: Eric Abrahamsen <eric <at> ericabrahamsen.net>, 34708 <at> debbugs.gnu.org
Subject: Re: bug#34708: alist-get has unclear documentation
Date: Sun, 03 Mar 2019 13:21:40 +0100

"Miguel V. S. Frasson" <mvsfrasson <at> gmail.com> writes:

> Hi
>
> I think the sentence below is a good and short explanation for the
> doc-string.
>
> The return value can be conveniently used as a generalized variable (a
> place) to set the value associated with KEY in ALIST, like in the
> example (setf (alist-get key alist) new-value)

Thanks for the idea.  I don't think we should explain it like this
however, because when evaluating

  (setf (alist-get key alist) new-value)

the function `alist-get' is never called, so there is no return value.
Of course what is sexy about place expressions is that it looks like you
would directly set the result of a function call, but what happens is
that setf doesn't evaluate the call but analyses it and builds and
evaluates code that leads to this result.

Eric suggested to say "this form is a setf-able place" but this also
doesn't answer the question what this (form) is.  `alist-get' is not a
form, it's the name of a function.  In my opinion it would be cleaner to
say something like "the name of this function can be used to build place
expressions" or "can be used in place expressions" or so.  Better ideas
welcome.


Michael.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.