From 806033f1640e1643e9d4eb532ca426f7068d7a81 Mon Sep 17 00:00:00 2001 From: "Dirk-Jan C. Binnema" Date: Fri, 16 Aug 2024 21:11:44 +0200 Subject: [PATCH] mu4e-query-items: improve documentation Possibly useful for #2741. --- mu4e/mu4e-query-items.el | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/mu4e/mu4e-query-items.el b/mu4e/mu4e-query-items.el index b2523e799..d7b6ef21e 100644 --- a/mu4e/mu4e-query-items.el +++ b/mu4e/mu4e-query-items.el @@ -1,6 +1,6 @@ ;;; mu4e-query-items.el --- Manage query results -*- lexical-binding: t -*- -;; Copyright (C) 2023 Dirk-Jan C. Binnema +;; Copyright (C) 2023-2024 Dirk-Jan C. Binnema ;; Author: Dirk-Jan C. Binnema ;; Maintainer: Dirk-Jan C. Binnema @@ -94,8 +94,8 @@ If ITEMS does not yet have a favorite item, pick the first." (defvar mu4e--bookmark-items-cached nil "Cached bookmarks query items.") (defvar mu4e--maildir-items-cached nil "Cached maildirs query items.") -(declare-function mu4e-bookmarks "mu4e-bookmarks") -(declare-function mu4e-maildir-shortcuts "mu4e-folders") +(declare-function mu4e-bookmarks "mu4e-bookmarks") +(declare-function mu4e-maildir-shortcuts "mu4e-folders") (defun mu4e--query-item-display-counts (item) "Get the count display string for some query-data ITEM." @@ -222,18 +222,32 @@ bookmark or maildir." data)) (defun mu4e-query-items (&optional type) - "Grab query items of TYPE. + "Grab cached information about query items of some TYPE. -TYPE is symbol; either bookmarks or maildirs, or nil for both. +TYPE is a symbol; either `bookmarks' or `maildirs', or nil for +both, and returns a list of plists. The information is based on +the last (cached) information known by mu4e. This combines: - - the latest queries data (i.e., `(mu4e-server-query-items)') - - baseline queries data (i.e. `mu4e-baseline') - with the combined queries for `(mu4e-bookmarks)' and - `(mu4e-maildir-shortcuts)' in bookmarks-compatible plists. - -This packages the aggregated information in a format that is convenient -for use in various places." +- the latest queries data (i.e., `(mu4e-server-query-items)') +- baseline queries data (i.e. `mu4e-baseline') with the combined + queries for `mu4e-bookmarks' and `mu4e-maildir-shortcuts' in + bookmarks-compatible plists. + +Currently, the plist contains the following fields: +- `:name' - the name of the bookmark or query +- `:query' - the associated (unprocessed) query +- `:count' - number of matches for the query +- `:unread' - number of unread messages for the query +- `:delta-count' - change in count since baseline +- `:delta-unread' - change in unread count since baseline +- `:favorite' - non-nil if this is the favorite query + +There are some other fields for internal mu4e use, better not use +those externally. + +For the various nuances with the unread count and baseline, +please refer to info node `(mu4e) Bookmarks and Maildirs'." (cond ((equal type 'bookmarks) (or mu4e--bookmark-items-cached