From 5593ed900d0d420f4ee3dd7af3f56b118308a3c0 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Mon, 5 Nov 2012 00:29:12 -0800 Subject: [PATCH] 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. --- lisp/ChangeLog | 9 +++++++++ lisp/emacs-lisp/cl-extra.el | 7 +++++-- lisp/emacs-lisp/cl-lib.el | 7 ++++++- lisp/emacs-lisp/cl-macs.el | 7 +++++++ 4 files changed, 27 insertions(+), 3 deletions(-) diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 5be111818dd..95c407fcdb7 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,12 @@ +2012-11-05 Glenn Morris + + * 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 * 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 c72e3342648..8f801b39d3d 100644 --- 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 122402797e1..e9b30a8f62d 100644 --- 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 8d240774edb..b28f8f7f9e9 100644 --- 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) -- 2.39.5