[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110780: Misc small cl doc fixes

[Glenn Morris]

------------------------------------------------------------
revno: 110780
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Mon 2012-11-05 00:29:12 -0800
message:
  Misc small cl doc fixes
  
  * emacs-lisp/cl-extra.el (cl-maplist, cl-mapcan): Doc fix.
  
  * emacs-lisp/cl-extra.el (cl-prettyexpand):
  * emacs-lisp/cl-lib.el (cl-proclaim, cl-declaim):
  * emacs-lisp/cl-macs.el (cl-destructuring-bind, cl-locally)
  (cl-the, cl-compiler-macroexpand): Add basic doc strings.
modified:
  lisp/ChangeLog
  lisp/emacs-lisp/cl-extra.el
  lisp/emacs-lisp/cl-lib.el
  lisp/emacs-lisp/cl-macs.el

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-11-03 18:32:09 +0000
+++ b/lisp/ChangeLog    2012-11-05 08:29:12 +0000
@@ -1,3 +1,12 @@
+2012-11-05  Glenn Morris  <address@hidden>
+
+       * emacs-lisp/cl-extra.el (cl-prettyexpand):
+       * emacs-lisp/cl-lib.el (cl-proclaim, cl-declaim):
+       * emacs-lisp/cl-macs.el (cl-destructuring-bind, cl-locally)
+       (cl-the, cl-compiler-macroexpand): Add basic doc strings.
+
+       * emacs-lisp/cl-extra.el (cl-maplist, cl-mapcan): Doc fix.
+
 2012-11-03  Glenn Morris  <address@hidden>
 
        * emacs-lisp/cl-macs.el (cl-parse-loop-clause):

=== modified file 'lisp/emacs-lisp/cl-extra.el'
--- a/lisp/emacs-lisp/cl-extra.el       2012-10-30 08:03:22 +0000
+++ b/lisp/emacs-lisp/cl-extra.el       2012-11-05 08:29:12 +0000
@@ -131,7 +131,7 @@
 ;;;###autoload
 (defun cl-maplist (cl-func cl-list &rest cl-rest)
   "Map FUNCTION to each sublist of LIST or LISTs.
-Like `mapcar', except applies to lists and their cdr's rather than to
+Like `cl-mapcar', except applies to lists and their cdr's rather than to
 the elements themselves.
 \n(fn FUNCTION LIST...)"
   (if cl-rest
@@ -170,7 +170,7 @@
 
 ;;;###autoload
 (defun cl-mapcan (cl-func cl-seq &rest cl-rest)
-  "Like `mapcar', but nconc's together the values returned by the function.
+  "Like `cl-mapcar', but nconc's together the values returned by the function.
 \n(fn FUNCTION SEQUENCE...)"
   (apply 'nconc (apply 'cl-mapcar cl-func cl-seq cl-rest)))
 
@@ -675,6 +675,9 @@
 
 ;;;###autoload
 (defun cl-prettyexpand (form &optional full)
+  "Expand macros in FORM and insert the pretty-printed result.
+Optional argument FULL non-nil means to expand all macros,
+including `cl-block' and `cl-eval-when'."
   (message "Expanding...")
   (let ((cl--compiling-file full)
        (byte-compile-macro-environment nil))

=== modified file 'lisp/emacs-lisp/cl-lib.el'
--- a/lisp/emacs-lisp/cl-lib.el 2012-10-11 20:36:23 +0000
+++ b/lisp/emacs-lisp/cl-lib.el 2012-11-05 08:29:12 +0000
@@ -251,12 +251,17 @@
 (defvar cl-proclaims-deferred nil)
 
 (defun cl-proclaim (spec)
+  "Record a global declaration specified by SPEC."
   (if (fboundp 'cl-do-proclaim) (cl-do-proclaim spec t)
     (push spec cl-proclaims-deferred))
   nil)
 
 (defmacro cl-declaim (&rest specs)
-  (let ((body (mapcar (function (lambda (x) (list 'cl-proclaim (list 'quote 
x))))
+  "Like `cl-proclaim', but takes any number of unevaluated, unquoted arguments.
+Puts `(cl-eval-when (compile load eval) ...)' around the declarations
+so that they are registered at compile-time as well as run-time."
+  (let ((body (mapcar (function (lambda (x)
+                                  (list 'cl-proclaim (list 'quote x))))
                      specs)))
     (if (cl--compiling-file) (cl-list* 'cl-eval-when '(compile load eval) body)
       (cons 'progn body))))   ; avoid loading cl-macs.el for cl-eval-when

=== modified file 'lisp/emacs-lisp/cl-macs.el'
--- a/lisp/emacs-lisp/cl-macs.el        2012-11-03 18:32:09 +0000
+++ b/lisp/emacs-lisp/cl-macs.el        2012-11-05 08:29:12 +0000
@@ -554,6 +554,7 @@
 
 ;;;###autoload
 (defmacro cl-destructuring-bind (args expr &rest body)
+  "Bind the variables in ARGS to the result of EXPR and execute BODY."
   (declare (indent 2)
            (debug (&define cl-macro-list def-form cl-declarations def-body)))
   (let* ((cl--bind-lets nil) (cl--bind-forms nil) (cl--bind-inits nil)
@@ -1886,10 +1887,12 @@
 
 ;;;###autoload
 (defmacro cl-locally (&rest body)
+  "Equivalent to `progn'."
   (declare (debug t))
   (cons 'progn body))
 ;;;###autoload
 (defmacro cl-the (_type form)
+  "At present this ignores _TYPE and is simply equivalent to FORM."
   (declare (indent 1) (debug (cl-type-spec form)))
   form)
 
@@ -2537,6 +2540,10 @@
 
 ;;;###autoload
 (defun cl-compiler-macroexpand (form)
+  "Like `macroexpand', but for compiler macros.
+Expands FORM repeatedly until no further expansion is possible.
+Returns FORM unchanged if it has no compiler macro, or if it has a
+macro that returns its `&whole' argument."
   (while
       (let ((func (car-safe form)) (handler nil))
        (while (and (symbolp func)