From 4b84c81200bcc923e15a50bd423c16ed2be20612 Mon Sep 17 00:00:00 2001 From: Richard Russon Date: Wed, 2 Dec 2015 03:58:15 +0000 Subject: [PATCH] tidy: add comments NOTE: this patch does NOT make any code changes. It simply adds comment blocks. Fully document all the sidebar config options. Add comment-blocks describing each function -- what it does, the parameters it takes, the return values. These can be used by doxygen. --- buffy.c | 43 +++++++++++++++++- init.h | 104 +++++++++++++++++++++++++++++++------------- mh.c | 11 +++++ sidebar.c | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 4 files changed, 253 insertions(+), 33 deletions(-) diff --git a/buffy.c b/buffy.c index 8db541a5c..d5641f639 100644 --- a/buffy.c +++ b/buffy.c @@ -162,6 +162,18 @@ void mutt_buffy_cleanup (const char *buf, struct stat *st) } } +/** + * buffy_compare_name - qsort callback to sort BUFFYs + * @a: First BUFFY to compare + * @b: Second BUFFY to compare + * + * Compare the paths of two BUFFYs taking the locale into account. + * + * Returns: + * -1: a precedes b + * 0: a and b are identical + * 1: b precedes a + */ static int buffy_compare_name (const void *a, const void *b) { @@ -171,6 +183,19 @@ buffy_compare_name (const void *a, const void *b) return mutt_strcoll (b1->path, b2->path); } +/** + * buffy_sort - Sort a linked list of BUFFYs + * @b: BUFFY at the head of the list to be sorted + * + * Take a linked list of BUFFYs and sort them by their paths according to the + * locale. Once sorted, the prev/next links are restored. + * + * If the config option "sidebar_sort" isn't set, then the BUFFY is returned + * unchanged. + * + * Returns: + * BUFFY at the head of the sorted list + */ static BUFFY * buffy_sort (BUFFY *b) { @@ -416,7 +441,13 @@ static int buffy_maildir_hasnew (BUFFY* mailbox) return 0; } -/* update message counts for the sidebar */ +/** + * buffy_maildir_update - Update messages counts for a maildir mailbox + * @mailbox: BUFFY representing a maildir mailbox + * + * Open a mailbox directories and update our record of how many new, or + * flagged, messages there are. + */ void buffy_maildir_update (BUFFY *mailbox) { @@ -512,7 +543,15 @@ static int buffy_mbox_hasnew (BUFFY* mailbox, struct stat *sb) return rc; } -/* update message counts for the sidebar */ +/** + * buffy_mbox_update - Update messages counts for an mbox mailbox + * @mailbox: BUFFY representing an mbox mailbox + * @sb: stat(2) infomation about the mailbox file + * + * Open a mbox file and update our record of how many new, or flagged, + * messages there are. If the mailbox hasn't changed since the last call, + * the function does nothing. + */ void buffy_mbox_update (BUFFY *mailbox, struct stat *sb) { diff --git a/init.h b/init.h index cfc67add9..edea86c06 100644 --- a/init.h +++ b/init.h @@ -2665,80 +2665,124 @@ struct option_t MuttVars[] = { ** Command to use when spawning a subshell. By default, the user's login ** shell from \fC/etc/passwd\fP is used. */ - - {"sidebar_delim", DT_STR, R_BOTH, UL &SidebarDelim, UL "|"}, + { "sidebar_delim", DT_STR, R_BOTH, UL &SidebarDelim, UL "|" }, /* ** .pp - ** This specifies the delimiter between the sidebar (if visible) and - ** other screens. + ** This specifies the character to be drawn between the sidebar (when + ** visible) and the other Mutt panels. ASCII and Unicode line-drawing + ** characters are supported. + ** .pp + ** \fBNote:\fP Only the first character of sidebar_delim is used. */ - { "sidebar_delim_chars", DT_STR, R_NONE, UL &SidebarDelimChars, UL "/." }, + { "sidebar_delim_chars", DT_STR, R_NONE, UL &SidebarDelimChars, UL "/." }, /* ** .pp ** This contains the list of characters which you would like to treat - ** as folder separators for displaying paths in the sidebar. If - ** you're not using IMAP folders, you probably prefer setting this to "/" - ** alone. + ** as folder separators for displaying paths in the sidebar. + ** .pp + ** Local mail is often arranged in directories: `dir1/dir2/mailbox'. + ** .ts + ** set sidebar_delim_chars='/' + ** .te + ** IMAP mailboxes are often named: `folder1.folder2.mailbox'. + ** .ts + ** set sidebar_delim_chars='.' + ** .te + ** .pp + ** \fBSee also:\fP $$sidebar_shortpath, $$sidebar_folderindent, $$sidebar_indentstr. */ { "sidebar_folderindent", DT_BOOL, R_BOTH, OPTSIDEBARFOLDERINDENT, 0 }, /* ** .pp - ** Should folders be indented in the sidebar. + ** Set this to indent mailboxes in the sidebar. + ** .pp + ** \fBSee also:\fP $$sidebar_shortpath, $$sidebar_indentstr, $$sidebar_delim_chars. */ - {"sidebar_format", DT_STR, R_NONE, UL &SidebarFormat, UL "%B%?F? [%F]?%* %?N?%N/?%S"}, + { "sidebar_format", DT_STR, R_NONE, UL &SidebarFormat, UL "%B%?F? [%F]?%* %?N?%N/?%S" }, /* ** .pp - ** Format string for the sidebar. The sequences `%N', `%F' and `%S' - ** will be replaced by the number of new or flagged messages or the total - ** size of them mailbox. `%B' will be replaced with the name of the mailbox. - ** The `%!' sequence will be expanded to `!' if there is one flagged message; - ** to `!!' if there are two flagged messages; and to `n!' for n flagged - ** messages, n>2. + ** This variable allows you to customize the sidebar display. This string is + ** similar to $$index_format, but has its own set of \fCprintf(3)\fP-like + ** sequences: + ** .dl + ** .dt %B .dd Name of the mailbox + ** .dt %S .dd Size of mailbox (total number of messages) + ** .dt %N .dd Number of New messages in the mailbox + ** .dt %F .dd Number of Flagged messages in the mailbox + ** .dt %! .dd `!' : one flagged message; `!!' : two flagged messages; `n!' : + ** n flagged messages (for n > 2). + ** .de */ - {"sidebar_indentstr", DT_STR, R_BOTH, UL &SidebarIndentStr, UL " "}, + { "sidebar_indentstr", DT_STR, R_BOTH, UL &SidebarIndentStr, UL " " }, /* ** .pp - ** This specifies the string that is used to indent items - ** with sidebar_folderindent= yes + ** This specifies the string that is used to indent mailboxes in the sidebar. + ** It defaults to two spaces. + ** .pp + ** \fBSee also:\fP $$sidebar_shortpath, $$sidebar_folderindent, $$sidebar_delim_chars. */ - {"sidebar_newmail_only", DT_BOOL, R_BOTH, OPTSIDEBARNEWMAILONLY, 0 }, + { "sidebar_newmail_only", DT_BOOL, R_BOTH, OPTSIDEBARNEWMAILONLY, 0 }, /* ** .pp - ** Show only new and flagged mail in the sidebar. + ** When set, the sidebar will only display mailboxes containing new, or + ** flagged, mail. + ** .pp + ** \fBSee also:\fP $sidebar_whitelist. */ { "sidebar_next_new_wrap", DT_BOOL, R_BOTH, UL OPTSIDEBARNEXTNEWWRAP, 0 }, /* ** .pp - ** Setting sidebar_next_new_wrap=yes causes mutt to wrap around the list - ** of mailboxes when using Next/Previous New Mailbox commands. + ** When set, the \fC\fP command will not stop and the end of + ** the list of mailboxes, but wrap around to the beginning. The + ** \fC\fP command is similarly affected, wrapping around to + ** the end of the list. */ { "sidebar_refresh", DT_NUM, R_BOTH, UL &SidebarRefresh, 60 }, /* ** .pp - ** Do not refresh sidebar in less than $sidebar_refresh seconds, - ** (0 disables refreshing). + ** Set sidebar_refresh to the minimum number of seconds between refreshes. + ** This will reduced network traffic. + ** .pp + ** \fBNote:\fP Set to 0 to disable refreshing. */ { "sidebar_shortpath", DT_BOOL, R_BOTH, OPTSIDEBARSHORTPATH, 0 }, /* ** .pp - ** Should the sidebar shorten the path showed. + ** By default the sidebar will show the mailbox's path, relative to the + ** $$folder variable. Setting \fCsidebar_shortpath=yes\fP will shorten the + ** names relative to the previous name. Here's an example: + ** .dl + ** .dt \fBshortpath=no\fP .dd \fBshortpath=yes\fP .dd \fBshortpath=yes, folderindent=yes, indentstr=".."\fP + ** .dt \fCfruit\fP .dd \fCfruit\fP .dd \fCfruit\fP + ** .dt \fCfruit.apple\fP .dd \fCapple\fP .dd \fC..apple\fP + ** .dt \fCfruit.banana\fP .dd \fCbanana\fP .dd \fC..banana\fP + ** .dt \fCfruit.cherry\fP .dd \fCcherry\fP .dd \fC..cherry\fP + ** .de + ** .pp + ** \fBSee also:\fP $$sidebar_delim_chars, $$sidebar_folderindent, $$sidebar_indentstr. */ { "sidebar_sort", DT_BOOL, R_BOTH, OPTSIDEBARSORT, 0 }, /* ** .pp - ** This specifies whether or not to sort the sidebar alphabetically. + ** This specifies whether or not to sort the sidebar mailboxes alphabetically. + ** .pp + ** \fBNote:\fP This config option must come before the mailboxes config. */ { "sidebar_visible", DT_BOOL, R_BOTH, OPTSIDEBAR, 0 }, /* ** .pp - ** This specifies whether or not to show sidebar (left-side list of folders). + ** This specifies whether or not to show sidebar. The sidebar shows a list of + ** all your mailboxes. + ** .pp + ** \fBSee also:\fP $$sidebar_format, $$sidebar_width */ { "sidebar_width", DT_NUM, R_BOTH, UL &SidebarWidth, 0 }, /* ** .pp - ** The width of the sidebar. + ** This controls the width of the sidebar. It is measured in screen columns. + ** For example: sidebar_width=20 could display 20 ASCII characters, or 10 + ** Chinese characters. */ - { "sig_dashes", DT_BOOL, R_NONE, OPTSIGDASHES, 1 }, /* ** .pp diff --git a/mh.c b/mh.c index 5f23c9cac..266dc8007 100644 --- a/mh.c +++ b/mh.c @@ -295,6 +295,17 @@ void mh_buffy(BUFFY *b) mhs_free_sequences (&mhs); } +/** + * mh_buffy_update - Update messages counts for an mh mailbox + * @path: Pathname of the mailbox + * @msg_count: Out: total number of messages + * @msg_unread: Out: number of unread messages + * @msg_flagged: Out: number of flagged messages + * @sb_last_checked: Out: timestamp the mailbox was last checked (NOW) + * + * Read through an mh mailbox and count messages. Save the number of new, + * flagged messages and a timestamp for now. + */ void mh_buffy_update (const char *path, int *msgcount, int *msg_unread, int *msg_flagged, time_t *sb_last_checked) { diff --git a/sidebar.c b/sidebar.c index 88fadc6a9..bb1cbf9f6 100644 --- a/sidebar.c +++ b/sidebar.c @@ -31,6 +31,11 @@ static BUFFY *TopBuffy; static BUFFY *BottomBuffy; static int known_lines; +/** + * struct sidebar_entry - Info about folders in the sidebar + * + * Used in the mutt_FormatString callback + */ struct sidebar_entry { char box[SHORT_STRING]; unsigned int size; @@ -38,6 +43,18 @@ struct sidebar_entry { unsigned int flagged; }; + +/** + * find_next_new - Find the next folder that contains new mail + * @wrap: Wrap around to the beginning if the end is reached + * + * Search down the list of mail folders for one containing new, or flagged, + * mail, or a folder that is in the SidebarWhitelist. + * + * Returns: + * BUFFY*: Success + * NULL: Failure + */ static BUFFY * find_next_new (int wrap) { @@ -61,6 +78,17 @@ find_next_new (int wrap) return NULL; } +/** + * find_prev_new - Find the previous folder that contains new mail + * @wrap: Wrap around to the beginning if the end is reached + * + * Search up the list of mail folders for one containing new, or flagged, mail, + * or a folder that is in the SidebarWhitelist. + * + * Returns: + * BUFFY*: Success + * NULL: Failure + */ static BUFFY * find_prev_new (int wrap) { @@ -84,7 +112,15 @@ find_prev_new (int wrap) return NULL; } - +/** + * calc_boundaries - Keep our TopBuffy/BottomBuffy up-to-date + * + * Whenever the sidebar's view of the BUFFYs changes, or the screen changes + * size, we should check TopBuffy and BottomBuffy still have the correct + * values. + * + * Ideally, this should happen in the core of mutt. + */ static void calc_boundaries (void) { @@ -128,6 +164,26 @@ calc_boundaries (void) } } +/** + * cb_format_str - Create the string to show in the sidebar + * @dest: Buffer in which to save string + * @destlen: Buffer length + * @col: Starting column, UNUSED + * @op: printf-like operator, e.g. 'B' + * @src: printf-like format string + * @prefix: Field formatting string, UNUSED + * @ifstring: If condition is met, display this string + * @elsestring: Otherwise, display this string + * @data: Pointer to our sidebar_entry + * @flags: Format flags, e.g. M_FORMAT_OPTIONAL + * + * cb_format_str is a callback function for mutt_FormatString. It understands + * five operators. '%B' : Mailbox name, '%F' : Number of flagged messages, + * '%N' : Number of new messages, '%S' : Size (total number of messages), + * '%!' : Icon denoting number of flagged messages. + * + * Returns: src (unchanged) + */ static const char * cb_format_str (char *dest, size_t destlen, size_t col, char op, const char *src, const char *prefix, const char *ifstring, const char *elsestring, @@ -199,6 +255,20 @@ cb_format_str (char *dest, size_t destlen, size_t col, char op, const char *src, return src; } +/** + * make_sidebar_entry - Turn mailbox data into a sidebar string + * @buf: Buffer in which to save string + * @buflen: Buffer length + * @width: Desired width in screen cells + * @box: Mailbox name + * @size: Size (total number of messages) + * @new: Number of new messages + * @flagged: Number of flagged messages + * + * Take all the relevant mailbox data and the desired screen width and then get + * mutt_FormatString to do the actual work. mutt_FormatString will callback to + * us using cb_format_str() for the sidebar specific formatting characters. + */ static void make_sidebar_entry (char *buf, unsigned int buflen, int width, char *box, unsigned int size, unsigned int new, unsigned int flagged) @@ -237,6 +307,12 @@ make_sidebar_entry (char *buf, unsigned int buflen, int width, char *box, } +/** + * sb_draw - Completely redraw the sidebar + * + * Completely refresh the sidebar region. First draw the divider; then, for + * each BUFFY, call make_sidebar_entry; finally blank out any remaining space. + */ void sb_draw (void) { @@ -441,6 +517,16 @@ sb_draw (void) } } +/** + * sb_should_refresh - Check if the sidebar is due to be refreshed + * + * The "sidebar_refresh" config option allows the user to limit the frequency + * with which the sidebar is refreshed. + * + * Returns: + * 1 Yes, refresh is due + * 0 No, refresh happened recently + */ int sb_should_refresh (void) { @@ -452,6 +538,20 @@ sb_should_refresh (void) return 0; } +/** + * sb_change_mailbox - Change the selected mailbox + * @op: Operation code + * + * Change the selected mailbox, e.g. "Next mailbox", "Previous Mailbox + * with new mail". The operations are listed OPS.SIDEBAR which is built + * into an enum in keymap_defs.h. + * + * If the operation is successful, CurBuffy will be set to the new mailbox. + * This function only *selects* the mailbox, doesn't *open* it. + * + * Allowed values are: OP_SIDEBAR_NEXT, OP_SIDEBAR_NEXT_NEW, OP_SIDEBAR_PREV, + * OP_SIDEBAR_PREV_NEW, OP_SIDEBAR_SCROLL_DOWN, OP_SIDEBAR_SCROLL_UP. + */ void sb_change_mailbox (int op) { @@ -467,6 +567,7 @@ sb_change_mailbox (int op) CurBuffy = CurBuffy->next; break; } + /* drop through */ case OP_SIDEBAR_NEXT_NEW: b = find_next_new (option (OPTSIDEBARNEXTNEWWRAP)); if (!b) { @@ -482,6 +583,7 @@ sb_change_mailbox (int op) CurBuffy = CurBuffy->prev; break; } + /* drop through */ case OP_SIDEBAR_PREV_NEW: b = find_prev_new (option (OPTSIDEBARNEXTNEWWRAP)); if (!b) { @@ -511,6 +613,13 @@ sb_change_mailbox (int op) sb_draw(); } +/** + * sb_set_buffystats - Update the BUFFY's message counts from the CONTEXT + * @ctx: A mailbox CONTEXT + * + * Given a mailbox CONTEXT, find a matching mailbox BUFFY and copy the message + * counts into it. + */ void sb_set_buffystats (const CONTEXT *ctx) { @@ -531,9 +640,18 @@ sb_set_buffystats (const CONTEXT *ctx) } } +/** + * sb_set_open_buffy - Set the CurBuffy based on a mailbox path + * @path: Mailbox path + * + * Search through the list of mailboxes. If a BUFFY has a matching path, set + * CurBuffy to it. + */ void sb_set_open_buffy (char *path) { + /* Even if the sidebar is hidden */ + BUFFY *b = CurBuffy = Incoming; if (!path || !b) @@ -548,9 +666,17 @@ sb_set_open_buffy (char *path) } } +/** + * sb_set_update_time - Note the time that the sidebar was updated + * + * Update the timestamp representing the last sidebar update. If the user + * configures "sidebar_refresh", this will help to reduce traffic. + */ void sb_set_update_time (void) { + /* XXX - should this be public? */ + SidebarLastRefresh = time (NULL); } -- 2.50.0