From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id aPa+BX/Iyl40RAAA0tVLHw (envelope-from ) for ; Sun, 24 May 2020 19:18:23 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1 with LMTPS id aE2KAX/Iyl6JXQAAbx9fmQ (envelope-from ) for ; Sun, 24 May 2020 19:18:23 +0000 Received: from arlo.cworth.org (arlo.cworth.org [50.126.95.6]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 329C69404C8 for ; Sun, 24 May 2020 19:18:21 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 69D686DE102E; Sun, 24 May 2020 12:18:16 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org Received: from arlo.cworth.org ([127.0.0.1]) by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id yTXQEvxGs2ZI; Sun, 24 May 2020 12:18:13 -0700 (PDT) Received: from arlo.cworth.org (localhost [IPv6:::1]) by arlo.cworth.org (Postfix) with ESMTP id 92AB06DE0B36; Sun, 24 May 2020 12:18:12 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 4856C6DE0B36 for ; Sun, 24 May 2020 12:18:11 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org Received: from arlo.cworth.org ([127.0.0.1]) by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id J54LvMHvPHWU for ; Sun, 24 May 2020 12:18:09 -0700 (PDT) Received: from lahtoruutu.iki.fi (lahtoruutu.iki.fi [185.185.170.37]) by arlo.cworth.org (Postfix) with ESMTPS id 746676DE0A89 for ; Sun, 24 May 2020 12:18:07 -0700 (PDT) Received: from guru.guru-group.fi (guru.guru-group.fi [46.183.73.34]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) (Authenticated sender: too) by lahtoruutu.iki.fi (Postfix) with ESMTPSA id 762B81B0008C; Sun, 24 May 2020 22:18:03 +0300 (EEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=iki.fi; s=lahtoruutu; t=1590347883; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc; bh=b4qTE0PbPnxp1Ao/SEFXKcSSNNUIVJ7laub4PczF/es=; b=iuzo9aY1p9NVGm4eKMr2eTZyrgfc5YlvivaLmvz3qMUnSKXewFAXpF3luSNJXgz2kMoHdy /jnQ8bDne2L5zlZwJOoUGzOlVxPxg2kuiETr8xRj1fOBQVPIxkdv5oO7H2rxZNxtXnv8cN Mbm2R2uxEN+lrcU2shHvuCCwx1fjPWfhLa3rVGJx2ZQN+7fM6SZSutyRq6rCfF0IaxgfhN lUaEzpkw8g28USwpNLBJAur8btG+T3YMSmH9f0m9cw31W2g/dBfgy7LUj8n0QvF4gDoizh GOhLU4sXQ0rB4FX3wQk5CZW1mVljC5hEzZyt2BA6lk1rZygJ6KG7i48J9jz6JQ== From: Tomi Ollila To: notmuch@notmuchmail.org Subject: [PATCH] emacs docstrings: consistent indentation, newlines, periods Date: Sun, 24 May 2020 22:17:56 +0300 Message-Id: <20200524191756.17280-1-tomi.ollila@iki.fi> X-Mailer: git-send-email 2.13.3 ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=iki.fi; s=lahtoruutu; t=1590347883; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc; bh=b4qTE0PbPnxp1Ao/SEFXKcSSNNUIVJ7laub4PczF/es=; b=OPsXyAyUQH1foiT0L7urywzTT4kZ/UKfH+y/Gre50Sv2qLRM+yV3z3WGnxC1MnRPap2N2Q Ib0i5+q/bXRFSPYW+Vwwj4NFy3K5bsq1SORM3L2wPBMZUscbIQVqhIsbC/PcEpjhbJEm5O d5NcG6HkOjS/2wsLJU0Oobv64WQ/BfW/nZSzjiMVyHJ6cm/ikh5UdHBIguIp3JMPYltJx3 KLgzyV2zGLJ9e4MBWdJal3lFjnqcEUeaWifUCu7mLdsb6KxVYXVzDSYFCB3tJ5Eo41zdZi h/R5j2NaRANRo6mRcoqSqmC43QkKyVzlZr4fMz8WJ3c3/OAOfjBpjPpCohsCoQ== ARC-Seal: i=1; s=lahtoruutu; d=iki.fi; t=1590347883; a=rsa-sha256; cv=none; b=jRwq56GPs6gJbIkf+cM6Y7jsnkCPu+Gh6SATW6SB4SVKGLMcS1zw58XGYxfJRH3hde01UP qpkH4ijT5EA6AFu3A8I26DxWIMz9n8kLnKlXp5PBbe8xWNX1B46j/79suNdmnKxTZ5Zyqw i6RLjTdlaK3C3vfsEQhgMgi9xGE9WPO/F712XlZ0IwKR3TT2fMrbxcfIici1rQAoimw7vn 0RXRv+3Z77/RkKowt4JodYpmdhQX1APP9TL4RhiJn9ZNLRfIxL/21wpimbWXU2yqfUvUD7 i/qnmtfDl/1oypY3TAzkZXvvqsfd7IERQZZ22f0qtrFxL/fBgT7KGU62zJDEZA== ARC-Authentication-Results: i=1; ORIGINATING; auth=pass smtp.auth=too smtp.mailfrom=tomi.ollila@iki.fi X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: tomi.ollila@iki.fi MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: notmuch-bounces@notmuchmail.org Sender: "notmuch" X-Scanner: scn0 Authentication-Results: aspmx1.migadu.com; dkim=fail (body hash did not verify) header.d=iki.fi header.s=lahtoruutu header.b=iuzo9aY1; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 50.126.95.6 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Spam-Score: 2.99 X-TUID: Hhzb0mOpY5vR 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