[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Lispref add-to-list - doc is unnecessary convoluted
From: |
Arthur Miller |
Subject: |
Lispref add-to-list - doc is unnecessary convoluted |
Date: |
Fri, 04 Dec 2020 03:17:19 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) |
Function: add-to-list symbol element &optional append compare-fn
This function sets the variable symbol by consing element onto the old
value, if element is not already a member of that value. It returns the
resulting list, whether updated or not. The value of symbol had better be a
list already before the call. add-to-list uses compare-fn to compare element
against existing list members; if compare-fn is nil, it uses equal.
Normally, if element is added, it is added to the front of symbol, but if
the optional argument append is non-nil, it is added at the end.
The argument symbol is not implicitly quoted; add-to-list is an ordinary
function, like set and unlike setq. Quote the argument yourself if that is what
you want.
Do not use this function when symbol refers to a lexical variable.
I think this doc is unnecessary convoluted and I don't see reason why it
describes the implementation. That first sentence make something so
simple as add-to-list sound so complicated for some reason when you read
it, and requires one to think twice through what it say (at least me).
Other functions does not do so, so why this one? I don't think it is
necessary since docs anyway says how it add to list (front/back) kist a
three sentences further.
I think it is more clear to use word 'list' instead of 'symbol' (element
is a symbol too for example). Not least because docs later says: "better
be a list". It clarifies intentions, and hopefully removes the need to say
things like 'better be a list'.
I hope I don't hurt anyone's feelings; I dont' know who wrote it, but I
would like to suggest a slight modification, patch included. I am not
native english speaker, so if you agree to change it, somebody please
look through it.
add-to-list-doc.patch
Description: Text Data
- Lispref add-to-list - doc is unnecessary convoluted,
Arthur Miller <=