Merge pull request #86 from tarsius/cleanup

* fix defcustom types and improve their doc-strings

.gitignore

@@ -67,9 +67,7 @@ test-mu-util
 mu4e-meta.el
 mu4e.pdf
 texinfo.tex
-/emacs/mdate-sh
+texi.texi
-/emacs/stamp-vti
-/emacs/version.texi
 *.tex
 *.pdf
 /www/auto/*
@@ -80,3 +78,4 @@ configure.lineno
 /mu4e/stamp-vti
 /mu4e/version.texi
 /guile/tests/test-mu-guile
+/lib/doxyfile

mu4e/mu4e-compose.el

@@ -90,17 +90,19 @@
   :group 'mu4e)
 
 (defcustom mu4e-sent-messages-behavior 'sent
-  "Determines what mu4e does with sent messages - this is a symbol
+  "Determines what mu4e does with sent messages.
-which can be either:
 
- * 'sent --> move the sent message to the Sent-folder (`mu4e-sent-folder')
+This is one of the symbols:
- * 'trash --> move the sent message to the Trash-folder (`mu4e-trash-folder')
+* `sent'    move the sent message to the Sent-folder (`mu4e-sent-folder')
- * 'delete --> delete the sent message.
+* `trash'   move the sent message to the Trash-folder (`mu4e-trash-folder')
+* `delete'  delete the sent message.
 
 Note, when using GMail/IMAP, you should set this to either 'trash
 or 'delete, since GMail already takes care of keeping copies in the
 sent folder."
-  :type 'symbol
+  :type '(choice (const sent :tag "move message to mu4e-sent-folder")
+		 (const sent :tag "move message to mu4e-trash-folder")
+		 (const sent :tag "delete message"))
   :safe 'symbolp
   :group 'mu4e-compose)
 

mu4e/mu4e-headers.el

@@ -51,12 +51,19 @@
      (:flags         .   6)
      (:from          .  22)
      (:subject       .  nil))
-  "A list of header fields to show in the headers buffer, and their
+  "A list of header fields to show in the headers buffer.
-respective widths in characters. A width of `nil' means
+Each element has the form (HEADER . WIDTH), where HEADER is one
-'unrestricted', and this is best reserved fo the rightmost (last)
+of the available headers (see `mu4e-header-info') and WIDTH is
-field. For the complete list of available headers, see
+the respective width in characters.  A width of `nil' means
-`mu4e-header-info'."
+'unrestricted', and this is best reserved for the
-  :type (list 'symbol)
+rightmost (last) field."
+  :type `(repeat (cons (choice ,@(mapcar (lambda (h)
+					   (list 'const :tag
+						 (plist-get (cdr h) :help)
+						 (car h)))
+					 mu4e-header-info))
+		       (choice (integer :tag "width")
+			       (const :tag "unrestricted width" nil))))
   :group 'mu4e-headers)
 
 (defcustom mu4e-headers-date-format "%x"

mu4e/mu4e-mark.el

@@ -31,13 +31,15 @@
 (require 'mu4e-message)
 
 (defcustom mu4e-headers-leave-behavior 'ask
-  "What to do when user leaves the headers view (e.g. quits,
+  "What to do when user leaves the headers view.
-  refreshes or does a new search). Value is one of the following
+That is when he e.g. quits, refreshes or does a new search.
-  symbols:
+Value is one of the following symbols:
-- ask (ask the user whether to ignore the marks)
+- `ask'     ask user whether to ignore the marks
-- apply (automatically apply the marks before doing anything else)
+- `apply'   automatically apply the marks before doing anything else
-- ignore (automatically ignore the marks without asking)."
+- `ignore'  automatically ignore the marks without asking"
-  :type 'symbol
+  :type '(choice (const ask    :tag "ask user whether to ignore marks")
+		 (const apply  :tag "apply marks without asking")
+		 (const ignore :tag "ignore marks without asking"))
   :group 'mu4e-headers)
 
 (defvar mu4e-headers-show-target t

mu4e/mu4e-vars.el

@@ -35,10 +35,9 @@
 
 (defcustom mu4e-mu-home nil
   "Location of the mu homedir, or nil for the default."
-  :type 'directory
   :group 'mu4e
   :type '(choice (const :tag "Default location" nil)
-                 (const :tag "Specify location" string))
+                 (directory :tag "Specify location"))
   :safe 'stringp)
 
 (defcustom mu4e-mu-binary (executable-find "mu")
@@ -49,15 +48,14 @@ PATH, you can specify the full path."
   :safe 'stringp)
 
 (defcustom mu4e-maildir (expand-file-name "~/Maildir")
-  "Your Maildir directory; by default, mu4e assumes
+  "Your Maildir directory."
-~/Maildir."
   :type 'directory
   :safe 'stringp
   :group 'mu4e)
 
 (defcustom mu4e-get-mail-command "true"
-  "Shell command to run to retrieve new mail; e.g. 'offlineimap' or
+  "Shell command to run to retrieve new mail.
-'fetchmail'."
+Common values are \"offlineimap\" and \"fetchmail\"."
   :type 'string
   :group 'mu4e
   :safe 'stringp)
@@ -107,10 +105,11 @@ personal message. This is used when indexing messages."
   :group 'mu4e)
 
 (defcustom mu4e-search-results-limit 500
-  "Maximum number of search results (or -1 for unlimited). Since
+  "Maximum number of search results.
-limiting search results speeds up searches significantly, it's
+Use -1 for no limit.  Since limiting search results speeds up
-useful to limit this. Note, to ignore the limit, use a prefix
+searches significantly, it's useful to limit this. Note, to
-argument (C-u) before invoking the search."
+ignore the limit, use a prefix argument (C-u) before invoking the
+search."
   :type '(choice (const :tag "Unlimited" -1)
                  (integer :tag "Limit"))
   :group 'mu4e)
@@ -501,8 +500,7 @@ headers)."
      (:from-or-to .
        ( :name "From/To"
 	 :shortname "From/To"
-	 :help "Sender of the message if it's not me; otherwise
+	 :help "Sender of the message if it's not me; otherwise the recipient"
-	 the recipient"
 	 :sortable nil))
      (:maildir .
        ( :name "Maildir"
@@ -539,13 +537,14 @@ headers)."
 	 :shortname "T"
 	 :help "Recipient of the message"
 	 :sortable t)))
-  "An alist of all possible header fields and information about
+  "An alist of all possible header fields and information about them.
-them.; this is used in the UI (the column headers in the header
+This is used in the UI (the column headers in the header list,
-list, and the fields the message view). Most fields should be
+and the fields the message view).
-self-explanatory. A special one is `:from-or-to', which is equal to
-`:from' unless `:from' matches `mu4e-user-mail-address-regexp', in
-which case it will be equal to `:to'.")
 
+Most fields should be self-explanatory. A special one is
+`:from-or-to', which is equal to `:from' unless `:from' matches
+`mu4e-user-mail-address-regexp', in which case it will be equal
+to `:to'.")
 
 (defvar mu4e-custom-header-info nil
   "A list like `mu4e-custom-header-info', but for

mu4e/mu4e-view.el

@@ -51,8 +51,8 @@
 
 (defcustom mu4e-view-fields
   '(:from :to  :cc :subject :flags :date :maildir :tags :attachments :signature)
-  "Header fields to display in the message view buffer. For the
+  "Header fields to display in the message view buffer.
-complete list of available headers, see `mu4e-header-info'."
+For the complete list of available headers, see `mu4e-header-info'."
   :type (list 'symbol)
   :group 'mu4e-view)
 
@@ -69,14 +69,14 @@ contact."
 
 (defcustom mu4e-view-date-format "%c"
   "Date format to use in the message view, in the format of
-  `format-time-string'."
+`format-time-string'."
   :type 'string
   :group 'mu4e-view)
 
 (defcustom mu4e-view-image-max-width 800
-  "The maximum width for images to display; this is only effective
+  "The maximum width for images to display.
-  if you're using an emacs with Imagemagick support, and
+This is only effective if you're using an emacs with Imagemagick
-  `mu4e-show-image' is non-nil."
+support, and `mu4e-show-image' is non-nil."
   :group 'mu4e-view)
 
 (defcustom mu4e-view-scroll-to-next t