User: aidan
Date: 06/04/16 17:54:23
Modified: xemacs/src ChangeLog data.c
Log:
Docstring improvements for basic Lisp functions, CL.
Revision Changes Path
1.736 +11 -0 XEmacs/xemacs/lisp/ChangeLog
Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lisp/ChangeLog,v
retrieving revision 1.735
retrieving revision 1.736
diff -u -p -r1.735 -r1.736
--- ChangeLog 2006/04/15 14:44:34 1.735
+++ ChangeLog 2006/04/16 15:54:16 1.736
@@ -1,3 +1,14 @@
+2006-04-16 Aidan Kehoe <kehoea(a)parhasard.net>
+
+ * cl.el (incf):
+ * cl.el (decf):
+ * cl.el (pop):
+ * cl.el (push):
+ * cl.el (pushnew):
+ Docstring clarifications; drop non-standard formatting for incf,
+ decf, pop, move to GNU's parameter names for push, pushnew since
+ they make it much easier to remember the right order.
+
2006-04-15 Aidan Kehoe <kehoea(a)parhasard.net>
* cmdloop.el (read-quoted-char): Use unicode-to-char instead of
1.16 +16 -15 XEmacs/xemacs/lisp/cl.el
Index: cl.el
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lisp/cl.el,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -p -r1.15 -r1.16
--- cl.el 2005/01/26 09:53:32 1.15
+++ cl.el 2006/04/16 15:54:16 1.16
@@ -132,7 +132,7 @@ Floating-point numbers of equal value ar
;;; can safely be used in .emacs files.
(defmacro incf (place &optional x)
- "(incf PLACE [X]): increment PLACE by X (1 by default).
+ "Increment PLACE by X (1 by default).
PLACE may be a symbol, or any generalized variable allowed by `setf'.
The return value is the incremented value of PLACE."
(if (symbolp place)
@@ -142,7 +142,7 @@ The return value is the incremented valu
(list 'callf '+ place (or x 1))))
(defmacro decf (place &optional x)
- "(decf PLACE [X]): decrement PLACE by X (1 by default).
+ "Decrement PLACE by X (1 by default).
PLACE may be a symbol, or any generalized variable allowed by `setf'.
The return value is the decremented value of PLACE."
(if (symbolp place)
@@ -150,7 +150,7 @@ The return value is the decremented valu
(list 'callf '- place (or x 1))))
(defmacro pop (place)
- "(pop PLACE): remove and return the head of the list stored in PLACE.
+ "Remove and return the head of the list stored in PLACE.
Analogous to (prog1 (car PLACE) (setf PLACE (cdr PLACE))), though more
careful about evaluating each argument only once and in the right order.
PLACE may be a symbol, or any generalized variable allowed by `setf'."
@@ -158,21 +158,22 @@ PLACE may be a symbol, or any generalize
`(car (prog1 ,place (setq ,place (cdr ,place))))
(cl-do-pop place)))
-(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
be a symbol, or any generalized variable allowed by `setf'."
- (if (symbolp place) `(setq ,place (cons ,x ,place))
- (list 'callf2 'cons x place)))
+ (if (symbolp listname) `(setq ,listname (cons ,newelt ,listname))
+ (list 'callf2 'cons newelt listname)))
-(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.
Keywords supported: :test :test-not :key"
- (if (symbolp place) (list 'setq place (list* 'adjoin x place keys))
- (list* 'callf2 'adjoin x place keys)))
+ (if (symbolp listname) (list 'setq listname
+ (list* 'adjoin newelt listname keys))
+ (list* 'callf2 'adjoin newelt listname keys)))
(defun cl-set-elt (seq n val)
(if (listp seq) (setcar (nthcdr n seq) val) (aset seq n val)))
1.943 +17 -0 XEmacs/xemacs/src/ChangeLog
Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/ChangeLog,v
retrieving revision 1.942
retrieving revision 1.943
diff -u -p -r1.942 -r1.943
--- ChangeLog 2006/04/10 15:16:45 1.942
+++ ChangeLog 2006/04/16 15:54:20 1.943
@@ -1,3 +1,20 @@
+2006-04-16 Aidan Kehoe <kehoea(a)parhasard.net>
+
+ * data.c (Fconsp):
+ * data.c (Fsymbolp):
+ * data.c (Fcar):
+ * data.c (Flistp):
+ * data.c (Fsetcar):
+ * data.c (Fsetcdr):
+ * data.c (Flss):
+ * data.c (Fgtr):
+ Short docstring clarifications to make life easier for people who
+ are learning Lisp; explain what a cons is in the consp docstring,
+ what a symbol is in the symbolp docstring, and so forth. Thank you
+ Alan Mackenzie on emacs-devel.
+ Expand on "monotonically increasing" and "monotonically
+ decreasing" in the Flss and Fgtr docstrings.
+
2006-04-10 Jerry James <james(a)xemacs.org>
* alsaplay.c: Support pre-1.0.10 versions of the ALSA library.
1.66 +44 -14 XEmacs/xemacs/src/data.c
Index: data.c
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/data.c,v
retrieving revision 1.65
retrieving revision 1.66
diff -u -p -r1.65 -r1.66
--- data.c 2005/10/24 10:07:35 1.65
+++ data.c 2006/04/16 15:54:21 1.66
@@ -216,6 +216,11 @@ Return t if OBJECT is nil.
DEFUN ("consp", Fconsp, 1, 1, 0, /*
Return t if OBJECT is a cons cell. `nil' is not a cons cell.
+
+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.
*/
(object))
{
@@ -232,6 +237,10 @@ Return t if OBJECT is not a cons cell.
DEFUN ("listp", Flistp, 1, 1, 0, /*
Return t if OBJECT is a list. `nil' is a list.
+
+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.
*/
(object))
{
@@ -256,6 +265,9 @@ Return t if OBJECT is an acyclic, nil-te
DEFUN ("symbolp", Fsymbolp, 1, 1, 0, /*
Return t if OBJECT is a symbol.
+
+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.
*/
(object))
{
@@ -600,19 +612,21 @@ Return a symbol representing the type of
/* Extract and set components of lists */
DEFUN ("car", Fcar, 1, 1, 0, /*
-Return the car of LIST. If arg is nil, return nil.
-Error if arg is not nil and not a cons cell. See also `car-safe'.
+Return the car of CONS. If CONS is nil, return nil.
+The car of a list or a dotted pair is its first element.
+
+Error if CONS is not nil and not a cons cell. See also `car-safe'.
*/
- (list))
+ (cons))
{
while (1)
{
- if (CONSP (list))
- return XCAR (list);
- else if (NILP (list))
+ if (CONSP (cons))
+ return XCAR (cons);
+ else if (NILP (cons))
return Qnil;
else
- list = wrong_type_argument (Qlistp, list);
+ cons = wrong_type_argument (Qlistp, cons);
}
}
@@ -625,19 +639,22 @@ Return the car of OBJECT if it is a cons
}
DEFUN ("cdr", Fcdr, 1, 1, 0, /*
-Return the cdr of LIST. If arg is nil, return nil.
+Return the cdr of CONS. If CONS is nil, return nil.
+The cdr of a list is the list without its first element. The cdr of a
+dotted pair (A . B) is the second element, B.
+
Error if arg is not nil and not a cons cell. See also `cdr-safe'.
*/
- (list))
+ (cons))
{
while (1)
{
- if (CONSP (list))
- return XCDR (list);
- else if (NILP (list))
+ if (CONSP (cons))
+ return XCDR (cons);
+ else if (NILP (cons))
return Qnil;
else
- list = wrong_type_argument (Qlistp, list);
+ cons = wrong_type_argument (Qlistp, cons);
}
}
@@ -651,6 +668,7 @@ Return the cdr of OBJECT if it is a cons
DEFUN ("setcar", Fsetcar, 2, 2, 0, /*
Set the car of CONS-CELL to be NEWCAR. Return NEWCAR.
+The car of a list or a dotted pair is its first element.
*/
(cons_cell, newcar))
{
@@ -663,6 +681,8 @@ Set the car of CONS-CELL to be NEWCAR.
DEFUN ("setcdr", Fsetcdr, 2, 2, 0, /*
Set the cdr of CONS-CELL to be NEWCDR. Return NEWCDR.
+The cdr of a list is the list without its first element. The cdr of a
+dotted pair (A . B) is the second element, B.
*/
(cons_cell, newcdr))
{
@@ -986,7 +1006,12 @@ The arguments may be numbers, characters
DEFUN ("<", Flss, 1, MANY, 0, /*
Return t if the sequence of arguments is monotonically increasing.
-The arguments may be numbers, characters or markers.
+
+(That is, if there is a second argument, it must be numerically greater than
+the first. If there is a third, it must be numerically greater than the
+second, and so on.) At least one argument is required.
+
+The arguments may be numbers, characters or markers.
*/
(int nargs, Lisp_Object *args))
{
@@ -995,6 +1020,11 @@ The arguments may be numbers, characters
DEFUN (">", Fgtr, 1, MANY, 0, /*
Return t if the sequence of arguments is monotonically decreasing.
+
+(That is, if there is a second argument, it must be numerically less than
+the first. If there is a third, it must be numerically less than the
+second, and so forth.) At least one argument is required.
+
The arguments may be numbers, characters or markers.
*/
(int nargs, Lisp_Object *args))