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.

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 5be111818dd3dd83e15a06b8a351b1bba8b5556a..95c407fcdb7c88f8bdf930b7d6bb2396e0aeeb7c 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,12 @@
+2012-11-05  Glenn Morris  <rgm@gnu.org>
+
+       * 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  <rgm@gnu.org>
 
        * emacs-lisp/cl-macs.el (cl-parse-loop-clause):

diff --git a/lisp/emacs-lisp/cl-extra.el b/lisp/emacs-lisp/cl-extra.el
index c72e33426482a335739786c20bc3859d3fe8d47f..8f801b39d3d8696f131c76bcde6a22bfd349caf4 100644 (file)
--- a/lisp/emacs-lisp/cl-extra.el
+++ b/lisp/emacs-lisp/cl-extra.el
@@ -131,7 +131,7 @@ TYPE is the sequence type to return.
 ;;;###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 @@ the elements themselves.
 
 ;;;###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 @@ PROPLIST is a list of the sort returned by `symbol-plist'.
 
 ;;;###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))

diff --git a/lisp/emacs-lisp/cl-lib.el b/lisp/emacs-lisp/cl-lib.el
index 122402797e10cb16cab3898b569942e3c07ffbca..e9b30a8f62d2ac9ddc500209277656c70439000e 100644 (file)
--- a/lisp/emacs-lisp/cl-lib.el
+++ b/lisp/emacs-lisp/cl-lib.el
@@ -251,12 +251,17 @@ one value.
 (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

diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index 8d240774edb17cb9ad5df3d75b50193926c3fe24..b28f8f7f9e9db19c03c011f0bc8f5f223b699c53 100644 (file)
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -554,6 +554,7 @@ its argument list allows full Common Lisp conventions."
 
 ;;;###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 @@ values.  For compatibility, (cl-values A B C) is a synonym for (list A B C).
 
 ;;;###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 @@ and then returning foo."
 
 ;;;###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)