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

Previous Next

Full log

View this message in rfc822 format

From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Michael Heerdegen <michael_heerdegen <at> web.de>, 34708 <at> debbugs.gnu.org, "Miguel V. S. Frasson" <mvsfrasson <at> gmail.com>
Subject: bug#34708: alist-get has unclear documentation
Date: Sun, 03 Mar 2019 08:49:14 -0800

On 03/03/19 07:51 AM, Drew Adams wrote:

[...]

>> 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.

Well I used "form" because it _is_ the form -- (alist-get KEY ALIST) --
that is the setf-able place, not the function/macro/name of the
function. At least as far as the coder is concerned.

> Yes wrt the substance (content). But an active
> phrasing is often better than the passive "__ can
> be used". Say what this does by saying what you
> can do with it.
>
> You can use function `alist-get' in a PLACE-expression
> argument to `setf'. In this role it specifies an
> alist element whose value `setf' sets:

> (setf (alist-get KEY ALIST) NEW-VALUE)
>
> Here, `setf' sets the value part of an element
> of ALIST whose key is KEY to NEW-VALUE.

But I like the above better anyway!

Previous Next

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