--- a/lisp/ChangeLog	Sun Sep 20 21:41:22 2009 +0100
+++ b/lisp/ChangeLog	Sun Sep 20 23:50:05 2009 +0100
@@ -1,3 +1,41 @@
+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.
+
 2009-09-20  Aidan Kehoe  <kehoea@parhasard.net>
 
 	* help.el (function-arglist): 

--- a/lisp/autoload.el	Sun Sep 20 21:41:22 2009 +0100
+++ b/lisp/autoload.el	Sun Sep 20 23:50:05 2009 +0100
@@ -283,8 +283,17 @@
      ((memq car autoload-make-autoload-operators)
       (let* ((macrop (memq car '(defmacro defmacro*)))
 	     (name (nth 1 form))
+             (arglist (nth 2 form))
 	     (body (nthcdr (get car 'doc-string-elt) form))
-	     (doc (if (stringp (car body)) (pop body))))
+             (placeholder (eval-when-compile (gensym)))
+             (doc (concat (if (stringp (car body))
+                              (pop body)
+                            "")
+                          "\n\narguments: "
+                          (replace-in-string
+                           (cl-function-arglist placeholder arglist)
+                           (format "^(%s ?" placeholder)
+                           "(") "\n")))
 	;; `define-generic-mode' quotes the name, so take care of that
 	(list 'autoload (if (listp name) name (list 'quote name)) file doc
 	      (or (and (memq car '(define-skeleton define-derived-mode

--- a/lisp/cl-macs.el	Sun Sep 20 21:41:22 2009 +0100
+++ b/lisp/cl-macs.el	Sun Sep 20 23:50:05 2009 +0100
@@ -610,7 +610,7 @@
 
 ;;;###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
@@ -655,7 +655,7 @@
 
 ;;;###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)
@@ -666,7 +666,7 @@
 
 ;;;###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
@@ -691,7 +691,7 @@
 
 ;;;###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)))))
 
@@ -700,7 +700,7 @@
 
 ;;;###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
@@ -742,13 +742,13 @@
 
 ;;;###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
@@ -1703,7 +1703,7 @@
 
 ;;;###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
@@ -1792,7 +1792,7 @@
 (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)
@@ -1832,7 +1832,7 @@
 
 ;;;###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)
@@ -2521,7 +2521,7 @@
 
 ;;;###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))
@@ -2660,7 +2660,7 @@
 
 ;;;###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)))
@@ -2673,7 +2673,7 @@
 
 ;;;###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))
@@ -2688,7 +2688,7 @@
 
 ;;;###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"))
@@ -2942,7 +2942,7 @@
 
 ;;;###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
@@ -3050,7 +3050,7 @@
 
 ;;;###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

--- a/lisp/help.el	Sun Sep 20 21:41:22 2009 +0100
+++ b/lisp/help.el	Sun Sep 20 23:50:05 2009 +0100
@@ -1087,8 +1087,7 @@
 ;; Default to nil for the non-hackers?  Not until we find a way to
 ;; distinguish hackers from non-hackers automatically!
 (defcustom describe-function-show-arglist t
-  "*If non-nil, describe-function will show its arglist,
-unless the function is autoloaded."
+  "*If non-nil, describe-function will show the function's arglist."
   :type 'boolean
   :group 'help-appearance)
 
@@ -1188,7 +1187,7 @@
 		 (compiled-function-arglist fndef))
 		((eq (car-safe fndef) 'lambda)
 		 (nth 1 fndef))
-		((subrp fndef)
+		((or (subrp fndef) (eq 'autoload (car-safe fndef)))
 		 (let* ((doc (documentation function))
 			(args (and doc
 				   (string-match
@@ -1227,9 +1226,10 @@
 		     (gettext "not documented"))
 	       (void-function "(alias for undefined function)")
 	       (error "(unexpected error from `documention')"))))
-    (if (and strip-arglist
-	     (string-match "[\n\t ]*\narguments: ?(\\([^)]*\\))\n?\\'" doc))
-	(setq doc (substring doc 0 (match-beginning 0))))
+    (when (and strip-arglist
+               (string-match "[\n\t ]*\narguments: ?(\\([^)]*\\))\n?\\'" doc))
+      (setq doc (substring doc 0 (match-beginning 0)))
+      (and (zerop (length doc)) (setq doc (gettext "not documented"))))
     doc))
 
 ;; replacement for `princ' that puts the text in the specified face,

--- a/lisp/hyper-apropos.el	Sun Sep 20 21:41:22 2009 +0100
+++ b/lisp/hyper-apropos.el	Sun Sep 20 23:50:05 2009 +0100
@@ -807,9 +807,9 @@
 		       ((eq symtype 'bytecode)
 			(princ (or (compiled-function-arglist newsym)
 				   "()")))
-		       ((and (eq symtype 'subr)
+		       ((and (or (eq symtype 'subr) (eq symtype 'autoload))
 			     (string-match
-			      "[\n\t ]*\narguments: ?\\((.*)\\)\n?\\'"
+                              "[\n\t ]*\narguments: ?(\\([^)]*\\))\n?\\'"
 			      doc))
 			(insert (substring doc
 					   (match-beginning 1)