Re: [COMMIT] Docstring improvements for basic Lisp functions, CL

This isn't a veto, but -(defmacro push (x place) - "(push X PLACE): insert X at the head of the list stored in PLACE. -Analogous to (setf PLACE (cons X PLACE)), though more careful about -evaluating each argument only once and in the right order. PLACE may +(defmacro push (newelt listname) + "Add NEWELT to the list stored in LISTNAME. +Analogous to (setf LISTNAME (cons NEWELT LISTNAME)), though more careful about +evaluating each argument only once and in the right order. LISTNAME may This wording is not an improvement; "add" could be interpreted to mean "append" or even "insert at some arbitrary, possibly variable, position." Also, in XEmacs Lisp PLACE need not refer to a list: (let ((x 'y)) (push 'z x) x) => (z . y) -(defmacro pushnew (x place &rest keys) - "(pushnew X PLACE): insert X at the head of the list if not already there. -Like (push X PLACE), except that the list is unmodified if X is `eql' to -an element already on the list. +(defmacro pushnew (newelt listname &rest keys) + "Add NEWELT to the list stored in LISTNAME, unless it's already there. +Like (push NEWELT LISTNAME), except that the list is unmodified if NEWELT is +`eql' to an element already on the list. Ditto, except worse since the pseudo-code isn't present. All of the following could be improved by rewriting to refer to related functions. Eg, +A cons cell is a Lisp object (an area in memory) comprising two pointers +called the CAR and the CDR. Each of these pointers can point to any other +Lisp object. The common Lisp data type, the list, is a specially-structured +series of cons cells. A cons cell is a Lisp object containing two references to arbitrary Lisp objects. The references are accessed with `car' and `cdr', and mutated with `setcar' and `setcdr' respectively. For historical reasons, the aliases `rplaca' and `rplacd' (for `setcar' and `setcdr') are supported. Many structures are built up from cons cells (lists, alists, plists). +A list is implemented as a series of cons cells structured such that the CDR +of each cell either points to another cons cell or to `nil', the special +Lisp value for both Boolean false and the empty list. A list is either the Lisp object nil (a symbol), interpreted as the empty list in this context, or a cons cell whose CDR refers to either nil or a cons cell. A "proper list" contains no cycles. +A symbol is a Lisp object with a name. It can optionally have any and all of +a value, a property list and an associated function. A symbol is a Lisp object with a name, and that name always refers to the same symbol (with a few exceptions, which must be explicitly invoked). The symbol may be used as a variable (ie, to contain a value) or function in Lisp code. It also has a property list which may be accessed with `get' and mutated with `put'. etc, etc -- School of Systems and Information Engineering http://turnbull.sk.tsukuba.ac.jp University of Tsukuba Tennodai 1-1-1 Tsukuba 305-8573 JAPAN Ask not how you can "do" free software business; ask what your business can "do for" free software.