Doc and message fixes.

(message-send-rename-function)
(message-make-forward-subject-function)
(message-send-mail-function, message-reply-to-function)
(message-wide-reply-to-function, message-followup-to-function)
(message-distribution-function, message-auto-save-directory): Fix
:type.

1 files changed, 87 insertions, 81 deletions

diff --git a/lisp/gnus/message.el b/lisp/gnus/message.el
index 589f205c947..673c949a9ae 100644
--- a/lisp/gnus/message.el
+++ b/lisp/gnus/message.el
@@ -112,7 +112,7 @@
 (defcustom message-send-rename-function nil
   "Function called to rename the buffer after sending it."
   :group 'message-buffers
-  :type 'function)
+  :type '(choice function (const nil)))
 
 (defcustom message-fcc-handler-function 'message-output
   "*A function called to save outgoing articles.
@@ -141,7 +141,7 @@ If this variable is nil, no such courtesy message will be added."
 (defcustom message-from-style 'default
   "*Specifies how \"From\" headers look.
 
-If `nil', they contain just the return address like:
+If nil, they contain just the return address like:
         king@grassland.com
 If `parens', they look like:
         king@grassland.com (Elvis Parsley)
@@ -164,13 +164,14 @@ To disable checking of long signatures, for instance, add
 
 Don't touch this variable unless you really know what you're doing.
 
-Checks include subject-cmsg multiple-headers sendsys message-id from
-long-lines control-chars size new-text quoting-style
-redirected-followup signature approved sender empty empty-headers
-message-id from subject shorten-followup-to existing-newsgroups
-buffer-file-name unchanged newsgroups."
+Checks include `subject-cmsg', `multiple-headers', `sendsys',
+`message-id', `from', `long-lines', `control-chars', `size',
+`new-text', `quoting-style', `redirected-followup', `signature',
+`approved', `sender', `empty', `empty-headers', `message-id', `from',
+`subject', `shorten-followup-to', `existing-newsgroups',
+`buffer-file-name', `unchanged', `newsgroups'."
   :group 'message-news
-  :type '(repeat sexp))
+  :type '(repeat sexp))                 ; Fixme: improve this
 
 (defcustom message-required-news-headers
   '(From Newsgroups Subject Date Message-ID
@@ -244,7 +245,7 @@ nil means let mailer mail back a message to report errors."
   :type 'boolean)
 
 (defcustom message-generate-new-buffers 'unique
-  "*Non-nil means that a new message buffer will be created whenever `message-setup' is called.
+  "*Non-nil means create a new message buffer whenever `message-setup' is called.
 If this is a function, call that function with three parameters:  The type,
 the to address and the group name.  (Any of these may be nil.)  The function
 should return the new buffer name."
@@ -281,19 +282,20 @@ If t, use `message-user-organization-file'."
 
 (defcustom message-make-forward-subject-function
   'message-forward-subject-author-subject
-  "*A list of functions that are called to generate a subject header for forwarded messages.
+  "*List of functions called to generate subject headers for forwarded messages.
 The subject generated by the previous function is passed into each
 successive function.
 
 The provided functions are:
 
-* message-forward-subject-author-subject (Source of article (author or
+* `message-forward-subject-author-subject' (Source of article (author or
       newsgroup)), in brackets followed by the subject
-* message-forward-subject-fwd (Subject of article with 'Fwd:' prepended
+* `message-forward-subject-fwd' (Subject of article with 'Fwd:' prepended
       to it."
   :group 'message-forwarding
   :type '(radio (function-item message-forward-subject-author-subject)
-                (function-item message-forward-subject-fwd)))
+                (function-item message-forward-subject-fwd)
+                (repeat :tag "List of functions" function)))
 
 (defcustom message-forward-as-mime t
   "*If non-nil, forward messages as an inline/rfc822 MIME section.  Otherwise, directly inline the old message in the forwarded message."
@@ -347,12 +349,15 @@ The headers should be delimited by a line whose contents match the
 variable `mail-header-separator'.
 
 Valid values include `message-send-mail-with-sendmail' (the default),
-`message-send-mail-with-mh', `message-send-mail-with-qmail' and
-`smtpmail-send-it'."
+`message-send-mail-with-mh', `message-send-mail-with-qmail',
+`smtpmail-send-it' and `feedmail-send-it'.
+
+See also `send-mail-function'."
   :type '(radio (function-item message-send-mail-with-sendmail)
                 (function-item message-send-mail-with-mh)
                 (function-item message-send-mail-with-qmail)
                 (function-item smtpmail-send-it)
+                (function-item feedmail-send-it)
                 (function :tag "Other"))
   :group 'message-sending
   :group 'message-mail)
@@ -366,25 +371,25 @@ variable `mail-header-separator'."
   :type 'function)
 
 (defcustom message-reply-to-function nil
-  "Function that should return a list of headers.
+  "If non-nil, function that should return a list of headers.
 This function should pick out addresses from the To, Cc, and From headers
 and respond with new To and Cc headers."
   :group 'message-interface
-  :type 'function)
+  :type '(choice function (const nil)))
 
 (defcustom message-wide-reply-to-function nil
-  "Function that should return a list of headers.
+  "If non-nil, function that should return a list of headers.
 This function should pick out addresses from the To, Cc, and From headers
 and respond with new To and Cc headers."
   :group 'message-interface
-  :type 'function)
+  :type '(choice function (const nil)))
 
 (defcustom message-followup-to-function nil
-  "Function that should return a list of headers.
+  "If non-nil, function that should return a list of headers.
 This function should pick out addresses from the To, Cc, and From headers
 and respond with new To and Cc headers."
   :group 'message-interface
-  :type 'function)
+  :type '(choice function (const nil)))
 
 (defcustom message-use-followup-to 'ask
   "*Specifies what to do with Followup-To header.
@@ -398,7 +403,7 @@ always query the user whether to use the value.  If it is the symbol
                  (const ask)))
 
 (defcustom message-sendmail-f-is-evil nil
-  "*Non-nil means that \"-f username\" should not be added to the sendmail command line.
+  "*Non-nil means don't add \"-f username\" to the sendmail command line.
 Doing so would be even more evil than leaving it out."
   :group 'message-sending
   :type 'boolean)
@@ -542,7 +547,7 @@ If a form, the result from the form will be used instead."
   "*Function called to return a Distribution header."
   :group 'message-news
   :group 'message-headers
-  :type 'function)
+  :type '(choice function (const nil)))
 
 (defcustom message-expires 14
   "Number of days before your article expires."
@@ -664,7 +669,7 @@ mail aliases off."
   "*Directory where Message auto-saves buffers if Gnus isn't running.
 If nil, Message won't auto-save."
   :group 'message-buffers
-  :type 'directory)
+  :type '(choice directory (const :tag "Don't auto-save" nil)))
 
 (defcustom message-buffer-naming-style 'unique
   "*The way new message buffers are named.
@@ -674,7 +679,7 @@ Valid valued are `unique' and `unsent'."
   :type '(choice (const :tag "unique" unique)
                  (const :tag "unsent" unsent)))
 
-(defcustom message-default-charset 
+(defcustom message-default-charset
   (and (not (mm-multibyte-p)) 'iso-8859-1)
   "Default charset used in non-MULE Emacsen.
 If nil, you might be asked to input the charset."
@@ -682,7 +687,7 @@ If nil, you might be asked to input the charset."
   :group 'message
   :type 'symbol)
 
-(defcustom message-dont-reply-to-names 
+(defcustom message-dont-reply-to-names
   (and (boundp 'rmail-dont-reply-to-names) rmail-dont-reply-to-names)
   "*A regexp specifying names to prune when doing wide replies.
 A value of nil means exclude your own name only."
@@ -904,8 +909,8 @@ The cdr of ech entry is a function for applying the face to a region.")
 
 (defcustom message-send-mail-partially-limit 1000000
   "The limitation of messages sent as message/partial.
-The lower bound of message size in characters, beyond which the message 
-should be sent in several parts. If it is nil, the size is unlimited."
+The lower bound of message size in characters, beyond which the message
+should be sent in several parts.  If it is nil, the size is unlimited."
   :version "21.1"
   :group 'message-buffers
   :type '(choice (const :tag "unlimited" nil)
@@ -920,7 +925,7 @@ The first matched address (not primary one) is used in the From field."
 
 (defcustom message-mail-user-agent nil
   "Like `mail-user-agent'.
-Except if it is `nil', use Gnus native MUA; if it is t, use
+Except if it is nil, use Gnus native MUA; if it is t, use
 `mail-user-agent'."
   :type '(radio (const :tag "Gnus native"
                        :format "%t\n"
@@ -1061,19 +1066,19 @@ Except if it is `nil', use Gnus native MUA; if it is t, use
 ;;;
 
 (defmacro message-y-or-n-p (question show &rest text)
-  "Ask QUESTION, displaying the rest of the arguments in a temp. buffer if SHOW"
+  "Ask QUESTION, displaying remaining args in a temporary buffer if SHOW."
   `(message-talkative-question 'y-or-n-p ,question ,show ,@text))
 
-;; Delete the current line (and the next N lines.);
 (defmacro message-delete-line (&optional n)
+  "Delete the current line (and the next N lines)."
   `(delete-region (progn (beginning-of-line) (point))
                   (progn (forward-line ,(or n 1)) (point))))
 
 (defun message-unquote-tokens (elems)
-  "Remove double quotes (\") from strings in list."
+  "Remove double quotes (\") from strings in list ELEMS."
   (mapcar (lambda (item)
             (while (string-match "^\\(.*\\)\"\\(.*\\)$" item)
-              (setq item (concat (match-string 1 item) 
+              (setq item (concat (match-string 1 item)
                                  (match-string 2 item))))
             item)
           elems))
@@ -1163,7 +1168,7 @@ is used by default."
 
 
 (defun message-fetch-reply-field (header)
-  "Fetch FIELD from the message we're replying to."
+  "Fetch field HEADER from the message we're replying to."
   (when (and message-reply-buffer
              (buffer-name message-reply-buffer))
     (save-excursion
@@ -1186,12 +1191,12 @@ is used by default."
       (byte-code-function-p form)))
 
 (defun message-strip-list-identifiers (subject)
-  "Remove list identifiers in `gnus-list-identifiers'."
+  "Remove list identifiers in `gnus-list-identifiers' from string SUBJECT."
   (require 'gnus-sum)                   ; for gnus-list-identifiers
   (let ((regexp (if (stringp gnus-list-identifiers)
                     gnus-list-identifiers
                   (mapconcat 'identity gnus-list-identifiers " *\\|"))))
-    (if (string-match (concat "\\(\\(\\(Re: +\\)?\\(" regexp 
+    (if (string-match (concat "\\(\\(\\(Re: +\\)?\\(" regexp
                                 " *\\)\\)+\\(Re: +\\)?\\)") subject)
         (concat (substring subject 0 (match-beginning 1))
                 (or (match-string 3 subject)
@@ -1201,14 +1206,14 @@ is used by default."
       subject)))
 
 (defun message-strip-subject-re (subject)
-  "Remove \"Re:\" from subject lines."
+  "Remove \"Re:\" from subject lines in string SUBJECT."
   (if (string-match message-subject-re-regexp subject)
       (substring subject (match-end 0))
     subject))
 
 (defun message-remove-header (header &optional is-regexp first reverse)
   "Remove HEADER in the narrowed buffer.
-If REGEXP, HEADER is a regular expression.
+If IS-REGEXP, HEADER is a regular expression.
 If FIRST, only remove the first instance of the header.
 Return the number of headers removed."
   (goto-char (point-min))
@@ -1264,7 +1269,7 @@ Return the number of headers removed."
   (goto-char (point-min)))
 
 (defun message-narrow-to-head-1 ()
-  "Like `message-narrow-to-head'. Don't widen."
+  "Like `message-narrow-to-head'.  Don't widen."
   (narrow-to-region
    (goto-char (point-min))
    (if (search-forward "\n\n" nil 1)
@@ -1463,9 +1468,9 @@ Point is left at the beginning of the narrowed-to region."
 ;;;###autoload
 (defun message-mode ()
   "Major mode for editing mail and news to be sent.
-Like Text Mode but with these additional commands:
-C-c C-s  message-send (send the message)    C-c C-c  message-send-and-exit
-C-c C-d  Postpone sending the message        C-c C-k  Kill the message
+Like Text Mode but with these additional commands:\\<message-mode-map>
+C-c C-s  `message-send' (send the message)  C-c C-c  `message-send-and-exit'
+C-c C-d  Postpone sending the message       C-c C-k  Kill the message
 C-c C-f  move to a header field (and create it if there isn't):
          C-c C-f C-t  move to To        C-c C-f C-s  move to Subject
          C-c C-f C-c  move to Cc        C-c C-f C-b  move to Bcc
@@ -1473,19 +1478,19 @@ C-c C-f  move to a header field (and create it if there isn't):
          C-c C-f C-u  move to Summary   C-c C-f C-n  move to Newsgroups
          C-c C-f C-k  move to Keywords  C-c C-f C-d  move to Distribution
          C-c C-f C-f  move to Followup-To
-C-c C-t  message-insert-to (add a To header to a news followup)
-C-c C-n  message-insert-newsgroups (add a Newsgroup header to a news reply)
-C-c C-b  message-goto-body (move to beginning of message text).
-C-c C-i  message-goto-signature (move to the beginning of the signature).
-C-c C-w  message-insert-signature (insert `message-signature-file' file).
-C-c C-y  message-yank-original (insert current message, if any).
-C-c C-q  message-fill-yanked-message (fill what was yanked).
-C-c C-e  message-elide-region (elide the text between point and mark).
-C-c C-v  message-delete-not-region (remove the text outside the region).
-C-c C-z  message-kill-to-signature (kill the text up to the signature).
-C-c C-r  message-caesar-buffer-body (rot13 the message body).
-C-c C-a  mml-attach-file (attach a file as MIME).
-M-RET    message-newline-and-reformat (break the line and reformat)."
+C-c C-t  `message-insert-to' (add a To header to a news followup)
+C-c C-n  `message-insert-newsgroups' (add a Newsgroup header to a news reply)
+C-c C-b  `message-goto-body' (move to beginning of message text).
+C-c C-i  `message-goto-signature' (move to the beginning of the signature).
+C-c C-w  `message-insert-signature' (insert `message-signature-file' file).
+C-c C-y  `message-yank-original' (insert current message, if any).
+C-c C-q  `message-fill-yanked-message' (fill what was yanked).
+C-c C-e  `message-elide-region' (elide the text between point and mark).
+C-c C-v  `message-delete-not-region' (remove the text outside the region).
+C-c C-z  `message-kill-to-signature' (kill the text up to the signature).
+C-c C-r  `message-caesar-buffer-body' (rot13 the message body).
+C-c C-a  `mml-attach-file' (attach a file as MIME).
+M-RET    `message-newline-and-reformat' (break the line and reformat)."
   (interactive)
   (if (local-variable-p 'mml-buffer-list (current-buffer))
       (mml-destroy-buffers))
@@ -1720,7 +1725,7 @@ With the prefix argument FORCE, insert the header anyway."
 ;;; Various commands
 
 (defun message-delete-not-region (beg end)
-  "Delete everything in the body of the current message that is outside of the region."
+  "Delete everything in the body of the current message outside of the region."
   (interactive "r")
   (save-excursion
     (goto-char end)
@@ -1771,7 +1776,7 @@ With the prefix argument FORCE, insert the header anyway."
     (forward-line 1)))
 
 (defun message-insert-signature (&optional force)
-  "Insert a signature.  See documentation for the `message-signature' variable."
+  "Insert a signature.  See documentation for variable `message-signature'."
   (interactive (list 0))
   (let* ((signature
           (cond
@@ -1808,7 +1813,7 @@ With the prefix argument FORCE, insert the header anyway."
       (or (bolp) (insert "\n")))))
 
 (defun message-elide-region (b e)
-  "Elide the text between point and mark.
+  "Elide the text in the region.
 An ellipsis (from `message-elide-ellipsis') will be inserted where the
 text was killed."
   (interactive "r")
@@ -1818,7 +1823,7 @@ text was killed."
 (defvar message-caesar-translation-table nil)
 
 (defun message-caesar-region (b e &optional n)
-  "Caesar rotation of region by N, default 13, for decrypting netnews."
+  "Caesar rotate region B to E by N, default 13, for decrypting netnews."
   (interactive
    (list
     (min (point) (or (mark t) (point)))
@@ -1852,8 +1857,8 @@ text was killed."
      (substring table (+ ?a 26) 255))))
 
 (defun message-caesar-buffer-body (&optional rotnum)
-  "Caesar rotates all letters in the current buffer by 13 places.
-Used to encode/decode possiblyun offensive messages (commonly in net.jokes).
+  "Caesar rotate all letters in the current buffer by 13 places.
+Used to encode/decode possibly offensive messages (commonly in rec.humor).
 With prefix arg, specifies the number of places to rotate each letter forward.
 Mail and USENET news headers are not rotated."
   (interactive (if current-prefix-arg
@@ -2046,7 +2051,7 @@ prefix, and don't delete any headers."
         (funcall message-citation-line-function)))))
 
 (defun message-insert-citation-line ()
-  "Function that inserts a simple citation line."
+  "Insert a simple citation line."
   (when message-reply-headers
     (insert (mail-header-from message-reply-headers) " writes:\n\n")))
 
@@ -2141,7 +2146,7 @@ The text will also be indented the normal way."
       (message-do-actions actions))))
 
 (defun message-bury (buffer)
-  "Bury this mail buffer."
+  "Bury this mail BUFFER."
   (let ((newbuf (other-buffer buffer)))
     (bury-buffer buffer)
     (if (and (fboundp 'frame-parameters)
@@ -2362,7 +2367,7 @@ It should typically alter the sending method in some way or other."
           ;; require one newline at the end.
           (or (= (preceding-char) ?\n)
               (insert ?\n))
-          (when 
+          (when
               (save-restriction
                 (message-narrow-to-headers)
                 (and news
@@ -2375,7 +2380,7 @@ It should typically alter the sending method in some way or other."
             (message-insert-courtesy-copy))
           (if (or (not message-send-mail-partially-limit)
                   (< (point-max) message-send-mail-partially-limit)
-                  (not (y-or-n-p "The message size is too large, should it be sent partially?")))
+                  (not (y-or-n-p "The message size is too large, should it be sent partially? ")))
               (mm-with-unibyte-current-buffer
                 (funcall message-send-mail-function))
             (message-send-mail-partially)))
@@ -2527,7 +2532,7 @@ to find out how to use this."
                     message-syntax-checks)
             message-syntax-checks))
          (message-this-is-news t)
-         (message-posting-charset (gnus-setup-posting-charset 
+         (message-posting-charset (gnus-setup-posting-charset
                                    (save-restriction
                                      (message-narrow-to-headers-or-head)
                                      (message-fetch-field "Newsgroups"))))
@@ -2554,7 +2559,7 @@ to find out how to use this."
               (erase-buffer)
               ;; Avoid copying text props.
               (insert (with-current-buffer messbuf
-                        (buffer-substring-no-properties 
+                        (buffer-substring-no-properties
                          (point-min) (point-max))))
               (message-encode-message-body)
               ;; Remove some headers.
@@ -2595,7 +2600,7 @@ to find out how to use this."
 ;;;
 
 (defun message-check-element (type)
-  "Returns non-nil if this type is not to be checked."
+  "Return non-nil if this TYPE is not to be checked."
   (if (eq message-syntax-checks 'dont-check-for-anything-just-trust-me)
       t
     (let ((able (assq type message-syntax-checks)))
@@ -2737,7 +2742,7 @@ to find out how to use this."
              t
            (y-or-n-p
             (format
-             "Really post to %s unknown group%s: %s "
+             "Really post to %s unknown group%s: %s? "
              (if (= (length errors) 1) "this" "these")
              (if (= (length errors) 1) "" "s")
              (mapconcat 'identity errors ", ")))))))
@@ -2939,7 +2944,7 @@ to find out how to use this."
       (kill-buffer (current-buffer)))))
 
 (defun message-output (filename)
-  "Append this article to Unix/babyl mail file.."
+  "Append this article to Unix/babyl mail file FILENAME."
   (if (and (file-readable-p filename)
            (mail-file-babyl-p filename))
       (gnus-output-to-rmail filename t)
@@ -3433,7 +3438,7 @@ Headers already prepared in the buffer are not modified."
       (goto-char (point-max)))))
 
 (defun message-shorten-1 (list cut surplus)
-  ;; Cut SURPLUS elements out of LIST, beginning with CUTth one.
+  "Cut SURPLUS elements out of LIST, beginning with CUTth one."
   (setcdr (nthcdr (- cut 2) list)
           (nthcdr (+ (- cut 2) surplus 1) list)))
 
@@ -3606,13 +3611,13 @@ than 988 characters long, and if they are not, trim them until they are."
         (setq to (cdr field))
         (setq headers (delq field headers)))
       (let ((mail-user-agent mua))
-        (compose-mail to subject 
+        (compose-mail to subject
                       (mapcar (lambda (item)
                                 (cons
                                  (format "%s" (car item))
                                  (cdr item)))
                               headers)
-                      nil switch-function yank-action actions))))) 
+                      nil switch-function yank-action actions)))))
  
 (eval-when-compile (defvar mc-modes-alist))
 (defun message-setup-1 (headers &optional replybuffer actions)
@@ -4099,7 +4104,8 @@ header line with the old Message-ID."
 ;;; Washing Subject:
 
 (defun message-wash-subject (subject)
-  "Remove junk like \"Re:\", \"(fwd)\", etc. that was added to the subject by previous forwarders, replyers, etc."
+  "Remove junk like \"Re:\", \"(fwd)\", etc. added to subject string SUBJECT.
+Previous forwarders, replyers, etc. may add it."
   (with-temp-buffer
     (insert-string subject)
     (goto-char (point-min))
@@ -4131,7 +4137,7 @@ header line with the old Message-ID."
 ;;; Forwarding messages.
 
 (defun message-forward-subject-author-subject (subject)
-  "Generate a subject for a forwarded message.
+  "Generate a SUBJECT for a forwarded message.
 The form is: [Source] Subject, where if the original message was mail,
 Source is the sender, and if the original message was news, Source is
 the list of newsgroups is was posted to."
@@ -4142,7 +4148,7 @@ the list of newsgroups is was posted to."
           "] " subject))
 
 (defun message-forward-subject-fwd (subject)
-  "Generate a subject for a forwarded message.
+  "Generate a SUBJECT for a forwarded message.
 The form is: Fwd: Subject, where Subject is the original subject of
 the message."
   (concat "Fwd: " subject))
@@ -4239,7 +4245,7 @@ Optional DIGEST will use digest to forward."
           (save-restriction
             (narrow-to-region b e)
             (goto-char b)
-            (narrow-to-region (point) 
+            (narrow-to-region (point)
                               (or (search-forward "\n\n" nil t) (point)))
             (delete-region (point-min) (point-max)))
         (when (and (not current-prefix-arg)
@@ -4247,7 +4253,7 @@ Optional DIGEST will use digest to forward."
           (save-restriction
             (narrow-to-region b e)
             (goto-char b)
-            (narrow-to-region (point) 
+            (narrow-to-region (point)
                               (or (search-forward "\n\n" nil t) (point)))
             (message-remove-header message-forward-ignored-headers t)))))
     (message-position-point)))
@@ -4549,7 +4555,7 @@ The following arguments may contain lists of values."
          (list list))))
 
 (defun message-generate-new-buffer-clone-locals (name &optional varstr)
-  "Create and return a buffer with a name based on NAME using generate-new-buffer.
+  "Create and return a buffer with name based on NAME using `generate-new-buffer.'
 Then clone the local variables and values from the old buffer to the
 new one, cloning only the locals having a substring matching the
 regexp varstr."
@@ -4584,7 +4590,7 @@ regexp varstr."
 (defvar message-inhibit-body-encoding nil)
 
 (defun message-encode-message-body ()
-  (unless message-inhibit-body-encoding 
+  (unless message-inhibit-body-encoding
     (let ((mail-parse-charset (or mail-parse-charset
                                   message-default-charset))
           (case-fold-search t)
@@ -4637,7 +4643,7 @@ regexp varstr."
 
 (defun message-use-alternative-email-as-from ()
   (require 'mail-utils)
-  (let* ((fields '("To" "Cc")) 
+  (let* ((fields '("To" "Cc"))
          (emails
           (split-string
            (mail-strip-quoted-names