mu4e-draft: fix flycheck warnings + whitespace

mu4e/mu4e-draft.el

@@ -1,6 +1,6 @@
 ;; mu4e-draft.el -- part of mu4e, the mu mail user agent for emacs
 ;;
-;; Copyright (C) 2011-2016 Dirk-Jan C. Binnema
+;; Copyright (C) 2011-2019 Dirk-Jan C. Binnema
 
 ;; Author: Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
 ;; Maintainer: Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
@@ -24,7 +24,8 @@
 
 ;; In this file, various functions to create draft messages
 
-;; Code
+;;; Code:
+
 (require 'cl-lib)
 (require 'mu4e-vars)
 (require 'mu4e-utils)
@@ -36,41 +37,39 @@
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 (defcustom mu4e-compose-dont-reply-to-self nil
-  "If non-nil, don't include self (that is, any member of
+  "If non-nil, don't include self.
-`mu4e-user-mail-address-list') in replies."
+\(that is, member of `mu4e-user-mail-address-list') in replies."
   :type 'boolean
   :group 'mu4e-compose)
 
 (defcustom mu4e-compose-cite-function
   (or message-cite-function 'message-cite-original-without-signature)
-  "The function to use to cite message in replies and forwarded
+  "The function for citing message in replies and forwards.
-messages. This is the mu4e-specific version of
+This is the mu4e-specific version of
 `message-cite-function'."
   :type 'function
   :group 'mu4e-compose)
 
 (defcustom mu4e-compose-signature
   (or message-signature "Sent with my mu4e")
-  "The message signature (i.e. the blob at the bottom of
+  "The message signature.
-messages). This is the mu4e-specific version of
+\(i.e. the blob at the bottom of messages). This is the
-`message-signature'."
+mu4e-specific version of `message-signature'."
   :group 'mu4e-compose)
 
 (defcustom mu4e-compose-signature-auto-include t
-  "Whether to automatically include a message-signature in new
+  "Whether to automatically include a message-signature."
-messages (if it is set)."
   :type 'boolean
   :group 'mu4e-compose)
 
 (defcustom mu4e-compose-auto-include-date nil
-  "Whether to include a date header when starting to draft a
+  "Whether to include a date header.
-message; if nil, only do so when sending the message."
+If nil, only do so when sending the message."
   :type 'boolean
   :group 'mu4e-compose)
 
 (defcustom mu4e-compose-in-new-frame nil
-  "Whether to compose messages in a new frame instead of the
+  "Whether to compose messages in a new frame."
-current window."
   :type 'boolean
   :group 'mu4e-compose)
 
@@ -108,18 +107,19 @@ If VAL is nil, return nil."
         (propertize val 'face 'mu4e-header-value-face))))
 
 (defconst mu4e~max-reference-num 21
-  "Maximum number of References:, as suggested by
+  "Specifies the maximum number of References:.
-`message-shorten-references'.")
+As suggested by `message-shorten-references'.")
 
 (defun mu4e~shorten-1 (list cut surplus)
-  "Cut SURPLUS elements out of LIST, beginning with CUTth
+  "Cut SURPLUS elements out of LIST.
+Beginning with CUTth
 one. Code borrowed from `message-shorten-1'."
   (setcdr (nthcdr (- cut 2) list)
     (nthcdr (+ (- cut 2) surplus 1) list)))
 
 (defun mu4e~draft-references-construct (msg)
-  "Construct the value of the References: header based on MSG as a
+  "Construct the value of the References: header based on MSG.
-comma-separated string. Normally, this the concatenation of the
+This assumes a comma-separated string. Normally, this the concatenation of the
 existing References + In-Reply-To (which may be empty, an note
 that :references includes the old in-reply-to as well) and the
 message-id. If the message-id is empty, returns the old
@@ -145,8 +145,9 @@ References. If both are empty, return nil."
 ;; determine the recipient fields for new messages
 
 (defun mu4e~draft-recipients-list-to-string (lst)
-  "Convert a lst LST of address cells into a string with a list of
+  "Convert a lst LST of address cells into a string.
-e-mail addresses. If LST is nil, returns nil."
+This is specified as a comma-separated list of e-mail addresses.
+If LST is nil, returns nil."
   (when lst
     (mapconcat
       (lambda (addrcell)
@@ -168,12 +169,12 @@ form (NAME . EMAIL)."
 
 
 (defun mu4e~draft-create-to-lst (origmsg)
-  "Create a list of address for the To: in a new message, based on
+  "Create a list of address for the To: in a new message.
-the original message ORIGMSG. If the Reply-To address is set, use
+This is based on the original message ORIGMSG. If the Reply-To
-that, otherwise use the From address. Note, whatever was in the To:
+address is set, use that, otherwise use the From address. Note,
-field before, goes to the Cc:-list (if we're doing a reply-to-all).
+whatever was in the To: field before, goes to the Cc:-list (if
-Special case: if we were the sender of the original, we simple copy
+we're doing a reply-to-all). Special case: if we were the sender
-the list form the original."
+of the original, we simple copy the list form the original."
   (let ((reply-to
     (or (plist-get origmsg :reply-to) (plist-get origmsg :from))))
     (cl-delete-duplicates reply-to :test #'mu4e~draft-address-cell-equal)
@@ -189,7 +190,8 @@ the list form the original."
 
 
 (defun mu4e~strip-ignored-addresses (addrs)
-  "Return all the addresses in ADDRS not matching
+  "Return all addresses that are not to be ignored.
+I.e. return all the addresses in ADDRS not matching
 `mu4e-compose-reply-ignore-address'."
   (cond
     ((null mu4e-compose-reply-ignore-address)
@@ -213,8 +215,9 @@ the list form the original."
 
 
 (defun mu4e~draft-create-cc-lst (origmsg reply-all)
-  "Create a list of address for the Cc: in a new message, based on
+  "Create a list of address for the Cc: in a new message.
-the original message ORIGMSG, and whether it's a reply-all."
+This is based on the original message ORIGMSG, and whether it's a
+REPLY-ALL."
   (when reply-all
     (let* ((cc-lst ;; get the cc-field from the original, remove dups
        (cl-delete-duplicates
@@ -249,8 +252,8 @@ the original message ORIGMSG, and whether it's a reply-all."
       cc-lst)))
 
 (defun mu4e~draft-recipients-construct (field origmsg &optional reply-all)
-  "Create value (a string) for the recipient field FIELD (a
+  "Create value (a string) for the recipient FIELD.
-symbol, :to or :cc), based on the original message ORIGMSG,
+\(which is a symbol, :to or :cc), based on the original message ORIGMSG,
 and (optionally) REPLY-ALL which indicates this is a reply-to-all
 message. Return nil if there are no recipients for the particular field."
   (mu4e~draft-recipients-list-to-string
@@ -268,13 +271,13 @@ message. Return nil if there are no recipients for the particular field."
 ;;; contributed by jhelberg
 
 (defun mu4e~rfc822-phrase-type (ph)
-  "Return either atom, quoted-string, a corner-case or nil. This
+  "Return an atom or quoted-string for the phrase PH.
-   checks for empty string first. Then quotes around the phrase
+This checks for empty string first. Then quotes around the phrase
-   (returning 'rfc822-quoted-string). Then whether there is a quote
+\(returning 'rfc822-quoted-string). Then whether there is a quote
-   inside the phrase (returning 'rfc822-containing-quote).
+inside the phrase (returning 'rfc822-containing-quote).
-   The reverse of the RFC atext definition is then tested.
+The reverse of the RFC atext definition is then tested.
-   If it matches, nil is returned, if not, it is an 'rfc822-atom, which
+If it matches, nil is returned, if not, it is an 'rfc822-atom, which
-   is returned."
+is returned."
   (cond
     ((= (length ph) 0) 'rfc822-empty)
     ((= (aref ph 0) ?\")
@@ -286,9 +289,9 @@ message. Return nil if there are no recipients for the particular field."
     (t 'rfc822-atom)))
 
 (defun mu4e~rfc822-quoteit (ph)
-  "Quote RFC822 phrase only if necessary.
+  "Quote an RFC822 phrase PH only if necessary.
-   Atoms and quoted strings don't need quotes. The rest do.  In
+Atoms and quoted strings don't need quotes. The rest do.  In
-   case a phrase contains a quote, it will be escaped."
+case a phrase contains a quote, it will be escaped."
   (let ((type (mu4e~rfc822-phrase-type ph)))
     (cond
       ((eq type 'rfc822-atom) ph)
@@ -299,13 +302,10 @@ message. Return nil if there are no recipients for the particular field."
       (t (format "\"%s\"" ph)))))
 
 
-
-
-
 (defun mu4e~draft-from-construct ()
-  "Construct a value for the From:-field of the reply to MSG,
+  "Construct a value for the From:-field of the reply.
-based on `user-full-name' and `user-mail-address'; if the latter is
+This is based on the variable `user-full-name' and
-nil, function returns nil."
+`user-mail-address'; if the latter is nil, function returns nil."
   (when user-mail-address
     (if user-full-name
       (format "%s <%s>" (mu4e~rfc822-quoteit user-full-name) user-mail-address)
@@ -350,9 +350,11 @@ separator is never written to the message file. Also see
           (insert "\n" sepa))))))
 
 (defun mu4e~draft-remove-mail-header-separator ()
-  "Remove `mail-header-separator; we do this before saving a
+  "Remove `mail-header-separator'.
+We do this before saving a
 file (and restore it afterwards), to ensure that the separator
-never hits the disk. Also see `mu4e~draft-insert-mail-header-separator."
+never hits the disk. Also see
+`mu4e~draft-insert-mail-header-separator."
   (save-excursion
     (widen)
     (goto-char (point-min))
@@ -407,9 +409,9 @@ You can append flags."
   "String to prefix replies with.")
 
 (defun mu4e~draft-reply-construct (origmsg)
-  "Create a draft message as a reply to original message
+  "Create a draft message as a reply to ORIGMSG.
-ORIGMSG. Replying-to-self is a special; in that case, the To and Cc
+Replying-to-self is special; in that case, the To and Cc fields
-fields will be the same as in the original."
+will be the same as in the original."
   (let* ((reply-to-self (mu4e-message-contact-field-matches-me origmsg :from))
     (recipnum
        (+ (length (mu4e~draft-create-to-lst origmsg))
@@ -486,8 +488,8 @@ fields will be the same as in the original."
     (mu4e~draft-common-construct)))
 
 (defvar mu4e~draft-drafts-folder nil
-  "The drafts-folder for this compose buffer, based on
+  "The drafts-folder for this compose buffer.
-`mu4e-drafts-folder', which is evaluated once.")
+This is based on `mu4e-drafts-folder', which is evaluated once.")
 
 (defun mu4e~draft-open-file (path)
   "Open the the draft file at PATH."
@@ -496,16 +498,16 @@ fields will be the same as in the original."
     (find-file path)))
 
 (defun mu4e~draft-determine-path (draft-dir)
-  "Determine the path for a new draft file."
+  "Determines the path for a new draft file in DRAFT-DIR."
   (format "%s/%s/cur/%s"
     mu4e-maildir draft-dir (mu4e~draft-message-filename-construct "DS")))
 
 
 (defun mu4e-draft-open (compose-type &optional msg)
-  "Open a draft file for a new message (when COMPOSE-TYPE is `reply',
+  "Open a draft file for a message MSG.
- `forward' or `new'), open an existing draft (when COMPOSE-TYPE
+In case of a new message (when COMPOSE-TYPE is `reply', `forward'
-is `edit'), or re-send an existing message (when COMPOSE-TYPE is
+ or `new'), open an existing draft (when COMPOSE-TYPE is `edit'),
-`resend').
+ or re-send an existing message (when COMPOSE-TYPE is `resend').
 
 The name of the draft folder is constructed from the
 concatenation of `mu4e-maildir' and `mu4e-drafts-folder' (the
@@ -513,7 +515,7 @@ latter will be evaluated). The message file name is a unique name
 determined by `mu4e-send-draft-file-name'. The initial contents
 will be created from either `mu4e~draft-reply-construct', or
 `mu4e~draft-forward-construct' or `mu4e~draft-newmsg-construct'."
-  (unless mu4e-maildir (mu4e-error "mu4e-maildir not set"))
+  (unless mu4e-maildir (mu4e-error "Variable mu4e-maildir not set"))
   (let ((draft-dir nil))
     (cl-case compose-type
 
@@ -551,7 +553,7 @@ will be created from either `mu4e~draft-reply-construct', or
         (save-excursion
     (message-insert-signature)
     (mu4e~fontify-signature))))))
-      (t (mu4e-error "unsupported compose-type %S" compose-type)))
+      (t (mu4e-error "Unsupported compose-type %S" compose-type)))
     ;; if we didn't find a draft folder yet, try some default
     (unless draft-dir
       (setq draft-dir (mu4e-get-drafts-folder msg)))
@@ -560,7 +562,8 @@ will be created from either `mu4e~draft-reply-construct', or
     (set (make-local-variable 'mu4e~draft-drafts-folder) draft-dir)
     (put 'mu4e~draft-drafts-folder 'permanent-local t)
     (unless mu4e~draft-drafts-folder
-      (mu4e-error "failed to determine drafts folder"))))
+      (mu4e-error "Failed to determine drafts folder"))))
 
 
 (provide 'mu4e-draft)
+;;; mu4e-draft.el ends here