unofficial mirror of notmuch@notmuchmail.org
 help / color / mirror / code / Atom feed
* [PATCH] emacs docstrings: consistent indentation, newlines, periods
@ 2020-05-03 21:21 Tomi Ollila
  2020-05-21 21:47 ` Daniel Kahn Gillmor
  0 siblings, 1 reply; 5+ messages in thread
From: Tomi Ollila @ 2020-05-03 21:21 UTC (permalink / raw)
  To: notmuch; +Cc: tomi.ollila

Fixed emacs docstrings to be consistent. No functional change.

- removed some (accidental) indentation
- removed some trailing newlines
- added trailing periods where missing (some exclusions)
---
 emacs/notmuch-address.el     | 21 ++++-----
 emacs/notmuch-draft.el       |  8 ++--
 emacs/notmuch-hello.el       | 11 ++---
 emacs/notmuch-jump.el        |  3 +-
 emacs/notmuch-lib.el         | 10 ++--
 emacs/notmuch-maildir-fcc.el |  4 +-
 emacs/notmuch-message.el     |  4 +-
 emacs/notmuch-mua.el         |  2 +-
 emacs/notmuch-query.el       | 13 +++---
 emacs/notmuch-show.el        | 24 +++++-----
 emacs/notmuch-tag.el         |  8 ++--
 emacs/notmuch-tree.el        | 88 ++++++++++++++++++------------------
 emacs/notmuch-wash.el        |  2 +-
 emacs/notmuch.el             | 34 +++++++-------
 14 files changed, 114 insertions(+), 118 deletions(-)

diff --git a/emacs/notmuch-address.el b/emacs/notmuch-address.el
index 64887a43..0d56fba7 100644
--- a/emacs/notmuch-address.el
+++ b/emacs/notmuch-address.el
@@ -29,11 +29,11 @@
 (declare-function company-manual-begin "company")
 
 (defvar notmuch-address-last-harvest 0
-  "Time of last address harvest")
+  "Time of last address harvest.")
 
 (defvar notmuch-address-completions (make-hash-table :test 'equal)
   "Hash of email addresses for completion during email composition.
-  This variable is set by calling `notmuch-address-harvest'.")
+This variable is set by calling `notmuch-address-harvest'.")
 
 (defvar notmuch-address-full-harvest-finished nil
   "t indicates that full completion address harvesting has been
@@ -73,11 +73,11 @@ (defcustom notmuch-address-internal-completion '(sent nil)
   "Determines how internal address completion generates candidates.
 
 This should be a list of the form '(DIRECTION FILTER), where
- DIRECTION is either sent or received and specifies whether the
- candidates are searched in messages sent by the user or received
- by the user (note received by is much faster), and FILTER is
- either nil or a filter-string, such as \"date:1y..\" to append
- to the query."
+DIRECTION is either sent or received and specifies whether the
+candidates are searched in messages sent by the user or received
+by the user (note received by is much faster), and FILTER is
+either nil or a filter-string, such as \"date:1y..\" to append
+to the query."
   :type '(list :tag "Use internal address completion"
 	       (radio
 		:tag "Base completion on messages you have"
@@ -126,8 +126,7 @@ (defcustom notmuch-address-post-completion-functions nil
 
 The completed address is passed as an argument to each function.
 Note that this hook will be invoked for completion in headers
-matching `notmuch-address-completion-headers-regexp'.
-"
+matching `notmuch-address-completion-headers-regexp'."
   :type 'hook
   :group 'notmuch-address
   :group 'notmuch-hooks)
@@ -147,7 +146,7 @@ (defun notmuch-address-message-insinuate ()
   (message "calling notmuch-address-message-insinuate is no longer needed"))
 
 (defcustom notmuch-address-use-company t
-  "If available, use company mode for address completion"
+  "If available, use company mode for address completion."
   :type 'boolean
   :group 'notmuch-send
   :group 'notmuch-address)
@@ -285,7 +284,7 @@ (defun notmuch-address-harvest-filter (proc string)
 (defvar notmuch-address-harvest-procs '(nil . nil)
   "The currently running harvests.
 
-The car is a partial harvest, and the cdr is a full harvest")
+The car is a partial harvest, and the cdr is a full harvest.")
 
 (defun notmuch-address-harvest (&optional addr-prefix synchronous callback)
   "Collect addresses completion candidates.
diff --git a/emacs/notmuch-draft.el b/emacs/notmuch-draft.el
index 504b33be..531666d0 100644
--- a/emacs/notmuch-draft.el
+++ b/emacs/notmuch-draft.el
@@ -45,7 +45,7 @@ (defcustom notmuch-draft-tags '("+draft")
 For example, if you wanted to give the message a \"draft\" tag
 but not the (normally added by default) \"inbox\" tag, you would
 set:
-    (\"+draft\" \"-inbox\")"
+    (\"+draft\" \"-inbox\")."
   :type '(repeat string)
   :group 'notmuch-draft)
 
@@ -76,7 +76,7 @@ (defcustom notmuch-draft-quoted-tags '()
 
 (defcustom notmuch-draft-save-plaintext 'ask
   "Should notmuch save/postpone in plaintext messages that seem
-  like they are intended to be sent encrypted
+like they are intended to be sent encrypted
 (i.e with an mml encryption tag in it)."
   :type '(radio
 	  (const :tag "Never" nil)
@@ -87,10 +87,10 @@ (defcustom notmuch-draft-save-plaintext 'ask
 
 (defvar notmuch-draft-encryption-tag-regex
   "<#\\(part encrypt\\|secure.*mode=.*encrypt>\\)"
-  "Regular expression matching mml tags indicating encryption of part or message")
+  "Regular expression matching mml tags indicating encryption of part or message.")
 
 (defvar notmuch-draft-id nil
-  "Message-id of the most recent saved draft of this message")
+  "Message-id of the most recent saved draft of this message.")
 (make-variable-buffer-local 'notmuch-draft-id)
 
 (defun notmuch-draft--mark-deleted ()
diff --git a/emacs/notmuch-hello.el b/emacs/notmuch-hello.el
index bdf584e6..0ff5aaff 100644
--- a/emacs/notmuch-hello.el
+++ b/emacs/notmuch-hello.el
@@ -359,7 +359,7 @@ (defcustom notmuch-hello-auto-refresh t
   :type 'boolean)
 
 (defvar notmuch-hello-hidden-sections nil
-  "List of sections titles whose contents are hidden")
+  "List of sections titles whose contents are hidden.")
 
 (defvar notmuch-hello-first-run t
   "True if `notmuch-hello' is run for the first time, set to nil
@@ -501,8 +501,7 @@ (defun notmuch-hello-filtered-query (query filter)
 the string it returns is used as the query. If nil is returned,
 the entry is hidden.
 
-Otherwise, FILTER is ignored.
-"
+Otherwise, FILTER is ignored."
   (cond
    ((functionp filter) (funcall filter query))
    ((stringp filter)
@@ -656,7 +655,7 @@ (defun notmuch-hello-window-configuration-change ()
 (defvar notmuch-emacs-version)
 
 (defun notmuch-hello-versions ()
-  "Display the notmuch version(s)"
+  "Display the notmuch version(s)."
   (interactive)
   (let ((notmuch-cli-version (notmuch-cli-version)))
     (message "notmuch version %s"
@@ -923,7 +922,7 @@ (defun notmuch-hello-insert-tags-section (&optional title &rest options)
 	 options))
 
 (defun notmuch-hello-insert-inbox ()
-  "Show an entry for each saved search and inboxed messages for each tag"
+  "Show an entry for each saved search and inboxed messages for each tag."
   (notmuch-hello-insert-searches "What's in your inbox"
 				 (append
 				  notmuch-saved-searches
@@ -931,7 +930,7 @@ (defun notmuch-hello-insert-inbox ()
 				 :filter "tag:inbox"))
 
 (defun notmuch-hello-insert-alltags ()
-  "Insert a section displaying all tags and associated message counts"
+  "Insert a section displaying all tags and associated message counts."
   (notmuch-hello-insert-tags-section
    nil
    :initially-hidden (not notmuch-show-all-tags-list)
diff --git a/emacs/notmuch-jump.el b/emacs/notmuch-jump.el
index 92a5a2cc..84fe2b9c 100644
--- a/emacs/notmuch-jump.el
+++ b/emacs/notmuch-jump.el
@@ -88,8 +88,7 @@ (defun notmuch-jump (action-map prompt)
 where KEY is a key binding, LABEL is a string label to display in
 the buffer, and ACTION is a nullary function to call.  LABEL may
 be null, in which case the action will still be bound, but will
-not appear in the pop-up buffer.
-"
+not appear in the pop-up buffer."
 
   (let* ((items (notmuch-jump--format-actions action-map))
 	 ;; Format the table of bindings and the full prompt
diff --git a/emacs/notmuch-lib.el b/emacs/notmuch-lib.el
index 01862f44..da7e80e9 100644
--- a/emacs/notmuch-lib.el
+++ b/emacs/notmuch-lib.el
@@ -145,7 +145,7 @@ (defcustom notmuch-archive-tags '("-inbox")
 
 For example, if you wanted to remove an \"inbox\" tag and add an
 \"archived\" tag, you would set:
-    (\"-inbox\" \"+archived\")"
+    (\"-inbox\" \"+archived\")."
   :type '(repeat string)
   :group 'notmuch-search
   :group 'notmuch-show)
@@ -189,7 +189,7 @@ (defun notmuch-command-to-string (&rest args)
 will appear in a buffer named \"*Notmuch errors*\" and an error
 will be signaled.
 
-Otherwise the output will be returned"
+Otherwise the output will be returned."
   (with-temp-buffer
     (let* ((status (apply #'call-process notmuch-command nil t nil args))
 	   (output (buffer-string)))
@@ -299,7 +299,7 @@ (defun notmuch-prefix-key-description (key)
 
 
 (defun notmuch-describe-key (actual-key binding prefix ua-keys tail)
-  "Prepend cons cells describing prefix-arg ACTUAL-KEY and ACTUAL-KEY to TAIL
+  "Prepend cons cells describing prefix-arg ACTUAL-KEY and ACTUAL-KEY to TAIL.
 
 It does not prepend if ACTUAL-KEY is already listed in TAIL."
   (let ((key-string (concat prefix (key-description actual-key))))
@@ -530,11 +530,11 @@ (defun notmuch-plist-delete (plist property)
     (cdr xplist)))
 
 (defun notmuch-split-content-type (content-type)
-  "Split content/type into 'content' and 'type'"
+  "Split content/type into 'content' and 'type'."
   (split-string content-type "/"))
 
 (defun notmuch-match-content-type (t1 t2)
-  "Return t if t1 and t2 are matching content types, taking wildcards into account"
+  "Return t if t1 and t2 are matching content types, taking wildcards into account."
   (let ((st1 (notmuch-split-content-type t1))
 	(st2 (notmuch-split-content-type t2)))
     (if (or (string= (cadr st1) "*")
diff --git a/emacs/notmuch-maildir-fcc.el b/emacs/notmuch-maildir-fcc.el
index b9cca543..e95de63b 100644
--- a/emacs/notmuch-maildir-fcc.el
+++ b/emacs/notmuch-maildir-fcc.el
@@ -78,7 +78,7 @@ (defcustom notmuch-fcc-dirs "sent"
  :group 'notmuch-send)
 
 (defcustom notmuch-maildir-use-notmuch-insert 't
-  "Should fcc use notmuch insert instead of simple fcc"
+  "Should fcc use notmuch insert instead of simple fcc."
   :type '(choice :tag "Fcc Method"
 		 (const :tag "Use notmuch insert" t)
 		 (const :tag "Use simple fcc" nil))
@@ -93,7 +93,7 @@ (defun notmuch-fcc-header-setup ()
 Sets the Fcc header based on the values of `notmuch-fcc-dirs'.
 
 Originally intended to be use a hook function, but now called directly
-by notmuch-mua-mail"
+by notmuch-mua-mail."
 
   (let ((subdir
 	 (cond
diff --git a/emacs/notmuch-message.el b/emacs/notmuch-message.el
index 0164472f..dc532306 100644
--- a/emacs/notmuch-message.el
+++ b/emacs/notmuch-message.el
@@ -33,7 +33,7 @@ (defcustom notmuch-message-replied-tags '("+replied")
 
 For example, if you wanted to add a \"replied\" tag and remove
 the \"inbox\" and \"todo\" tags, you would set:
-    (\"+replied\" \"-inbox\" \"-todo\")"
+    (\"+replied\" \"-inbox\" \"-todo\")."
   :type '(repeat string)
   :group 'notmuch-send)
 
@@ -46,7 +46,7 @@ (defcustom notmuch-message-forwarded-tags '("+forwarded")
 
 For example, if you wanted to add a \"forwarded\" tag and remove
 the \"inbox\" tag, you would set:
-    (\"+forwarded\" \"-inbox\")"
+    (\"+forwarded\" \"-inbox\")."
   :type '(repeat string)
   :group 'notmuch-send)
 
diff --git a/emacs/notmuch-mua.el b/emacs/notmuch-mua.el
index 40a1e6bc..1efc88ea 100644
--- a/emacs/notmuch-mua.el
+++ b/emacs/notmuch-mua.el
@@ -334,7 +334,7 @@ (defun notmuch-mua-reply (query-string &optional sender reply-all)
   (set-buffer-modified-p nil))
 
 (define-derived-mode notmuch-message-mode message-mode "Message[Notmuch]"
-  "Notmuch message composition mode. Mostly like `message-mode'"
+  "Notmuch message composition mode. Mostly like `message-mode'."
   (notmuch-address-setup))
 
 (put 'notmuch-message-mode 'flyspell-mode-predicate 'mail-mode-flyspell-verify)
diff --git a/emacs/notmuch-query.el b/emacs/notmuch-query.el
index 563e4acf..3a835a00 100644
--- a/emacs/notmuch-query.el
+++ b/emacs/notmuch-query.el
@@ -28,8 +28,7 @@ (defun notmuch-query-get-threads (search-terms)
 
 A thread is a forest or list of trees. A tree is a two element
 list where the first element is a message, and the second element
-is a possibly empty forest of replies.
-"
+is a possibly empty forest of replies."
   (let ((args '("show" "--format=sexp" "--format-version=4")))
     (if notmuch-show-process-crypto
 	(setq args (append args '("--decrypt=true"))))
@@ -40,7 +39,7 @@ (defun notmuch-query-get-threads (search-terms)
 ;; Mapping functions across collections of messages.
 
 (defun notmuch-query-map-aux  (mapper function seq)
-  "private function to do the actual mapping and flattening"
+  "Private function to do the actual mapping and flattening."
   (apply 'append
 	 (mapcar
 	   (lambda (tree)
@@ -48,20 +47,20 @@ (defun notmuch-query-map-aux  (mapper function seq)
 	   seq)))
 
 (defun notmuch-query-map-threads (fn threads)
-  "apply FN to every thread in  THREADS. Flatten results to a list.
+  "Apply FN to every thread in THREADS. Flatten results to a list.
 
 See the function notmuch-query-get-threads for more information."
   (notmuch-query-map-aux 'notmuch-query-map-forest fn threads))
 
 (defun notmuch-query-map-forest (fn forest)
-  "apply function to every message in a forest. Flatten results to a list.
+  "Apply function to every message in a forest. Flatten results to a list.
 
 See the function notmuch-query-get-threads for more information.
 "
   (notmuch-query-map-aux 'notmuch-query-map-tree fn forest))
 
 (defun notmuch-query-map-tree (fn tree)
-  "Apply function FN to every message in TREE. Flatten results to a list
+  "Apply function FN to every message in TREE. Flatten results to a list.
 
 See the function notmuch-query-get-threads for more information."
   (cons (funcall fn (car tree)) (notmuch-query-map-forest fn (cadr tree))))
@@ -70,7 +69,7 @@ (defun notmuch-query-map-tree (fn tree)
 ;; Predefined queries
 
 (defun notmuch-query-get-message-ids (&rest search-terms)
-  "Return a list of message-ids of messages that match SEARCH-TERMS"
+  "Return a list of message-ids of messages that match SEARCH-TERMS."
   (notmuch-query-map-threads
    (lambda (msg) (plist-get msg :id))
    (notmuch-query-get-threads search-terms)))
diff --git a/emacs/notmuch-show.el b/emacs/notmuch-show.el
index 59931453..bb99e197 100644
--- a/emacs/notmuch-show.el
+++ b/emacs/notmuch-show.el
@@ -179,7 +179,7 @@ (defvar notmuch-show-indent-content t)
 (make-variable-buffer-local 'notmuch-show-indent-content)
 
 (defvar notmuch-show-attachment-debug nil
-  "If t log stdout and stderr from attachment handlers
+  "If t log stdout and stderr from attachment handlers.
 
 When set to nil (the default) stdout and stderr from attachment
 handlers is discarded. When set to t the stdout and stderr from
@@ -237,7 +237,7 @@ (defcustom notmuch-show-mark-read-tags '("-unread")
 
 For example, if you wanted to remove an \"unread\" tag and add a
 \"read\" tag (which would make little sense), you would set:
-    (\"-unread\" \"+read\")"
+    (\"-unread\" \"+read\")."
   :type '(repeat string)
   :group 'notmuch-show)
 
@@ -266,7 +266,7 @@ (defcustom notmuch-show-imenu-indent nil
   :group 'notmuch-show)
 
 (defmacro with-current-notmuch-show-message (&rest body)
-  "Evaluate body with current buffer set to the text of current message"
+  "Evaluate body with current buffer set to the text of current message."
   `(save-excursion
      (let ((id (notmuch-show-get-message-id)))
        (let ((buf (generate-new-buffer (concat "*notmuch-msg-" id "*"))))
@@ -887,7 +887,7 @@ (defun notmuch-show-insert-bodypart-internal (msg part content-type nth depth bu
 		    nil))))
 
 (defun notmuch-show-create-part-overlays (button beg end)
-  "Add an overlay to the part between BEG and END"
+  "Add an overlay to the part between BEG and END."
 
   ;; If there is no button (i.e., the part is text/plain and the first
   ;; part) or if the part has no content then we don't make the part
@@ -898,7 +898,7 @@ (defun notmuch-show-create-part-overlays (button beg end)
     t))
 
 (defun notmuch-show-record-part-information (part beg end)
-  "Store PART as a text property from BEG to END"
+  "Store PART as a text property from BEG to END."
 
   ;; Record part information.  Since we already inserted subparts,
   ;; don't override existing :notmuch-part properties.
@@ -1381,7 +1381,7 @@ (defun notmuch-show-capture-state ()
     (list win-id-combo (notmuch-show-get-message-ids-for-open-messages))))
 
 (defun notmuch-show-get-query ()
-  "Return the current query in this show buffer"
+  "Return the current query in this show buffer."
   (if notmuch-show-query-context
       (concat notmuch-show-thread-id
 	      " and ("
@@ -1459,7 +1459,7 @@ (defvar notmuch-show-stash-map
     (define-key map "G" 'notmuch-show-stash-git-send-email)
     (define-key map "?" 'notmuch-subkeymap-help)
     map)
-  "Submap for stash commands")
+  "Submap for stash commands.")
 (fset 'notmuch-show-stash-map notmuch-show-stash-map)
 
 (defvar notmuch-show-part-map
@@ -1471,7 +1471,7 @@ (defvar notmuch-show-part-map
     (define-key map "m" 'notmuch-show-choose-mime-of-part)
     (define-key map "?" 'notmuch-subkeymap-help)
     map)
-  "Submap for part commands")
+  "Submap for part commands.")
 (fset 'notmuch-show-part-map notmuch-show-part-map)
 
 (defvar notmuch-show-mode-map
@@ -1561,14 +1561,14 @@ (define-derived-mode notmuch-show-mode fundamental-mode "notmuch-show"
         #'notmuch-show-imenu-extract-index-name-function))
 
 (defun notmuch-tree-from-show-current-query ()
-  "Call notmuch tree with the current query"
+  "Call notmuch tree with the current query."
   (interactive)
   (notmuch-tree notmuch-show-thread-id
 		notmuch-show-query-context
 		(notmuch-show-get-message-id)))
 
 (defun notmuch-unthreaded-from-show-current-query ()
-  "Call notmuch unthreaded with the current query"
+  "Call notmuch unthreaded with the current query."
   (interactive)
   (notmuch-unthreaded notmuch-show-thread-id
 		      notmuch-show-query-context
@@ -2011,7 +2011,7 @@ (defun notmuch-show-open-if-matched ()
     (notmuch-show-message-visible props (plist-get props :match))))
 
 (defun notmuch-show-goto-first-wanted-message ()
-  "Move to the first open message and mark it read"
+  "Move to the first open message and mark it read."
   (goto-char (point-min))
   (unless (notmuch-show-message-visible-p)
     (notmuch-show-next-open-message))
@@ -2511,7 +2511,7 @@ (defun notmuch-show--mm-display-part (handle)
       (view-buffer buf 'kill-buffer-if-not-modified))))
 
 (defun notmuch-show-choose-mime-of-part (mime-type)
-  "Choose the mime type to use for displaying part"
+  "Choose the mime type to use for displaying part."
   (interactive
    (list (completing-read "Mime type to use (default text/plain): "
 			  (mailcap-mime-types) nil nil nil nil "text/plain")))
diff --git a/emacs/notmuch-tag.el b/emacs/notmuch-tag.el
index bc83e3de..c54e6ad0 100644
--- a/emacs/notmuch-tag.el
+++ b/emacs/notmuch-tag.el
@@ -84,7 +84,7 @@ (defcustom notmuch-tagging-keys
   :group 'notmuch-tag)
 
 (define-widget 'notmuch-tag-format-type 'lazy
-  "Customize widget for notmuch-tag-format and friends"
+  "Customize widget for notmuch-tag-format and friends."
   :type '(alist :key-type (regexp :tag "Tag")
 		:extra-offset -3
 		:value-type
@@ -313,7 +313,7 @@ (defun notmuch-tag-format-tag (tags orig-tags tag)
 are in TAGS but are not in ORIG-TAGS) are shown using formats
 from `notmuch-tag-added-formats' and tags which have not been
 changed (the normal case) are shown using formats from
-`notmuch-tag-formats'"
+`notmuch-tag-formats'."
   (let* ((tag-state (cond ((not (member tag tags)) 'deleted)
 			  ((not (member tag orig-tags)) 'added)))
 	 (formatted-tag (gethash (cons tag tag-state) notmuch-tag--format-cache 'missing)))
@@ -351,7 +351,7 @@ (defcustom notmuch-before-tag-hook nil
 'tag-changes' will contain the tags that are about to be added or removed as
 a list of strings of the form \"+TAG\" or \"-TAG\".
 'query' will be a string containing the search query that determines
-the messages that are about to be tagged"
+the messages that are about to be tagged."
 
   :type 'hook
   :options '(notmuch-hl-line-mode)
@@ -363,7 +363,7 @@ (defcustom notmuch-after-tag-hook nil
 'tag-changes' will contain the tags that were added or removed as
 a list of strings of the form \"+TAG\" or \"-TAG\".
 'query' will be a string containing the search query that determines
-the messages that were tagged"
+the messages that were tagged."
   :type 'hook
   :options '(notmuch-hl-line-mode)
   :group 'notmuch-hooks)
diff --git a/emacs/notmuch-tree.el b/emacs/notmuch-tree.el
index 254664c4..398a14da 100644
--- a/emacs/notmuch-tree.el
+++ b/emacs/notmuch-tree.el
@@ -45,7 +45,7 @@ (defvar notmuch-search-query-string)
 
 ;; this variable distinguishes the unthreaded display from the normal tree display
 (defvar notmuch-tree-unthreaded nil
-  "A buffer local copy of argument unthreaded to the function notmuch-tree")
+  "A buffer local copy of argument unthreaded to the function notmuch-tree.")
 (make-variable-buffer-local 'notmuch-tree-unthreaded)
 
 (defgroup notmuch-tree nil
@@ -73,17 +73,17 @@ (defcustom notmuch-tree-result-format
     ((("tree" . "%s")("subject" . "%s")) ." %-54s ")
     ("tags" . "(%s)"))
   "Result formatting for Tree view. Supported fields are: date,
-        authors, subject, tree, tags.  Tree means the thread tree
-        box graphics. The field may also be a list in which case
-        the formatting rules are applied recursively and then the
-        output of all the fields in the list is inserted
-        according to format-string.
+authors, subject, tree, tags.  Tree means the thread tree
+box graphics. The field may also be a list in which case
+the formatting rules are applied recursively and then the
+output of all the fields in the list is inserted
+according to format-string.
 
 Note the author string should not contain
-        whitespace (put it in the neighbouring fields instead).
-        For example:
-        (setq notmuch-tree-result-format \(\(\"authors\" . \"%-40s\"\)
-                                             \(\"subject\" . \"%s\"\)\)\)"
+whitespace (put it in the neighbouring fields instead).
+For example:
+(setq notmuch-tree-result-format \(\(\"authors\" . \"%-40s\"\)
+                                  \(\"subject\" . \"%s\"\)\)\)"
   :type '(alist :key-type (string) :value-type (string))
   :group 'notmuch-tree)
 
@@ -93,17 +93,17 @@ (defcustom notmuch-unthreaded-result-format
     ((("subject" . "%s")) ." %-54s ")
     ("tags" . "(%s)"))
   "Result formatting for unthreaded Tree view. Supported fields are: date,
-        authors, subject, tree, tags.  Tree means the thread tree
-        box graphics. The field may also be a list in which case
-        the formatting rules are applied recursively and then the
-        output of all the fields in the list is inserted
-        according to format-string.
+authors, subject, tree, tags.  Tree means the thread tree
+box graphics. The field may also be a list in which case
+the formatting rules are applied recursively and then the
+output of all the fields in the list is inserted
+according to format-string.
 
 Note the author string should not contain
-        whitespace (put it in the neighbouring fields instead).
-        For example:
-        (setq notmuch-tree-result-format \(\(\"authors\" . \"%-40s\"\)
-                                             \(\"subject\" . \"%s\"\)\)\)"
+whitespace (put it in the neighbouring fields instead).
+For example:
+(setq notmuch-tree-result-format \(\(\"authors\" . \"%-40s\"\)
+                                  \(\"subject\" . \"%s\"\)\)\)"
   :type '(alist :key-type (string) :value-type (string))
   :group 'notmuch-tree)
 
@@ -166,7 +166,7 @@ (defface notmuch-tree-match-tag-face
 ;; Faces for messages that do not match the query.
 (defface notmuch-tree-no-match-face
   '((t (:foreground "gray")))
-  "Default face used in tree mode face for non-matching messages"
+  "Default face used in tree mode face for non-matching messages."
   :group 'notmuch-tree
   :group 'notmuch-faces)
 
@@ -201,23 +201,23 @@ (defface notmuch-tree-no-match-tag-face
   :group 'notmuch-faces)
 
 (defvar notmuch-tree-previous-subject
-  "The subject of the most recent result shown during the async display")
+  "The subject of the most recent result shown during the async display.")
 (make-variable-buffer-local 'notmuch-tree-previous-subject)
 
 (defvar notmuch-tree-basic-query nil
-  "A buffer local copy of argument query to the function notmuch-tree")
+  "A buffer local copy of argument query to the function notmuch-tree.")
 (make-variable-buffer-local 'notmuch-tree-basic-query)
 
 (defvar notmuch-tree-query-context nil
-  "A buffer local copy of argument query-context to the function notmuch-tree")
+  "A buffer local copy of argument query-context to the function notmuch-tree.")
 (make-variable-buffer-local 'notmuch-tree-query-context)
 
 (defvar notmuch-tree-target-msg nil
-  "A buffer local copy of argument target to the function notmuch-tree")
+  "A buffer local copy of argument target to the function notmuch-tree.")
 (make-variable-buffer-local 'notmuch-tree-target-msg)
 
 (defvar notmuch-tree-open-target nil
-  "A buffer local copy of argument open-target to the function notmuch-tree")
+  "A buffer local copy of argument open-target to the function notmuch-tree.")
 (make-variable-buffer-local 'notmuch-tree-open-target)
 
 (defvar notmuch-tree-message-window nil
@@ -251,14 +251,14 @@ (defun notmuch-tree-to-message-pane (func)
 	 (call-interactively #',func)))))
 
 (defun notmuch-tree-inherit-from-message-pane (sym)
-  "Return value of SYM in message-pane if open, or tree-pane if not"
+  "Return value of SYM in message-pane if open, or tree-pane if not."
   (if (window-live-p notmuch-tree-message-window)
       (with-selected-window notmuch-tree-message-window
 	(symbol-value sym))
     (symbol-value sym)))
 
 (defun notmuch-tree-button-activate (&optional button)
-  "Activate BUTTON or button at point
+  "Activate BUTTON or button at point.
 
 This function does not give an error if there is no button."
   (interactive)
@@ -346,7 +346,7 @@ (defun notmuch-tree-get-message-properties ()
 
 Some useful entries are:
 :headers - Property list containing the headers :Date, :Subject, :From, etc.
-:tags - Tags for this message"
+:tags - Tags for this message."
   (save-excursion
     (beginning-of-line)
     (get-text-property (point) :notmuch-message-properties)))
@@ -432,7 +432,7 @@ (defun notmuch-tree-tag-update-display (&optional tag-changes)
 	    (notmuch-show-update-tags new-tags)))))))
 
 (defun notmuch-tree-tag (tag-changes)
-  "Change tags for the current message"
+  "Change tags for the current message."
   (interactive
    (list (notmuch-read-tag-changes (notmuch-tree-get-tags) "Tag message")))
   (notmuch-tag (notmuch-tree-get-message-id) tag-changes)
@@ -472,26 +472,26 @@ (defun notmuch-tree-to-search ()
     (notmuch-search query)))
 
 (defun notmuch-tree-to-tree ()
-  "Run a query and display results in Tree view"
+  "Run a query and display results in Tree view."
   (interactive)
   (let ((query (notmuch-read-query "Notmuch tree view search: ")))
     (notmuch-tree-close-message-window)
     (notmuch-tree query)))
 
 (defun notmuch-unthreaded-from-tree-current-query ()
-  "Switch from tree view to unthreaded view"
+  "Switch from tree view to unthreaded view."
   (interactive)
   (unless notmuch-tree-unthreaded
     (notmuch-tree-refresh-view 'unthreaded)))
 
 (defun notmuch-tree-from-unthreaded-current-query ()
-  "Switch from unthreaded view to tree view"
+  "Switch from unthreaded view to tree view."
   (interactive)
   (when notmuch-tree-unthreaded
     (notmuch-tree-refresh-view 'tree)))
 
 (defun notmuch-search-from-tree-current-query ()
-  "Call notmuch search with the current query"
+  "Call notmuch search with the current query."
   (interactive)
   (notmuch-tree-close-message-window)
   (notmuch-search (notmuch-tree-get-query)))
@@ -563,7 +563,7 @@ (defun notmuch-tree-show-message (arg)
     (notmuch-tree-show-message-in)))
 
 (defun notmuch-tree-scroll-message-window ()
-  "Scroll the message window (if it exists)"
+  "Scroll the message window (if it exists)."
   (interactive)
   (when (window-live-p notmuch-tree-message-window)
     (with-selected-window notmuch-tree-message-window
@@ -572,7 +572,7 @@ (defun notmuch-tree-scroll-message-window ()
 	(scroll-up)))))
 
 (defun notmuch-tree-scroll-message-window-back ()
-  "Scroll the message window back(if it exists)"
+  "Scroll the message window back(if it exists)."
   (interactive)
   (when (window-live-p notmuch-tree-message-window)
     (with-selected-window notmuch-tree-message-window
@@ -661,7 +661,7 @@ (defun notmuch-tree-goto-matching-message (&optional prev)
     (not (funcall eobfn))))
 
 (defun notmuch-tree-matching-message (&optional prev pop-at-end)
-  "Move to the next or previous matching message"
+  "Move to the next or previous matching message."
   (interactive "P")
   (forward-line (if prev -1 nil))
   (if (and (not (notmuch-tree-goto-matching-message prev)) pop-at-end)
@@ -734,7 +734,7 @@ (defun notmuch-tree-get-messages-ids-thread-search ()
 	     " or "))
 
 (defun notmuch-tree-tag-thread (tag-changes)
-  "Tag all messages in the current thread"
+  "Tag all messages in the current thread."
   (interactive
    (let ((tags (apply #'append (notmuch-tree-thread-mapcar
 				(lambda () (notmuch-tree-get-tags))))))
@@ -775,7 +775,7 @@ (defun notmuch-tree-clean-address (address)
     (or p-name p-address)))
 
 (defun notmuch-tree-format-field (field format-string msg)
-  "Format a FIELD of MSG according to FORMAT-STRING and return string"
+  "Format a FIELD of MSG according to FORMAT-STRING and return string."
   (let* ((headers (plist-get msg :headers))
 	 (match (plist-get msg :match)))
     (cond
@@ -831,7 +831,7 @@ (defun notmuch-tree-format-field (field format-string msg)
 	(format format-string (notmuch-tag-format-tags tags orig-tags face)))))))
 
 (defun notmuch-tree-format-field-list (field-list msg)
-  "Format fields of MSG according to FIELD-LIST and return string"
+  "Format fields of MSG according to FIELD-LIST and return string."
   (let ((face (if (plist-get msg :match)
 		  'notmuch-tree-match-face
 		'notmuch-tree-no-match-face))
@@ -842,7 +842,7 @@ (defun notmuch-tree-format-field-list (field-list msg)
     (notmuch-apply-face result-string face t)))
 
 (defun notmuch-tree-insert-msg (msg)
-  "Insert the message MSG according to notmuch-tree-result-format"
+  "Insert the message MSG according to notmuch-tree-result-format."
   ;; We need to save the previous subject as it will get overwritten
   ;; by the insert-field calls.
   (let ((previous-subject notmuch-tree-previous-subject))
@@ -852,7 +852,7 @@ (defun notmuch-tree-insert-msg (msg)
     (insert "\n")))
 
 (defun notmuch-tree-goto-and-insert-msg (msg)
-  "Insert msg at the end of the buffer. Move point to msg if it is the target"
+  "Insert msg at the end of the buffer. Move point to msg if it is the target."
   (save-excursion
     (goto-char (point-max))
     (notmuch-tree-insert-msg msg))
@@ -946,7 +946,7 @@ (define-derived-mode notmuch-tree-mode fundamental-mode "notmuch-tree"
 	truncate-lines t))
 
 (defun notmuch-tree-process-sentinel (proc msg)
-  "Add a message to let user know when \"notmuch tree\" exits"
+  "Add a message to let user know when \"notmuch tree\" exits."
   (let ((buffer (process-buffer proc))
 	(status (process-status proc))
 	(exit-status (process-exit-status proc))
@@ -968,7 +968,7 @@ (defun notmuch-tree-process-sentinel (proc msg)
 		    (insert "\n")))))))))
 
 (defun notmuch-tree-process-filter (proc string)
-  "Process and filter the output of \"notmuch show\" for tree view"
+  "Process and filter the output of \"notmuch show\" for tree view."
   (let ((results-buf (process-buffer proc))
         (parse-buf (process-get proc 'parse-buf))
         (inhibit-read-only t)
@@ -1026,7 +1026,7 @@ (defun notmuch-tree-worker (basic-query &optional query-context target open-targ
       (set-process-query-on-exit-flag proc nil))))
 
 (defun notmuch-tree-get-query ()
-  "Return the current query in this tree buffer"
+  "Return the current query in this tree buffer."
   (if notmuch-tree-query-context
       (concat notmuch-tree-basic-query
 	      " and ("
diff --git a/emacs/notmuch-wash.el b/emacs/notmuch-wash.el
index 54108d93..fd0314cc 100644
--- a/emacs/notmuch-wash.el
+++ b/emacs/notmuch-wash.el
@@ -192,7 +192,7 @@ (defun notmuch-wash-button-label (overlay)
     (format label-format lines-count)))
 
 (defun notmuch-wash-region-to-button (msg beg end type &optional prefix)
-  "Auxiliary function to do the actual making of overlays and buttons
+  "Auxiliary function to do the actual making of overlays and buttons.
 
 BEG and END are buffer locations. TYPE should a string, either
 \"citation\" or \"signature\". Optional PREFIX is some arbitrary
diff --git a/emacs/notmuch.el b/emacs/notmuch.el
index a980c7a2..40caa280 100644
--- a/emacs/notmuch.el
+++ b/emacs/notmuch.el
@@ -113,7 +113,7 @@ (defcustom notmuch-init-file (locate-user-emacs-file "notmuch-config")
   :group 'notmuch)
 
 (defvar notmuch-query-history nil
-  "Variable to store minibuffer history for notmuch queries")
+  "Variable to store minibuffer history for notmuch queries.")
 
 (defun notmuch-foreach-mime-part (function mm-handle)
   (cond ((stringp (car mm-handle))
@@ -202,7 +202,7 @@ (defvar notmuch-search-stash-map
     (define-key map "q" 'notmuch-stash-query)
     (define-key map "?" 'notmuch-subkeymap-help)
     map)
-  "Submap for stash commands")
+  "Submap for stash commands.")
 (fset 'notmuch-search-stash-map notmuch-search-stash-map)
 
 (defun notmuch-search-stash-thread-id ()
@@ -417,7 +417,7 @@ (defun notmuch-search-result-end (&optional pos)
 
 The returned point will be just after the newline character that
 ends the result line.  If there is no thread at POS (or point),
-returns nil"
+returns nil."
   (when (notmuch-search-get-result pos)
     (next-single-property-change (or pos (point)) 'notmuch-search-result
 				 nil (point-max))))
@@ -457,9 +457,9 @@ (defun notmuch-search-properties-in-region (property beg end)
     output))
 
 (defun notmuch-search-find-thread-id (&optional bare)
-  "Return the thread for the current thread
+  "Return the thread for the current thread.
 
-If BARE is set then do not prefix with \"thread:\""
+If BARE is set then do not prefix with \"thread:\"."
   (let ((thread (plist-get (notmuch-search-get-result) :thread)))
     (when thread (concat (unless bare "thread:") thread))))
 
@@ -486,19 +486,19 @@ (defun notmuch-search-find-stable-query-region (beg end &optional only-matched)
       (concat "(" (mapconcat 'identity query-list ") or (") ")"))))
 
 (defun notmuch-search-find-authors ()
-  "Return the authors for the current thread"
+  "Return the authors for the current thread."
   (plist-get (notmuch-search-get-result) :authors))
 
 (defun notmuch-search-find-authors-region (beg end)
-  "Return a list of authors for the current region"
+  "Return a list of authors for the current region."
   (notmuch-search-properties-in-region :authors beg end))
 
 (defun notmuch-search-find-subject ()
-  "Return the subject for the current thread"
+  "Return the subject for the current thread."
   (plist-get (notmuch-search-get-result) :subject))
 
 (defun notmuch-search-find-subject-region (beg end)
-  "Return a list of authors for the current region"
+  "Return a list of authors for the current region."
   (notmuch-search-properties-in-region :subject beg end))
 
 (defun notmuch-search-show-thread (&optional elide-toggle)
@@ -520,22 +520,22 @@ (defun notmuch-search-show-thread (&optional elide-toggle)
       (message "End of search results."))))
 
 (defun notmuch-tree-from-search-current-query ()
-  "Call notmuch tree with the current query"
+  "Call notmuch tree with the current query."
   (interactive)
   (notmuch-tree notmuch-search-query-string))
 
 (defun notmuch-unthreaded-from-search-current-query ()
-  "Call notmuch tree with the current query"
+  "Call notmuch tree with the current query."
   (interactive)
   (notmuch-unthreaded notmuch-search-query-string))
 
 (defun notmuch-tree-from-search-thread ()
-  "Show the selected thread with notmuch-tree"
+  "Show the selected thread with notmuch-tree."
   (interactive)
   (notmuch-tree (notmuch-search-find-thread-id)
-                notmuch-search-query-string
+		notmuch-search-query-string
 		nil
-                (notmuch-prettify-subject (notmuch-search-find-subject))
+		(notmuch-prettify-subject (notmuch-search-find-subject))
 		t))
 
 (defun notmuch-search-reply-to-thread (&optional prompt-for-sender)
@@ -660,7 +660,7 @@ (defun notmuch-search-update-result (result &optional pos)
 	(goto-char new-point)))))
 
 (defun notmuch-search-process-sentinel (proc msg)
-  "Add a message to let user know when \"notmuch search\" exits"
+  "Add a message to let user know when \"notmuch search\" exits."
   (let ((buffer (process-buffer proc))
 	(status (process-status proc))
 	(exit-status (process-exit-status proc))
@@ -862,7 +862,7 @@ (defun notmuch-search-append-result (result)
       (goto-char pos))))
 
 (defun notmuch-search-process-filter (proc string)
-  "Process and filter the output of \"notmuch search\""
+  "Process and filter the output of \"notmuch search\"."
   (let ((results-buf (process-buffer proc))
 	(parse-buf (process-get proc 'parse-buf))
 	(inhibit-read-only t)
@@ -952,7 +952,7 @@ (defun notmuch-read-query (prompt)
 			      'notmuch-search-history current-query nil)))))
 
 (defun notmuch-search-get-query ()
-  "Return the current query in this search buffer"
+  "Return the current query in this search buffer."
   notmuch-search-query-string)
 
 (put 'notmuch-search 'notmuch-doc "Search for messages.")
-- 
2.20.1


^ permalink raw reply related	[flat|nested] 5+ messages in thread

* Re: [PATCH] emacs docstrings: consistent indentation, newlines, periods
  2020-05-03 21:21 Tomi Ollila
@ 2020-05-21 21:47 ` Daniel Kahn Gillmor
  2020-05-21 22:08   ` Tomi Ollila
  0 siblings, 1 reply; 5+ messages in thread
From: Daniel Kahn Gillmor @ 2020-05-21 21:47 UTC (permalink / raw)
  To: Tomi Ollila, notmuch


[-- Attachment #1.1: Type: text/plain, Size: 3042 bytes --]

On Mon 2020-05-04 00:21:36 +0300, Tomi Ollila wrote:
> Fixed emacs docstrings to be consistent. No functional change.
>
> - removed some (accidental) indentation
> - removed some trailing newlines
> - added trailing periods where missing (some exclusions)

This all looks good to me, except for the following changes.

I think if the last line of the docstring is an example, deliberately
indented to indicate that it is verbatim code, adding a trailing period
is a mistake, because it encourages naive users to make the obvious
error of including the period in their text.

These were the examples i noticed in a skim of the changeset:

> --- a/emacs/notmuch-draft.el
> +++ b/emacs/notmuch-draft.el
> @@ -45,7 +45,7 @@ (defcustom notmuch-draft-tags '("+draft")
>  For example, if you wanted to give the message a \"draft\" tag
>  but not the (normally added by default) \"inbox\" tag, you would
>  set:
> -    (\"+draft\" \"-inbox\")"
> +    (\"+draft\" \"-inbox\")."
>    :type '(repeat string)
>    :group 'notmuch-draft)
>  


> --- a/emacs/notmuch-lib.el
> +++ b/emacs/notmuch-lib.el
> @@ -145,7 +145,7 @@ (defcustom notmuch-archive-tags '("-inbox")
>  
>  For example, if you wanted to remove an \"inbox\" tag and add an
>  \"archived\" tag, you would set:
> -    (\"-inbox\" \"+archived\")"
> +    (\"-inbox\" \"+archived\")."
>    :type '(repeat string)
>    :group 'notmuch-search
>    :group 'notmuch-show)


> --- a/emacs/notmuch-message.el
> +++ b/emacs/notmuch-message.el
> @@ -33,7 +33,7 @@ (defcustom notmuch-message-replied-tags '("+replied")
>  
>  For example, if you wanted to add a \"replied\" tag and remove
>  the \"inbox\" and \"todo\" tags, you would set:
> -    (\"+replied\" \"-inbox\" \"-todo\")"
> +    (\"+replied\" \"-inbox\" \"-todo\")."
>    :type '(repeat string)
>    :group 'notmuch-send)
>  
> @@ -46,7 +46,7 @@ (defcustom notmuch-message-forwarded-tags '("+forwarded")
>  
>  For example, if you wanted to add a \"forwarded\" tag and remove
>  the \"inbox\" tag, you would set:
> -    (\"+forwarded\" \"-inbox\")"
> +    (\"+forwarded\" \"-inbox\")."
>    :type '(repeat string)
>    :group 'notmuch-send)


> --- a/emacs/notmuch-show.el
> +++ b/emacs/notmuch-show.el
> @@ -237,7 +237,7 @@ (defcustom notmuch-show-mark-read-tags '("-unread")
>  
>  For example, if you wanted to remove an \"unread\" tag and add a
>  \"read\" tag (which would make little sense), you would set:
> -    (\"-unread\" \"+read\")"
> +    (\"-unread\" \"+read\")."
>    :type '(repeat string)
>    :group 'notmuch-show)


I'd prefer this changeset to not have trailing periods when the
docstring ends in an example.   (and maybe also to clean up any trailing
periods that might already be in such a docstring, if they exist)

I recognize this is something of an aesthetic position with no
objectively correct answer, but so is the question of trailing periods,
i suppose.  I'm not going to die on this hill, though.

Regards,

        --dkg

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

[-- Attachment #2: Type: text/plain, Size: 0 bytes --]



^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [PATCH] emacs docstrings: consistent indentation, newlines, periods
  2020-05-21 21:47 ` Daniel Kahn Gillmor
@ 2020-05-21 22:08   ` Tomi Ollila
  0 siblings, 0 replies; 5+ messages in thread
From: Tomi Ollila @ 2020-05-21 22:08 UTC (permalink / raw)
  To: Daniel Kahn Gillmor, notmuch

On Thu, May 21 2020, Daniel Kahn Gillmor wrote:

> On Mon 2020-05-04 00:21:36 +0300, Tomi Ollila wrote:
>> Fixed emacs docstrings to be consistent. No functional change.
>>
>> - removed some (accidental) indentation
>> - removed some trailing newlines
>> - added trailing periods where missing (some exclusions)
>
> This all looks good to me, except for the following changes.
>
> I think if the last line of the docstring is an example, deliberately
> indented to indicate that it is verbatim code, adding a trailing period
> is a mistake, because it encourages naive users to make the obvious
> error of including the period in their text.
>
> These were the examples i noticed in a skim of the changeset:
>
>> --- a/emacs/notmuch-draft.el
>> +++ b/emacs/notmuch-draft.el
>> @@ -45,7 +45,7 @@ (defcustom notmuch-draft-tags '("+draft")
>>  For example, if you wanted to give the message a \"draft\" tag
>>  but not the (normally added by default) \"inbox\" tag, you would
>>  set:
>> -    (\"+draft\" \"-inbox\")"
>> +    (\"+draft\" \"-inbox\")."
>>    :type '(repeat string)
>>    :group 'notmuch-draft)
>>  
>
>
>> --- a/emacs/notmuch-lib.el
>> +++ b/emacs/notmuch-lib.el
>> @@ -145,7 +145,7 @@ (defcustom notmuch-archive-tags '("-inbox")
>>  
>>  For example, if you wanted to remove an \"inbox\" tag and add an
>>  \"archived\" tag, you would set:
>> -    (\"-inbox\" \"+archived\")"
>> +    (\"-inbox\" \"+archived\")."
>>    :type '(repeat string)
>>    :group 'notmuch-search
>>    :group 'notmuch-show)
>
>
>> --- a/emacs/notmuch-message.el
>> +++ b/emacs/notmuch-message.el
>> @@ -33,7 +33,7 @@ (defcustom notmuch-message-replied-tags '("+replied")
>>  
>>  For example, if you wanted to add a \"replied\" tag and remove
>>  the \"inbox\" and \"todo\" tags, you would set:
>> -    (\"+replied\" \"-inbox\" \"-todo\")"
>> +    (\"+replied\" \"-inbox\" \"-todo\")."
>>    :type '(repeat string)
>>    :group 'notmuch-send)
>>  
>> @@ -46,7 +46,7 @@ (defcustom notmuch-message-forwarded-tags '("+forwarded")
>>  
>>  For example, if you wanted to add a \"forwarded\" tag and remove
>>  the \"inbox\" tag, you would set:
>> -    (\"+forwarded\" \"-inbox\")"
>> +    (\"+forwarded\" \"-inbox\")."
>>    :type '(repeat string)
>>    :group 'notmuch-send)
>
>
>> --- a/emacs/notmuch-show.el
>> +++ b/emacs/notmuch-show.el
>> @@ -237,7 +237,7 @@ (defcustom notmuch-show-mark-read-tags '("-unread")
>>  
>>  For example, if you wanted to remove an \"unread\" tag and add a
>>  \"read\" tag (which would make little sense), you would set:
>> -    (\"-unread\" \"+read\")"
>> +    (\"-unread\" \"+read\")."
>>    :type '(repeat string)
>>    :group 'notmuch-show)
>
>
> I'd prefer this changeset to not have trailing periods when the
> docstring ends in an example.   (and maybe also to clean up any trailing
> periods that might already be in such a docstring, if they exist)
>
> I recognize this is something of an aesthetic position with no
> objectively correct answer, but so is the question of trailing periods,
> i suppose.  I'm not going to die on this hill, though.

I agree with your point. Like I mentioned I excluded trailing period at
least in one case where missing, probably similar to this. I have to
reconsider also to re-indent some content after For example: 

How I did the changeset I used David's rstdoc.el to get long list of all
docstrings and then looked through that and went editing original .el
files -- monotonic changes makes one blind of all kinds of considerations.

>
> Regards,
>
>         --dkg

Tomi

^ permalink raw reply	[flat|nested] 5+ messages in thread

* [PATCH] emacs docstrings: consistent indentation, newlines, periods
@ 2020-05-24 19:17 Tomi Ollila
  2020-06-06 11:50 ` David Bremner
  0 siblings, 1 reply; 5+ messages in thread
From: Tomi Ollila @ 2020-05-24 19:17 UTC (permalink / raw)
  To: notmuch; +Cc: tomi.ollila

Fixed emacs docstrings to be consistent. No functional change.

- removed some (accidental) indentation
- removed some trailing newlines
- added trailing periods where missing (some exclusions)
---

V2 of id:"20200503212136.11070-1-tomi.ollila@iki.fi"

changes to v1:
- trailing periods removed when example code in comments
- re-indented (setq's after For example: ..
- all 'tree view' consistently uncapitalized now 

 emacs/notmuch-address.el     | 21 ++++-----
 emacs/notmuch-draft.el       |  6 +--
 emacs/notmuch-hello.el       | 11 ++---
 emacs/notmuch-jump.el        |  3 +-
 emacs/notmuch-lib.el         |  8 ++--
 emacs/notmuch-maildir-fcc.el |  4 +-
 emacs/notmuch-mua.el         |  2 +-
 emacs/notmuch-query.el       | 13 +++---
 emacs/notmuch-show.el        | 22 ++++-----
 emacs/notmuch-tag.el         |  8 ++--
 emacs/notmuch-tree.el        | 90 ++++++++++++++++++------------------
 emacs/notmuch-wash.el        |  2 +-
 emacs/notmuch.el             | 34 +++++++-------
 13 files changed, 110 insertions(+), 114 deletions(-)

diff --git a/emacs/notmuch-address.el b/emacs/notmuch-address.el
index 64887a43..0d56fba7 100644
--- a/emacs/notmuch-address.el
+++ b/emacs/notmuch-address.el
@@ -29,11 +29,11 @@
 (declare-function company-manual-begin "company")
 
 (defvar notmuch-address-last-harvest 0
-  "Time of last address harvest")
+  "Time of last address harvest.")
 
 (defvar notmuch-address-completions (make-hash-table :test 'equal)
   "Hash of email addresses for completion during email composition.
-  This variable is set by calling `notmuch-address-harvest'.")
+This variable is set by calling `notmuch-address-harvest'.")
 
 (defvar notmuch-address-full-harvest-finished nil
   "t indicates that full completion address harvesting has been
@@ -73,11 +73,11 @@ (defcustom notmuch-address-internal-completion '(sent nil)
   "Determines how internal address completion generates candidates.
 
 This should be a list of the form '(DIRECTION FILTER), where
- DIRECTION is either sent or received and specifies whether the
- candidates are searched in messages sent by the user or received
- by the user (note received by is much faster), and FILTER is
- either nil or a filter-string, such as \"date:1y..\" to append
- to the query."
+DIRECTION is either sent or received and specifies whether the
+candidates are searched in messages sent by the user or received
+by the user (note received by is much faster), and FILTER is
+either nil or a filter-string, such as \"date:1y..\" to append
+to the query."
   :type '(list :tag "Use internal address completion"
 	       (radio
 		:tag "Base completion on messages you have"
@@ -126,8 +126,7 @@ (defcustom notmuch-address-post-completion-functions nil
 
 The completed address is passed as an argument to each function.
 Note that this hook will be invoked for completion in headers
-matching `notmuch-address-completion-headers-regexp'.
-"
+matching `notmuch-address-completion-headers-regexp'."
   :type 'hook
   :group 'notmuch-address
   :group 'notmuch-hooks)
@@ -147,7 +146,7 @@ (defun notmuch-address-message-insinuate ()
   (message "calling notmuch-address-message-insinuate is no longer needed"))
 
 (defcustom notmuch-address-use-company t
-  "If available, use company mode for address completion"
+  "If available, use company mode for address completion."
   :type 'boolean
   :group 'notmuch-send
   :group 'notmuch-address)
@@ -285,7 +284,7 @@ (defun notmuch-address-harvest-filter (proc string)
 (defvar notmuch-address-harvest-procs '(nil . nil)
   "The currently running harvests.
 
-The car is a partial harvest, and the cdr is a full harvest")
+The car is a partial harvest, and the cdr is a full harvest.")
 
 (defun notmuch-address-harvest (&optional addr-prefix synchronous callback)
   "Collect addresses completion candidates.
diff --git a/emacs/notmuch-draft.el b/emacs/notmuch-draft.el
index 504b33be..27abc7d9 100644
--- a/emacs/notmuch-draft.el
+++ b/emacs/notmuch-draft.el
@@ -76,7 +76,7 @@ (defcustom notmuch-draft-quoted-tags '()
 
 (defcustom notmuch-draft-save-plaintext 'ask
   "Should notmuch save/postpone in plaintext messages that seem
-  like they are intended to be sent encrypted
+like they are intended to be sent encrypted
 (i.e with an mml encryption tag in it)."
   :type '(radio
 	  (const :tag "Never" nil)
@@ -87,10 +87,10 @@ (defcustom notmuch-draft-save-plaintext 'ask
 
 (defvar notmuch-draft-encryption-tag-regex
   "<#\\(part encrypt\\|secure.*mode=.*encrypt>\\)"
-  "Regular expression matching mml tags indicating encryption of part or message")
+  "Regular expression matching mml tags indicating encryption of part or message.")
 
 (defvar notmuch-draft-id nil
-  "Message-id of the most recent saved draft of this message")
+  "Message-id of the most recent saved draft of this message.")
 (make-variable-buffer-local 'notmuch-draft-id)
 
 (defun notmuch-draft--mark-deleted ()
diff --git a/emacs/notmuch-hello.el b/emacs/notmuch-hello.el
index bdf584e6..0ff5aaff 100644
--- a/emacs/notmuch-hello.el
+++ b/emacs/notmuch-hello.el
@@ -359,7 +359,7 @@ (defcustom notmuch-hello-auto-refresh t
   :type 'boolean)
 
 (defvar notmuch-hello-hidden-sections nil
-  "List of sections titles whose contents are hidden")
+  "List of sections titles whose contents are hidden.")
 
 (defvar notmuch-hello-first-run t
   "True if `notmuch-hello' is run for the first time, set to nil
@@ -501,8 +501,7 @@ (defun notmuch-hello-filtered-query (query filter)
 the string it returns is used as the query. If nil is returned,
 the entry is hidden.
 
-Otherwise, FILTER is ignored.
-"
+Otherwise, FILTER is ignored."
   (cond
    ((functionp filter) (funcall filter query))
    ((stringp filter)
@@ -656,7 +655,7 @@ (defun notmuch-hello-window-configuration-change ()
 (defvar notmuch-emacs-version)
 
 (defun notmuch-hello-versions ()
-  "Display the notmuch version(s)"
+  "Display the notmuch version(s)."
   (interactive)
   (let ((notmuch-cli-version (notmuch-cli-version)))
     (message "notmuch version %s"
@@ -923,7 +922,7 @@ (defun notmuch-hello-insert-tags-section (&optional title &rest options)
 	 options))
 
 (defun notmuch-hello-insert-inbox ()
-  "Show an entry for each saved search and inboxed messages for each tag"
+  "Show an entry for each saved search and inboxed messages for each tag."
   (notmuch-hello-insert-searches "What's in your inbox"
 				 (append
 				  notmuch-saved-searches
@@ -931,7 +930,7 @@ (defun notmuch-hello-insert-inbox ()
 				 :filter "tag:inbox"))
 
 (defun notmuch-hello-insert-alltags ()
-  "Insert a section displaying all tags and associated message counts"
+  "Insert a section displaying all tags and associated message counts."
   (notmuch-hello-insert-tags-section
    nil
    :initially-hidden (not notmuch-show-all-tags-list)
diff --git a/emacs/notmuch-jump.el b/emacs/notmuch-jump.el
index 92a5a2cc..84fe2b9c 100644
--- a/emacs/notmuch-jump.el
+++ b/emacs/notmuch-jump.el
@@ -88,8 +88,7 @@ (defun notmuch-jump (action-map prompt)
 where KEY is a key binding, LABEL is a string label to display in
 the buffer, and ACTION is a nullary function to call.  LABEL may
 be null, in which case the action will still be bound, but will
-not appear in the pop-up buffer.
-"
+not appear in the pop-up buffer."
 
   (let* ((items (notmuch-jump--format-actions action-map))
 	 ;; Format the table of bindings and the full prompt
diff --git a/emacs/notmuch-lib.el b/emacs/notmuch-lib.el
index 01862f44..0bb08eb2 100644
--- a/emacs/notmuch-lib.el
+++ b/emacs/notmuch-lib.el
@@ -189,7 +189,7 @@ (defun notmuch-command-to-string (&rest args)
 will appear in a buffer named \"*Notmuch errors*\" and an error
 will be signaled.
 
-Otherwise the output will be returned"
+Otherwise the output will be returned."
   (with-temp-buffer
     (let* ((status (apply #'call-process notmuch-command nil t nil args))
 	   (output (buffer-string)))
@@ -299,7 +299,7 @@ (defun notmuch-prefix-key-description (key)
 
 
 (defun notmuch-describe-key (actual-key binding prefix ua-keys tail)
-  "Prepend cons cells describing prefix-arg ACTUAL-KEY and ACTUAL-KEY to TAIL
+  "Prepend cons cells describing prefix-arg ACTUAL-KEY and ACTUAL-KEY to TAIL.
 
 It does not prepend if ACTUAL-KEY is already listed in TAIL."
   (let ((key-string (concat prefix (key-description actual-key))))
@@ -530,11 +530,11 @@ (defun notmuch-plist-delete (plist property)
     (cdr xplist)))
 
 (defun notmuch-split-content-type (content-type)
-  "Split content/type into 'content' and 'type'"
+  "Split content/type into 'content' and 'type'."
   (split-string content-type "/"))
 
 (defun notmuch-match-content-type (t1 t2)
-  "Return t if t1 and t2 are matching content types, taking wildcards into account"
+  "Return t if t1 and t2 are matching content types, taking wildcards into account."
   (let ((st1 (notmuch-split-content-type t1))
 	(st2 (notmuch-split-content-type t2)))
     (if (or (string= (cadr st1) "*")
diff --git a/emacs/notmuch-maildir-fcc.el b/emacs/notmuch-maildir-fcc.el
index b9cca543..e95de63b 100644
--- a/emacs/notmuch-maildir-fcc.el
+++ b/emacs/notmuch-maildir-fcc.el
@@ -78,7 +78,7 @@ (defcustom notmuch-fcc-dirs "sent"
  :group 'notmuch-send)
 
 (defcustom notmuch-maildir-use-notmuch-insert 't
-  "Should fcc use notmuch insert instead of simple fcc"
+  "Should fcc use notmuch insert instead of simple fcc."
   :type '(choice :tag "Fcc Method"
 		 (const :tag "Use notmuch insert" t)
 		 (const :tag "Use simple fcc" nil))
@@ -93,7 +93,7 @@ (defun notmuch-fcc-header-setup ()
 Sets the Fcc header based on the values of `notmuch-fcc-dirs'.
 
 Originally intended to be use a hook function, but now called directly
-by notmuch-mua-mail"
+by notmuch-mua-mail."
 
   (let ((subdir
 	 (cond
diff --git a/emacs/notmuch-mua.el b/emacs/notmuch-mua.el
index 40a1e6bc..1efc88ea 100644
--- a/emacs/notmuch-mua.el
+++ b/emacs/notmuch-mua.el
@@ -334,7 +334,7 @@ (defun notmuch-mua-reply (query-string &optional sender reply-all)
   (set-buffer-modified-p nil))
 
 (define-derived-mode notmuch-message-mode message-mode "Message[Notmuch]"
-  "Notmuch message composition mode. Mostly like `message-mode'"
+  "Notmuch message composition mode. Mostly like `message-mode'."
   (notmuch-address-setup))
 
 (put 'notmuch-message-mode 'flyspell-mode-predicate 'mail-mode-flyspell-verify)
diff --git a/emacs/notmuch-query.el b/emacs/notmuch-query.el
index 563e4acf..3a835a00 100644
--- a/emacs/notmuch-query.el
+++ b/emacs/notmuch-query.el
@@ -28,8 +28,7 @@ (defun notmuch-query-get-threads (search-terms)
 
 A thread is a forest or list of trees. A tree is a two element
 list where the first element is a message, and the second element
-is a possibly empty forest of replies.
-"
+is a possibly empty forest of replies."
   (let ((args '("show" "--format=sexp" "--format-version=4")))
     (if notmuch-show-process-crypto
 	(setq args (append args '("--decrypt=true"))))
@@ -40,7 +39,7 @@ (defun notmuch-query-get-threads (search-terms)
 ;; Mapping functions across collections of messages.
 
 (defun notmuch-query-map-aux  (mapper function seq)
-  "private function to do the actual mapping and flattening"
+  "Private function to do the actual mapping and flattening."
   (apply 'append
 	 (mapcar
 	   (lambda (tree)
@@ -48,20 +47,20 @@ (defun notmuch-query-map-aux  (mapper function seq)
 	   seq)))
 
 (defun notmuch-query-map-threads (fn threads)
-  "apply FN to every thread in  THREADS. Flatten results to a list.
+  "Apply FN to every thread in THREADS. Flatten results to a list.
 
 See the function notmuch-query-get-threads for more information."
   (notmuch-query-map-aux 'notmuch-query-map-forest fn threads))
 
 (defun notmuch-query-map-forest (fn forest)
-  "apply function to every message in a forest. Flatten results to a list.
+  "Apply function to every message in a forest. Flatten results to a list.
 
 See the function notmuch-query-get-threads for more information.
 "
   (notmuch-query-map-aux 'notmuch-query-map-tree fn forest))
 
 (defun notmuch-query-map-tree (fn tree)
-  "Apply function FN to every message in TREE. Flatten results to a list
+  "Apply function FN to every message in TREE. Flatten results to a list.
 
 See the function notmuch-query-get-threads for more information."
   (cons (funcall fn (car tree)) (notmuch-query-map-forest fn (cadr tree))))
@@ -70,7 +69,7 @@ (defun notmuch-query-map-tree (fn tree)
 ;; Predefined queries
 
 (defun notmuch-query-get-message-ids (&rest search-terms)
-  "Return a list of message-ids of messages that match SEARCH-TERMS"
+  "Return a list of message-ids of messages that match SEARCH-TERMS."
   (notmuch-query-map-threads
    (lambda (msg) (plist-get msg :id))
    (notmuch-query-get-threads search-terms)))
diff --git a/emacs/notmuch-show.el b/emacs/notmuch-show.el
index 59931453..c9170466 100644
--- a/emacs/notmuch-show.el
+++ b/emacs/notmuch-show.el
@@ -179,7 +179,7 @@ (defvar notmuch-show-indent-content t)
 (make-variable-buffer-local 'notmuch-show-indent-content)
 
 (defvar notmuch-show-attachment-debug nil
-  "If t log stdout and stderr from attachment handlers
+  "If t log stdout and stderr from attachment handlers.
 
 When set to nil (the default) stdout and stderr from attachment
 handlers is discarded. When set to t the stdout and stderr from
@@ -266,7 +266,7 @@ (defcustom notmuch-show-imenu-indent nil
   :group 'notmuch-show)
 
 (defmacro with-current-notmuch-show-message (&rest body)
-  "Evaluate body with current buffer set to the text of current message"
+  "Evaluate body with current buffer set to the text of current message."
   `(save-excursion
      (let ((id (notmuch-show-get-message-id)))
        (let ((buf (generate-new-buffer (concat "*notmuch-msg-" id "*"))))
@@ -887,7 +887,7 @@ (defun notmuch-show-insert-bodypart-internal (msg part content-type nth depth bu
 		    nil))))
 
 (defun notmuch-show-create-part-overlays (button beg end)
-  "Add an overlay to the part between BEG and END"
+  "Add an overlay to the part between BEG and END."
 
   ;; If there is no button (i.e., the part is text/plain and the first
   ;; part) or if the part has no content then we don't make the part
@@ -898,7 +898,7 @@ (defun notmuch-show-create-part-overlays (button beg end)
     t))
 
 (defun notmuch-show-record-part-information (part beg end)
-  "Store PART as a text property from BEG to END"
+  "Store PART as a text property from BEG to END."
 
   ;; Record part information.  Since we already inserted subparts,
   ;; don't override existing :notmuch-part properties.
@@ -1381,7 +1381,7 @@ (defun notmuch-show-capture-state ()
     (list win-id-combo (notmuch-show-get-message-ids-for-open-messages))))
 
 (defun notmuch-show-get-query ()
-  "Return the current query in this show buffer"
+  "Return the current query in this show buffer."
   (if notmuch-show-query-context
       (concat notmuch-show-thread-id
 	      " and ("
@@ -1459,7 +1459,7 @@ (defvar notmuch-show-stash-map
     (define-key map "G" 'notmuch-show-stash-git-send-email)
     (define-key map "?" 'notmuch-subkeymap-help)
     map)
-  "Submap for stash commands")
+  "Submap for stash commands.")
 (fset 'notmuch-show-stash-map notmuch-show-stash-map)
 
 (defvar notmuch-show-part-map
@@ -1471,7 +1471,7 @@ (defvar notmuch-show-part-map
     (define-key map "m" 'notmuch-show-choose-mime-of-part)
     (define-key map "?" 'notmuch-subkeymap-help)
     map)
-  "Submap for part commands")
+  "Submap for part commands.")
 (fset 'notmuch-show-part-map notmuch-show-part-map)
 
 (defvar notmuch-show-mode-map
@@ -1561,14 +1561,14 @@ (define-derived-mode notmuch-show-mode fundamental-mode "notmuch-show"
         #'notmuch-show-imenu-extract-index-name-function))
 
 (defun notmuch-tree-from-show-current-query ()
-  "Call notmuch tree with the current query"
+  "Call notmuch tree with the current query."
   (interactive)
   (notmuch-tree notmuch-show-thread-id
 		notmuch-show-query-context
 		(notmuch-show-get-message-id)))
 
 (defun notmuch-unthreaded-from-show-current-query ()
-  "Call notmuch unthreaded with the current query"
+  "Call notmuch unthreaded with the current query."
   (interactive)
   (notmuch-unthreaded notmuch-show-thread-id
 		      notmuch-show-query-context
@@ -2011,7 +2011,7 @@ (defun notmuch-show-open-if-matched ()
     (notmuch-show-message-visible props (plist-get props :match))))
 
 (defun notmuch-show-goto-first-wanted-message ()
-  "Move to the first open message and mark it read"
+  "Move to the first open message and mark it read."
   (goto-char (point-min))
   (unless (notmuch-show-message-visible-p)
     (notmuch-show-next-open-message))
@@ -2511,7 +2511,7 @@ (defun notmuch-show--mm-display-part (handle)
       (view-buffer buf 'kill-buffer-if-not-modified))))
 
 (defun notmuch-show-choose-mime-of-part (mime-type)
-  "Choose the mime type to use for displaying part"
+  "Choose the mime type to use for displaying part."
   (interactive
    (list (completing-read "Mime type to use (default text/plain): "
 			  (mailcap-mime-types) nil nil nil nil "text/plain")))
diff --git a/emacs/notmuch-tag.el b/emacs/notmuch-tag.el
index bc83e3de..c54e6ad0 100644
--- a/emacs/notmuch-tag.el
+++ b/emacs/notmuch-tag.el
@@ -84,7 +84,7 @@ (defcustom notmuch-tagging-keys
   :group 'notmuch-tag)
 
 (define-widget 'notmuch-tag-format-type 'lazy
-  "Customize widget for notmuch-tag-format and friends"
+  "Customize widget for notmuch-tag-format and friends."
   :type '(alist :key-type (regexp :tag "Tag")
 		:extra-offset -3
 		:value-type
@@ -313,7 +313,7 @@ (defun notmuch-tag-format-tag (tags orig-tags tag)
 are in TAGS but are not in ORIG-TAGS) are shown using formats
 from `notmuch-tag-added-formats' and tags which have not been
 changed (the normal case) are shown using formats from
-`notmuch-tag-formats'"
+`notmuch-tag-formats'."
   (let* ((tag-state (cond ((not (member tag tags)) 'deleted)
 			  ((not (member tag orig-tags)) 'added)))
 	 (formatted-tag (gethash (cons tag tag-state) notmuch-tag--format-cache 'missing)))
@@ -351,7 +351,7 @@ (defcustom notmuch-before-tag-hook nil
 'tag-changes' will contain the tags that are about to be added or removed as
 a list of strings of the form \"+TAG\" or \"-TAG\".
 'query' will be a string containing the search query that determines
-the messages that are about to be tagged"
+the messages that are about to be tagged."
 
   :type 'hook
   :options '(notmuch-hl-line-mode)
@@ -363,7 +363,7 @@ (defcustom notmuch-after-tag-hook nil
 'tag-changes' will contain the tags that were added or removed as
 a list of strings of the form \"+TAG\" or \"-TAG\".
 'query' will be a string containing the search query that determines
-the messages that were tagged"
+the messages that were tagged."
   :type 'hook
   :options '(notmuch-hl-line-mode)
   :group 'notmuch-hooks)
diff --git a/emacs/notmuch-tree.el b/emacs/notmuch-tree.el
index 254664c4..ab90f652 100644
--- a/emacs/notmuch-tree.el
+++ b/emacs/notmuch-tree.el
@@ -45,7 +45,7 @@ (defvar notmuch-search-query-string)
 
 ;; this variable distinguishes the unthreaded display from the normal tree display
 (defvar notmuch-tree-unthreaded nil
-  "A buffer local copy of argument unthreaded to the function notmuch-tree")
+  "A buffer local copy of argument unthreaded to the function notmuch-tree.")
 (make-variable-buffer-local 'notmuch-tree-unthreaded)
 
 (defgroup notmuch-tree nil
@@ -72,18 +72,18 @@ (defcustom notmuch-tree-result-format
     ("authors" . "%-20s")
     ((("tree" . "%s")("subject" . "%s")) ." %-54s ")
     ("tags" . "(%s)"))
-  "Result formatting for Tree view. Supported fields are: date,
-        authors, subject, tree, tags.  Tree means the thread tree
-        box graphics. The field may also be a list in which case
-        the formatting rules are applied recursively and then the
-        output of all the fields in the list is inserted
-        according to format-string.
+  "Result formatting for tree view. Supported fields are: date,
+authors, subject, tree, tags.  Tree means the thread tree
+box graphics. The field may also be a list in which case
+the formatting rules are applied recursively and then the
+output of all the fields in the list is inserted
+according to format-string.
 
 Note the author string should not contain
-        whitespace (put it in the neighbouring fields instead).
-        For example:
+whitespace (put it in the neighbouring fields instead).
+For example:
         (setq notmuch-tree-result-format \(\(\"authors\" . \"%-40s\"\)
-                                             \(\"subject\" . \"%s\"\)\)\)"
+                                          \(\"subject\" . \"%s\"\)\)\)"
   :type '(alist :key-type (string) :value-type (string))
   :group 'notmuch-tree)
 
@@ -92,18 +92,18 @@ (defcustom notmuch-unthreaded-result-format
     ("authors" . "%-20s")
     ((("subject" . "%s")) ." %-54s ")
     ("tags" . "(%s)"))
-  "Result formatting for unthreaded Tree view. Supported fields are: date,
-        authors, subject, tree, tags.  Tree means the thread tree
-        box graphics. The field may also be a list in which case
-        the formatting rules are applied recursively and then the
-        output of all the fields in the list is inserted
-        according to format-string.
+  "Result formatting for unthreaded tree view. Supported fields are: date,
+authors, subject, tree, tags.  Tree means the thread tree
+box graphics. The field may also be a list in which case
+the formatting rules are applied recursively and then the
+output of all the fields in the list is inserted
+according to format-string.
 
 Note the author string should not contain
-        whitespace (put it in the neighbouring fields instead).
-        For example:
+whitespace (put it in the neighbouring fields instead).
+For example:
         (setq notmuch-tree-result-format \(\(\"authors\" . \"%-40s\"\)
-                                             \(\"subject\" . \"%s\"\)\)\)"
+                                          \(\"subject\" . \"%s\"\)\)\)"
   :type '(alist :key-type (string) :value-type (string))
   :group 'notmuch-tree)
 
@@ -166,7 +166,7 @@ (defface notmuch-tree-match-tag-face
 ;; Faces for messages that do not match the query.
 (defface notmuch-tree-no-match-face
   '((t (:foreground "gray")))
-  "Default face used in tree mode face for non-matching messages"
+  "Default face used in tree mode face for non-matching messages."
   :group 'notmuch-tree
   :group 'notmuch-faces)
 
@@ -201,23 +201,23 @@ (defface notmuch-tree-no-match-tag-face
   :group 'notmuch-faces)
 
 (defvar notmuch-tree-previous-subject
-  "The subject of the most recent result shown during the async display")
+  "The subject of the most recent result shown during the async display.")
 (make-variable-buffer-local 'notmuch-tree-previous-subject)
 
 (defvar notmuch-tree-basic-query nil
-  "A buffer local copy of argument query to the function notmuch-tree")
+  "A buffer local copy of argument query to the function notmuch-tree.")
 (make-variable-buffer-local 'notmuch-tree-basic-query)
 
 (defvar notmuch-tree-query-context nil
-  "A buffer local copy of argument query-context to the function notmuch-tree")
+  "A buffer local copy of argument query-context to the function notmuch-tree.")
 (make-variable-buffer-local 'notmuch-tree-query-context)
 
 (defvar notmuch-tree-target-msg nil
-  "A buffer local copy of argument target to the function notmuch-tree")
+  "A buffer local copy of argument target to the function notmuch-tree.")
 (make-variable-buffer-local 'notmuch-tree-target-msg)
 
 (defvar notmuch-tree-open-target nil
-  "A buffer local copy of argument open-target to the function notmuch-tree")
+  "A buffer local copy of argument open-target to the function notmuch-tree.")
 (make-variable-buffer-local 'notmuch-tree-open-target)
 
 (defvar notmuch-tree-message-window nil
@@ -251,14 +251,14 @@ (defun notmuch-tree-to-message-pane (func)
 	 (call-interactively #',func)))))
 
 (defun notmuch-tree-inherit-from-message-pane (sym)
-  "Return value of SYM in message-pane if open, or tree-pane if not"
+  "Return value of SYM in message-pane if open, or tree-pane if not."
   (if (window-live-p notmuch-tree-message-window)
       (with-selected-window notmuch-tree-message-window
 	(symbol-value sym))
     (symbol-value sym)))
 
 (defun notmuch-tree-button-activate (&optional button)
-  "Activate BUTTON or button at point
+  "Activate BUTTON or button at point.
 
 This function does not give an error if there is no button."
   (interactive)
@@ -346,7 +346,7 @@ (defun notmuch-tree-get-message-properties ()
 
 Some useful entries are:
 :headers - Property list containing the headers :Date, :Subject, :From, etc.
-:tags - Tags for this message"
+:tags - Tags for this message."
   (save-excursion
     (beginning-of-line)
     (get-text-property (point) :notmuch-message-properties)))
@@ -432,7 +432,7 @@ (defun notmuch-tree-tag-update-display (&optional tag-changes)
 	    (notmuch-show-update-tags new-tags)))))))
 
 (defun notmuch-tree-tag (tag-changes)
-  "Change tags for the current message"
+  "Change tags for the current message."
   (interactive
    (list (notmuch-read-tag-changes (notmuch-tree-get-tags) "Tag message")))
   (notmuch-tag (notmuch-tree-get-message-id) tag-changes)
@@ -472,26 +472,26 @@ (defun notmuch-tree-to-search ()
     (notmuch-search query)))
 
 (defun notmuch-tree-to-tree ()
-  "Run a query and display results in Tree view"
+  "Run a query and display results in tree view."
   (interactive)
   (let ((query (notmuch-read-query "Notmuch tree view search: ")))
     (notmuch-tree-close-message-window)
     (notmuch-tree query)))
 
 (defun notmuch-unthreaded-from-tree-current-query ()
-  "Switch from tree view to unthreaded view"
+  "Switch from tree view to unthreaded view."
   (interactive)
   (unless notmuch-tree-unthreaded
     (notmuch-tree-refresh-view 'unthreaded)))
 
 (defun notmuch-tree-from-unthreaded-current-query ()
-  "Switch from unthreaded view to tree view"
+  "Switch from unthreaded view to tree view."
   (interactive)
   (when notmuch-tree-unthreaded
     (notmuch-tree-refresh-view 'tree)))
 
 (defun notmuch-search-from-tree-current-query ()
-  "Call notmuch search with the current query"
+  "Call notmuch search with the current query."
   (interactive)
   (notmuch-tree-close-message-window)
   (notmuch-search (notmuch-tree-get-query)))
@@ -563,7 +563,7 @@ (defun notmuch-tree-show-message (arg)
     (notmuch-tree-show-message-in)))
 
 (defun notmuch-tree-scroll-message-window ()
-  "Scroll the message window (if it exists)"
+  "Scroll the message window (if it exists)."
   (interactive)
   (when (window-live-p notmuch-tree-message-window)
     (with-selected-window notmuch-tree-message-window
@@ -572,7 +572,7 @@ (defun notmuch-tree-scroll-message-window ()
 	(scroll-up)))))
 
 (defun notmuch-tree-scroll-message-window-back ()
-  "Scroll the message window back(if it exists)"
+  "Scroll the message window back(if it exists)."
   (interactive)
   (when (window-live-p notmuch-tree-message-window)
     (with-selected-window notmuch-tree-message-window
@@ -661,7 +661,7 @@ (defun notmuch-tree-goto-matching-message (&optional prev)
     (not (funcall eobfn))))
 
 (defun notmuch-tree-matching-message (&optional prev pop-at-end)
-  "Move to the next or previous matching message"
+  "Move to the next or previous matching message."
   (interactive "P")
   (forward-line (if prev -1 nil))
   (if (and (not (notmuch-tree-goto-matching-message prev)) pop-at-end)
@@ -734,7 +734,7 @@ (defun notmuch-tree-get-messages-ids-thread-search ()
 	     " or "))
 
 (defun notmuch-tree-tag-thread (tag-changes)
-  "Tag all messages in the current thread"
+  "Tag all messages in the current thread."
   (interactive
    (let ((tags (apply #'append (notmuch-tree-thread-mapcar
 				(lambda () (notmuch-tree-get-tags))))))
@@ -775,7 +775,7 @@ (defun notmuch-tree-clean-address (address)
     (or p-name p-address)))
 
 (defun notmuch-tree-format-field (field format-string msg)
-  "Format a FIELD of MSG according to FORMAT-STRING and return string"
+  "Format a FIELD of MSG according to FORMAT-STRING and return string."
   (let* ((headers (plist-get msg :headers))
 	 (match (plist-get msg :match)))
     (cond
@@ -831,7 +831,7 @@ (defun notmuch-tree-format-field (field format-string msg)
 	(format format-string (notmuch-tag-format-tags tags orig-tags face)))))))
 
 (defun notmuch-tree-format-field-list (field-list msg)
-  "Format fields of MSG according to FIELD-LIST and return string"
+  "Format fields of MSG according to FIELD-LIST and return string."
   (let ((face (if (plist-get msg :match)
 		  'notmuch-tree-match-face
 		'notmuch-tree-no-match-face))
@@ -842,7 +842,7 @@ (defun notmuch-tree-format-field-list (field-list msg)
     (notmuch-apply-face result-string face t)))
 
 (defun notmuch-tree-insert-msg (msg)
-  "Insert the message MSG according to notmuch-tree-result-format"
+  "Insert the message MSG according to notmuch-tree-result-format."
   ;; We need to save the previous subject as it will get overwritten
   ;; by the insert-field calls.
   (let ((previous-subject notmuch-tree-previous-subject))
@@ -852,7 +852,7 @@ (defun notmuch-tree-insert-msg (msg)
     (insert "\n")))
 
 (defun notmuch-tree-goto-and-insert-msg (msg)
-  "Insert msg at the end of the buffer. Move point to msg if it is the target"
+  "Insert msg at the end of the buffer. Move point to msg if it is the target."
   (save-excursion
     (goto-char (point-max))
     (notmuch-tree-insert-msg msg))
@@ -946,7 +946,7 @@ (define-derived-mode notmuch-tree-mode fundamental-mode "notmuch-tree"
 	truncate-lines t))
 
 (defun notmuch-tree-process-sentinel (proc msg)
-  "Add a message to let user know when \"notmuch tree\" exits"
+  "Add a message to let user know when \"notmuch tree\" exits."
   (let ((buffer (process-buffer proc))
 	(status (process-status proc))
 	(exit-status (process-exit-status proc))
@@ -968,7 +968,7 @@ (defun notmuch-tree-process-sentinel (proc msg)
 		    (insert "\n")))))))))
 
 (defun notmuch-tree-process-filter (proc string)
-  "Process and filter the output of \"notmuch show\" for tree view"
+  "Process and filter the output of \"notmuch show\" for tree view."
   (let ((results-buf (process-buffer proc))
         (parse-buf (process-get proc 'parse-buf))
         (inhibit-read-only t)
@@ -1026,7 +1026,7 @@ (defun notmuch-tree-worker (basic-query &optional query-context target open-targ
       (set-process-query-on-exit-flag proc nil))))
 
 (defun notmuch-tree-get-query ()
-  "Return the current query in this tree buffer"
+  "Return the current query in this tree buffer."
   (if notmuch-tree-query-context
       (concat notmuch-tree-basic-query
 	      " and ("
@@ -1035,7 +1035,7 @@ (defun notmuch-tree-get-query ()
     notmuch-tree-basic-query))
 
 (defun notmuch-tree (&optional query query-context target buffer-name open-target unthreaded)
-  "Display threads matching QUERY in Tree View.
+  "Display threads matching QUERY in tree view.
 
 The arguments are:
   QUERY: the main query. This can be any query but in many cases will be
diff --git a/emacs/notmuch-wash.el b/emacs/notmuch-wash.el
index 54108d93..fd0314cc 100644
--- a/emacs/notmuch-wash.el
+++ b/emacs/notmuch-wash.el
@@ -192,7 +192,7 @@ (defun notmuch-wash-button-label (overlay)
     (format label-format lines-count)))
 
 (defun notmuch-wash-region-to-button (msg beg end type &optional prefix)
-  "Auxiliary function to do the actual making of overlays and buttons
+  "Auxiliary function to do the actual making of overlays and buttons.
 
 BEG and END are buffer locations. TYPE should a string, either
 \"citation\" or \"signature\". Optional PREFIX is some arbitrary
diff --git a/emacs/notmuch.el b/emacs/notmuch.el
index a980c7a2..40caa280 100644
--- a/emacs/notmuch.el
+++ b/emacs/notmuch.el
@@ -113,7 +113,7 @@ (defcustom notmuch-init-file (locate-user-emacs-file "notmuch-config")
   :group 'notmuch)
 
 (defvar notmuch-query-history nil
-  "Variable to store minibuffer history for notmuch queries")
+  "Variable to store minibuffer history for notmuch queries.")
 
 (defun notmuch-foreach-mime-part (function mm-handle)
   (cond ((stringp (car mm-handle))
@@ -202,7 +202,7 @@ (defvar notmuch-search-stash-map
     (define-key map "q" 'notmuch-stash-query)
     (define-key map "?" 'notmuch-subkeymap-help)
     map)
-  "Submap for stash commands")
+  "Submap for stash commands.")
 (fset 'notmuch-search-stash-map notmuch-search-stash-map)
 
 (defun notmuch-search-stash-thread-id ()
@@ -417,7 +417,7 @@ (defun notmuch-search-result-end (&optional pos)
 
 The returned point will be just after the newline character that
 ends the result line.  If there is no thread at POS (or point),
-returns nil"
+returns nil."
   (when (notmuch-search-get-result pos)
     (next-single-property-change (or pos (point)) 'notmuch-search-result
 				 nil (point-max))))
@@ -457,9 +457,9 @@ (defun notmuch-search-properties-in-region (property beg end)
     output))
 
 (defun notmuch-search-find-thread-id (&optional bare)
-  "Return the thread for the current thread
+  "Return the thread for the current thread.
 
-If BARE is set then do not prefix with \"thread:\""
+If BARE is set then do not prefix with \"thread:\"."
   (let ((thread (plist-get (notmuch-search-get-result) :thread)))
     (when thread (concat (unless bare "thread:") thread))))
 
@@ -486,19 +486,19 @@ (defun notmuch-search-find-stable-query-region (beg end &optional only-matched)
       (concat "(" (mapconcat 'identity query-list ") or (") ")"))))
 
 (defun notmuch-search-find-authors ()
-  "Return the authors for the current thread"
+  "Return the authors for the current thread."
   (plist-get (notmuch-search-get-result) :authors))
 
 (defun notmuch-search-find-authors-region (beg end)
-  "Return a list of authors for the current region"
+  "Return a list of authors for the current region."
   (notmuch-search-properties-in-region :authors beg end))
 
 (defun notmuch-search-find-subject ()
-  "Return the subject for the current thread"
+  "Return the subject for the current thread."
   (plist-get (notmuch-search-get-result) :subject))
 
 (defun notmuch-search-find-subject-region (beg end)
-  "Return a list of authors for the current region"
+  "Return a list of authors for the current region."
   (notmuch-search-properties-in-region :subject beg end))
 
 (defun notmuch-search-show-thread (&optional elide-toggle)
@@ -520,22 +520,22 @@ (defun notmuch-search-show-thread (&optional elide-toggle)
       (message "End of search results."))))
 
 (defun notmuch-tree-from-search-current-query ()
-  "Call notmuch tree with the current query"
+  "Call notmuch tree with the current query."
   (interactive)
   (notmuch-tree notmuch-search-query-string))
 
 (defun notmuch-unthreaded-from-search-current-query ()
-  "Call notmuch tree with the current query"
+  "Call notmuch tree with the current query."
   (interactive)
   (notmuch-unthreaded notmuch-search-query-string))
 
 (defun notmuch-tree-from-search-thread ()
-  "Show the selected thread with notmuch-tree"
+  "Show the selected thread with notmuch-tree."
   (interactive)
   (notmuch-tree (notmuch-search-find-thread-id)
-                notmuch-search-query-string
+		notmuch-search-query-string
 		nil
-                (notmuch-prettify-subject (notmuch-search-find-subject))
+		(notmuch-prettify-subject (notmuch-search-find-subject))
 		t))
 
 (defun notmuch-search-reply-to-thread (&optional prompt-for-sender)
@@ -660,7 +660,7 @@ (defun notmuch-search-update-result (result &optional pos)
 	(goto-char new-point)))))
 
 (defun notmuch-search-process-sentinel (proc msg)
-  "Add a message to let user know when \"notmuch search\" exits"
+  "Add a message to let user know when \"notmuch search\" exits."
   (let ((buffer (process-buffer proc))
 	(status (process-status proc))
 	(exit-status (process-exit-status proc))
@@ -862,7 +862,7 @@ (defun notmuch-search-append-result (result)
       (goto-char pos))))
 
 (defun notmuch-search-process-filter (proc string)
-  "Process and filter the output of \"notmuch search\""
+  "Process and filter the output of \"notmuch search\"."
   (let ((results-buf (process-buffer proc))
 	(parse-buf (process-get proc 'parse-buf))
 	(inhibit-read-only t)
@@ -952,7 +952,7 @@ (defun notmuch-read-query (prompt)
 			      'notmuch-search-history current-query nil)))))
 
 (defun notmuch-search-get-query ()
-  "Return the current query in this search buffer"
+  "Return the current query in this search buffer."
   notmuch-search-query-string)
 
 (put 'notmuch-search 'notmuch-doc "Search for messages.")
-- 
2.25.1


^ permalink raw reply related	[flat|nested] 5+ messages in thread

* Re: [PATCH] emacs docstrings: consistent indentation, newlines, periods
  2020-05-24 19:17 [PATCH] emacs docstrings: consistent indentation, newlines, periods Tomi Ollila
@ 2020-06-06 11:50 ` David Bremner
  0 siblings, 0 replies; 5+ messages in thread
From: David Bremner @ 2020-06-06 11:50 UTC (permalink / raw)
  To: Tomi Ollila, notmuch; +Cc: tomi.ollila

Tomi Ollila <tomi.ollila@iki.fi> writes:

> Fixed emacs docstrings to be consistent. No functional change.
>
> - removed some (accidental) indentation
> - removed some trailing newlines
> - added trailing periods where missing (some exclusions)

I'm hoping this doesn't cause any surprising problems, included in the
latest release candidate.

^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2020-06-06 11:51 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-05-24 19:17 [PATCH] emacs docstrings: consistent indentation, newlines, periods Tomi Ollila
2020-06-06 11:50 ` David Bremner
  -- strict thread matches above, loose matches on Subject: below --
2020-05-03 21:21 Tomi Ollila
2020-05-21 21:47 ` Daniel Kahn Gillmor
2020-05-21 22:08   ` Tomi Ollila

Code repositories for project(s) associated with this public inbox

	https://yhetil.org/notmuch.git/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).