changeset 62626:970aed705a2a

(pushnew, cl-macroexpand, floatp-safe, plusp, minusp, oddp, evenp, mapcar*, list*, copy-list, adjoin, subst): Improve argument/docstring consistency.

--- a/lisp/emacs-lisp/cl.el	Sun May 22 15:52:51 2005 +0000
+++ b/lisp/emacs-lisp/cl.el	Sun May 22 17:46:50 2005 +0000
@@ -162,7 +162,8 @@
   "(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.
-Keywords supported:  :test :test-not :key"
+\nKeywords supported:  :test :test-not :key
+\n(fn X PLACE [KEYWORD VALUE]...)"
   (if (symbolp place) (list 'setq place (list* 'adjoin x place keys))
     (list* 'callf2 'adjoin x place keys)))
 
@@ -256,7 +257,8 @@
 in place of FORM.  When a non-macro-call results, it is returned.
 
 The second optional arg ENVIRONMENT specifies an environment of macro
-definitions to shadow the loaded ones for use in file byte-compilation."
+definitions to shadow the loaded ones for use in file byte-compilation.
+\n(fn FORM &optional ENVIRONMENT)"
   (let ((cl-macro-environment cl-env))
     (while (progn (setq cl-macro (funcall cl-old-macroexpand cl-macro cl-env))
 		  (and (symbolp cl-macro)
@@ -300,27 +302,27 @@
 
 ;;; Numbers.
 
-(defun floatp-safe (x)
+(defun floatp-safe (object)
   "Return t if OBJECT is a floating point number.
 On Emacs versions that lack floating-point support, this function
 always returns nil."
-  (and (numberp x) (not (integerp x))))
+  (and (numberp object) (not (integerp object))))
 
-(defun plusp (x)
+(defun plusp (number)
   "Return t if NUMBER is positive."
-  (> x 0))
+  (> number 0))
 
-(defun minusp (x)
+(defun minusp (number)
   "Return t if NUMBER is negative."
-  (< x 0))
+  (< number 0))
 
-(defun oddp (x)
+(defun oddp (integer)
   "Return t if INTEGER is odd."
-  (eq (logand x 1) 1))
+  (eq (logand integer 1) 1))
 
-(defun evenp (x)
+(defun evenp (integer)
   "Return t if INTEGER is even."
-  (eq (logand x 1) 0))
+  (eq (logand integer 1) 0))
 
 (defvar *random-state* (vector 'cl-random-state-tag -1 30 (cl-random-time)))
 
@@ -344,7 +346,8 @@
 If there are several SEQs, FUNCTION is called with that many arguments,
 and mapping stops as soon as the shortest list runs out.  With just one
 SEQ, this is like `mapcar'.  With several, it is like the Common Lisp
-`mapcar' function extended to arbitrary sequence types."
+`mapcar' function extended to arbitrary sequence types.
+\n(fn FUNCTION SEQ...)"
   (if cl-rest
       (if (or (cdr cl-rest) (nlistp cl-x) (nlistp (car cl-rest)))
 	  (cl-mapcar-many cl-func (cons cl-x cl-rest))
@@ -503,9 +506,10 @@
 ;;    x))
 
 (defun list* (arg &rest rest)   ; See compiler macro in cl-macs.el
-  "Return a new list with specified args as elements, consed to last arg.
+  "Return a new list with specified ARGs as elements, consed to last ARG.
 Thus, `(list* A B C D)' is equivalent to `(nconc (list A B C) D)', or to
-`(cons A (cons B (cons C D)))'."
+`(cons A (cons B (cons C D)))'.
+\n(fn ARG...)"
   (cond ((not rest) arg)
 	((not (cdr rest)) (cons arg (car rest)))
 	(t (let* ((n (length rest))
@@ -522,8 +526,8 @@
     (nreverse res)))
 
 (defun copy-list (list)
-  "Return a copy of a list, which may be a dotted list.
-The elements of the list are not copied, just the list structure itself."
+  "Return a copy of LIST, which may be a dotted list.
+The elements of LIST are not copied, just the list structure itself."
   (if (consp list)
       (let ((res nil))
 	(while (consp list) (push (pop list) res))
@@ -544,7 +548,8 @@
 (defun adjoin (cl-item cl-list &rest cl-keys)  ; See compiler macro in cl-macs
   "Return ITEM consed onto the front of LIST only if it's not already there.
 Otherwise, return LIST unmodified.
-Keywords supported:  :test :test-not :key"
+\nKeywords supported:  :test :test-not :key
+\n(fn ITEM LIST [KEYWORD VALUE]...)"
   (cond ((or (equal cl-keys '(:test eq))
 	     (and (null cl-keys) (not (numberp cl-item))))
 	 (if (memq cl-item cl-list) cl-list (cons cl-item cl-list)))
@@ -555,7 +560,8 @@
 (defun subst (cl-new cl-old cl-tree &rest cl-keys)
   "Substitute NEW for OLD everywhere in TREE (non-destructively).
 Return a copy of TREE with all elements `eql' to OLD replaced by NEW.
-Keywords supported:  :test :test-not :key"
+\nKeywords supported:  :test :test-not :key
+\n(fn NEW OLD TREE [KEYWORD VALUE]...)"
   (if (or cl-keys (and (numberp cl-old) (not (integerp cl-old))))
       (apply 'sublis (list (cons cl-old cl-new)) cl-tree cl-keys)
     (cl-do-subst cl-new cl-old cl-tree)))