xemacs-beta: lisp/cl-macs.el comparison

comparison lisp/cl-macs.el @ 4695:fee33ab25966

Add arglist info for autoloaded functions and macros. lisp/ChangeLog addition: 2009-09-20 Aidan Kehoe <kehoea@parhasard.net> Add arglist information to docstrings for autoloaded functions and macros. * hyper-apropos.el (hyper-apropos-get-doc): Treat autoload docstrings like subr docstrings; correct the regexp used. * help.el (describe-function-show-arglist): This no longer treats autoloads specially. (function-arglist): Treat autoload docstrings like subr docstrings. (function-documentation): Treat documentation strings that are zero-length after the arglist has been removed as indicating a lack of documentation. * cl-macs.el (case): (ecase): (typecase): (etypecase): (block): (return): (return-from): (progv): (lexical-let): (lexical-let*): (remf): (callf): (callf2): (define-modify-macro): (deftype): (define-compiler-macro): Rely on the autoload code to always show an arglist for these functions, don't supply an ad-hoc one in the docstring. These changes are for the most obvious functions; there are some missed that would require changing argument names in the docstring or in the function bodies. * autoload.el (make-autoload): Add arg list information to the doc string, using the same approach as for subrs.

author	Aidan Kehoe <kehoea@parhasard.net>
date	Sun, 20 Sep 2009 23:50:05 +0100
parents	2ac296807b88
children	eb1a409c317b

comparison

equal deleted inserted replaced

-:2ac296807b88
+:fee33ab25966
 ;;; Conditional control structures.
 ;;;###autoload
 (defmacro case (expr &rest clauses)
-"(case EXPR CLAUSES...): evals EXPR, chooses from CLAUSES on that value.
+"Evals EXPR, chooses from CLAUSES on that value.
 Each clause looks like (KEYLIST BODY...).  EXPR is evaluated and compared
 against each key in each KEYLIST; the corresponding BODY is evaluated.
 If no clause succeeds, case returns nil.  A single atom may be used in
 place of a KEYLIST of one atom.  A KEYLIST of `t' or `otherwise' is
 allowed only in the final clause, and matches if no other keys match.
 ;; anything to introduce it, as there is probably much more CL stuff
 ;; missing, and the feature is not essential.  --hniksic
 ;;;###autoload
 (defmacro ecase (expr &rest clauses)
-"(ecase EXPR CLAUSES...): like `case', but error if no case fits.
+"Like `case', but error if no case fits.
 `otherwise'-clauses are not allowed."
 ;; XEmacs addition: disallow t and otherwise
 (let ((disallowed (or (assq t clauses)
 			(assq 'otherwise clauses))))
 (if disallowed
 	(error "`%s' is not allowed in ecase" (car disallowed))))
 (list* 'case expr (append clauses '((ecase-error-flag)))))
 ;;;###autoload
 (defmacro typecase (expr &rest clauses)
-"(typecase EXPR CLAUSES...): evals EXPR, chooses from CLAUSES on that value.
+"Evals EXPR, chooses from CLAUSES on that value.
 Each clause looks like (TYPE BODY...).  EXPR is evaluated and, if it
 satisfies TYPE, the corresponding BODY is evaluated.  If no clause succeeds,
 typecase returns nil.  A TYPE of `t' or `otherwise' is allowed only in the
 final clause, and matches if no other keys match."
 (let* ((temp (if (cl-simple-expr-p expr 3) expr (gensym)))
 (if (eq temp expr) body
 (list 'let (list (list temp expr)) body))))
 ;;;###autoload
 (defmacro etypecase (expr &rest clauses)
-"(etypecase EXPR CLAUSES...): like `typecase', but error if no case fits.
+"Like `typecase', but error if no case fits.
 `otherwise'-clauses are not allowed."
 (list* 'typecase expr (append clauses '((ecase-error-flag)))))
 ;;; Blocks and exits.
 ;;;###autoload
 (defmacro block (name &rest body)
-"(block NAME BODY...): define a lexically-scoped block named NAME.
+"Define a lexically-scoped block named NAME.
 NAME may be any symbol.  Code inside the BODY forms can call `return-from'
 to jump prematurely out of the block.  This differs from `catch' and `throw'
 in two respects:  First, the NAME is an unevaluated symbol rather than a
 quoted symbol or other form; and second, NAME is lexically rather than
 dynamically scoped:  Only references to it within BODY will work.  These
 (if cl-found (setcdr cl-found t)))
 (byte-compile-throw (cons 'throw (cdr cl-form)))))
 ;;;###autoload
 (defmacro return (&optional result)
-"(return [RESULT]): return from the block named nil.
+"Return from the block named nil.
 This is equivalent to `(return-from nil RESULT)'."
 (list 'return-from nil result))
 ;;;###autoload
 (defmacro return-from (name &optional result)
-"(return-from NAME [RESULT]): return from the block named NAME.
+"Return from the block named NAME.
 This jumps out to the innermost enclosing `(block NAME ...)' form,
 returning RESULT from that form (or nil if RESULT is omitted).
 This is compatible with Common Lisp, but note that `defun' and
 `defmacro' do not create implicit blocks as they do in Common Lisp."
 (let ((name2 (intern (format "--cl-block-%s--" name))))
 ;;; Binding control structures.
 ;;;###autoload
 (defmacro progv (symbols values &rest body)
-"(progv SYMBOLS VALUES BODY...): bind SYMBOLS to VALUES dynamically in BODY.
+"Bind SYMBOLS to VALUES dynamically in BODY.
 The forms SYMBOLS and VALUES are evaluated, and must evaluate to lists.
 Each SYMBOL in the first list is bound to the corresponding VALUE in the
 second list (or made unbound if VALUES is shorter than SYMBOLS); then the
 BODY forms are executed and their result is returned.  This is much like
 a `let' form, except that the list of symbols can be computed at run-time."
 				cl-macro-environment)))))
 (defvar cl-closure-vars nil)
 ;;;###autoload
 (defmacro lexical-let (bindings &rest body)
-"(lexical-let BINDINGS BODY...): like `let', but lexically scoped.
+"Like `let', but lexically scoped.
 The main visible difference is that lambdas inside BODY will create
 lexical closures as in Common Lisp."
 (let* ((cl-closure-vars cl-closure-vars)
 	 (vars (mapcar #'(lambda (x)
 			   (or (consp x) (setq x (list x)))
 			   vars))
 	    ebody))))
 ;;;###autoload
 (defmacro lexical-let* (bindings &rest body)
-"(lexical-let* BINDINGS BODY...): like `let*', but lexically scoped.
+"Like `let*', but lexically scoped.
 The main visible difference is that lambdas inside BODY will create
 lexical closures as in Common Lisp."
 (if (null bindings) (cons 'progn body)
 (setq bindings (reverse bindings))
 (while bindings
 		  (list 'car temp)
 		  (cl-setf-do-store (nth 1 method) (list 'cdr temp)))))))
 ;;;###autoload
 (defmacro remf (place tag)
-"(remf PLACE TAG): remove TAG from property list PLACE.
+"Remove TAG from property list PLACE.
 PLACE may be a symbol, or any generalized variable allowed by `setf'.
 The form returns true if TAG was found and removed, nil otherwise."
 (let* ((method (cl-setf-do-modify place t))
 	 (tag-temp (and (not (cl-const-expr-p tag)) (gensym "--remf-tag--")))
 	 (val-temp (and (not (cl-simple-expr-p place))
 (setq body (list (list* 'letf (list (pop bindings)) body))))
 (car body)))
 ;;;###autoload
 (defmacro callf (func place &rest args)
-"(callf FUNC PLACE ARGS...): set PLACE to (FUNC PLACE ARGS...).
+"Set PLACE to (FUNC PLACE ARGS...).
 FUNC should be an unquoted function name.  PLACE may be a symbol,
 or any generalized variable allowed by `setf'."
 (let* ((method (cl-setf-do-modify place (cons 'list args)))
 	 (rargs (cons (nth 2 method) args)))
 (list 'let* (car method)
 			      (list* 'funcall (list 'function func)
 				     rargs))))))
 ;;;###autoload
 (defmacro callf2 (func arg1 place &rest args)
-"(callf2 FUNC ARG1 PLACE ARGS...): set PLACE to (FUNC ARG1 PLACE ARGS...).
+"Set PLACE to (FUNC ARG1 PLACE ARGS...).
 Like `callf', but PLACE is the second argument of FUNC, not the first."
 (if (and (cl-safe-expr-p arg1) (cl-simple-expr-p place) (symbolp func))
 (list 'setf place (list* func arg1 place args))
 (let* ((method (cl-setf-do-modify place (cons 'list args)))
 	   (temp (and (not (cl-const-expr-p arg1)) (gensym "--arg1--")))
 				(list* 'funcall (list 'function func)
 				       rargs)))))))
 ;;;###autoload
 (defmacro define-modify-macro (name arglist func &optional doc)
-"(define-modify-macro NAME ARGLIST FUNC): define a `setf'-like modify macro.
+"Define a `setf'-like modify macro.
 If NAME is called, it combines its PLACE argument with the other arguments
 from ARGLIST using FUNC: (define-modify-macro incf (&optional (n 1)) +)"
 (if (memq '&key arglist) (error "&key not allowed in define-modify-macro"))
 (let ((place (gensym "--place--")))
 (list 'defmacro* name (cons place arglist) doc
 ;;; Types and assertions.
 ;;;###autoload
 (defmacro deftype (name arglist &rest body)
-"(deftype NAME ARGLIST BODY...): define NAME as a new data type.
+"Define NAME as a new data type.
 The type name can then be used in `typecase', `check-type', etc."
 (list 'eval-when '(compile load eval)
 	(cl-transform-function-property
 	 name 'cl-deftype-handler (cons (list* '&cl-defs ''('*) arglist) body))))
 ;;; Compiler macros.
 ;;;###autoload
 (defmacro define-compiler-macro (func args &rest body)
-"(define-compiler-macro FUNC ARGLIST BODY...): Define a compiler-only macro.
+"Define a compiler-only macro.
 This is like `defmacro', but macro expansion occurs only if the call to
 FUNC is compiled (i.e., not interpreted).  Compiler macros should be used
 for optimizing the way calls to FUNC are compiled; the form returned by
 BODY should do the same thing as a call to the normal function called
 FUNC, though possibly more efficiently.  Note that, like regular macros,

Mercurial > hg > xemacs-beta

comparison lisp/cl-macs.el @ 4695:fee33ab25966