Common Lisp lambda list in help.
Description.
This paper contains proposal to include information on CL lambda list of
defun*-ed functions in documentation.
State of art.
Current implementation of defun* and defmacro* does not allow user to learn
function/macro arglist via documentation.
Lets consider the following code:
(defun* tmp-cl-func (x y &optional (a b c) &key d)
"Some docs"
(progn nil))
After evaluation of this code the documentation on tmp-cl-func says:
----------------------------------------
`tmp-cl-func' is a Lisp function
(tmp-cl-func X Y &rest --REST--48142)
Documentation:
Some docs
----------------------------------------
This info stores no information on the actual arguments list of
`tmp-cl-func'.
Proposal.
I propose to modify defun*/defmacro* -related code to add information on
function/macro Common Lisp arguments list to on-line documentation on
function/macros they produce.
Simple implementation.
One very simple way to solve the problem is to add arguments list directly to
documentation strings. See patch below.
In the case with `tmp-cl-func' it gives:
----------------------------------------
`tmp-cl-func' is a Lisp function
(tmp-cl-func X Y &rest --REST--48144)
Documentation:
Common Lisp lambda list:
(tmp-cl-func X Y &optional (A B C) &key D)
Some docs
----------------------------------------
The drawback is that confusingly looking "&rest --REST--48144" is still
displayed.
The second observation is that argument list description should not be a part
of doc string. Docstrings are written manually and describes functionality
of function/macro. Arglist description is just signature of function and
should be generated by system in run-time.
Nick.
Index: cl-macs.el
===================================================================
RCS file: /usr/CVSroot/XEmacs/xemacs/lisp/cl-macs.el,v
retrieving revision 1.4.2.15
diff -u -r1.4.2.15 cl-macs.el
--- cl-macs.el 2000/12/01 09:54:30 1.4.2.15
+++ cl-macs.el 2001/01/10 17:44:12
＠＠ -150,11 +150,33 ＠＠
(defvar bind-block) (defvar bind-defs) (defvar bind-enquote)
(defvar bind-inits) (defvar bind-lets) (defvar bind-forms)
+(defun cl-upcase-arg (arg)
+ (cond ((symbolp arg)
+ (if (memq arg lambda-list-keywords)
+ arg
+ (intern (upcase (symbol-name arg)))))
+ ((listp arg)
+ (mapcar 'cl-upcase-arg arg))))
+
+(defun cl-function-arglist (function agrlist)
+ (prin1-to-string
+ (cons function (cl-upcase-arg agrlist))))
+
(defun cl-transform-lambda (form bind-block)
(let* ((args (car form)) (body (cdr form))
(bind-defs nil) (bind-enquote nil)
(bind-inits nil) (bind-lets nil) (bind-forms nil)
- (header nil) (simple-args nil))
+ (header nil) (simple-args nil)
+ (doc ""))
+ ;; Add CL lambda list to documentation
+ (if (stringp (car body))
+ (setq doc (cl-pop body)))
+ (cl-push (concat "\nCommon Lisp lambda list:\n"
+ " " (cl-function-arglist bind-block args)
+ "\n\n"
+ doc)
+ header)
+
(while (or (stringp (car body)) (eq (car-safe (car body)) 'interactive))
(cl-push (cl-pop body) header))
(setq args (if (listp args) (copy-list args) (list '&rest args)))