From: Richard Russon Date: Fri, 20 Jul 2018 10:46:35 +0000 (+0100) Subject: doxygen: lots of docs (94%) X-Git-Tag: 2019-10-25~744 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=290fef718076373e5e86b2460cb9963846623a23;p=neomutt doxygen: lots of docs (94%) --- diff --git a/curs_lib.c b/curs_lib.c index b3516d2e8..d1bacc8d5 100644 --- a/curs_lib.c +++ b/curs_lib.c @@ -82,6 +82,9 @@ static size_t UngetCount = 0; static size_t UngetLen = 0; static struct Event *UngetKeyEvents; +/** + * mutt_refresh - Force a refresh of the screen + */ void mutt_refresh(void) { /* don't refresh when we are waiting for a child. */ @@ -111,6 +114,19 @@ void mutt_need_hard_redraw(void) mutt_menu_set_current_redraw_full(); } +/** + * mutt_getch - Read a character from the input buffer + * @retval obj Event to process + * + * The priority for reading events is: + * 1. UngetKeyEvents buffer + * 2. MacroEvents buffer + * 3. Keyboard + * + * This function can return: + * - Error `{ -1, OP_NULL }` + * - Timeout `{ -2, OP_NULL }` + */ struct Event mutt_getch(void) { int ch; @@ -165,6 +181,19 @@ struct Event mutt_getch(void) return ch == ctrl('G') ? err : ret; } +/** + * mutt_get_field_full - Ask the user for a string + * @param[in] field Prompt + * @param[in] buf Buffer for the result + * @param[in] buflen Length of buffer + * @param[in] complete Flags for completion, e.g. #MUTT_FILE + * @param[in] multiple Allow multiple selections + * @param[out] files List of files selected + * @param[out] numfiles Number of files selected + * @retval 1 Redraw the screen and call the function again + * @retval 0 Selection made + * @retval -1 Aborted + */ int mutt_get_field_full(const char *field, char *buf, size_t buflen, int complete, int multiple, char ***files, int *numfiles) { @@ -196,6 +225,16 @@ int mutt_get_field_full(const char *field, char *buf, size_t buflen, return ret; } +/** + * mutt_get_field_unbuffered - Ask the user for a string (ignoring macro buffer) + * @param msg Prompt + * @param buf Buffer for the result + * @param buflen Length of buffer + * @param flags Flags for completion, e.g. #MUTT_FILE + * @retval 1 Redraw the screen and call the function again + * @retval 0 Selection made + * @retval -1 Aborted + */ int mutt_get_field_unbuffered(char *msg, char *buf, size_t buflen, int flags) { int rc; @@ -207,12 +246,17 @@ int mutt_get_field_unbuffered(char *msg, char *buf, size_t buflen, int flags) return rc; } -void mutt_edit_file(const char *editor, const char *data) +/** + * mutt_edit_file - Let the user edit a file + * @param editor User's editor config + * @param file File to edit + */ +void mutt_edit_file(const char *editor, const char *file) { char cmd[HUGE_STRING]; mutt_endwin(); - mutt_expand_file_fmt(cmd, sizeof(cmd), editor, data); + mutt_expand_file_fmt(cmd, sizeof(cmd), editor, file); if (mutt_system(cmd) != 0) { mutt_error(_("Error running \"%s\"!"), cmd); @@ -223,6 +267,12 @@ void mutt_edit_file(const char *editor, const char *data) clearok(stdscr, true); } +/** + * mutt_yesorno - Ask the user a Yes/No question + * @param msg Prompt + * @param def Default answer, e.g. #MUTT_YES + * @retval num Selection made, e.g. #MUTT_NO + */ int mutt_yesorno(const char *msg, int def) { struct Event ch; @@ -376,6 +426,9 @@ void mutt_query_exit(void) SigInt = 0; } +/** + * mutt_show_error - Show the user an error message + */ void mutt_show_error(void) { if (OptKeepQuiet || !ErrorBufMessage) @@ -387,6 +440,9 @@ void mutt_show_error(void) mutt_window_clrtoeol(MuttMessageWindow); } +/** + * mutt_endwin - Shutdown curses/slang + */ void mutt_endwin(void) { if (OptNoCurses) @@ -402,6 +458,10 @@ void mutt_endwin(void) errno = e; } +/** + * mutt_perror_debug - Show the user an 'errno' message + * @param s Additional text to show + */ void mutt_perror_debug(const char *s) { char *p = strerror(errno); @@ -410,6 +470,12 @@ void mutt_perror_debug(const char *s) mutt_error("%s: %s (errno = %d)", s, p ? p : _("unknown error"), errno); } +/** + * mutt_any_key_to_continue - Prompt the user to 'press any key' and wait + * @param s Message prompt + * @retval num Key pressed + * @retval EOF Error, or prompt aborted + */ int mutt_any_key_to_continue(const char *s) { struct termios t; @@ -440,6 +506,15 @@ int mutt_any_key_to_continue(const char *s) return (ch >= 0) ? ch : EOF; } +/** + * mutt_do_pager - Display some page-able text to the user + * @param banner Message for status bar + * @param tempfile File to display + * @param do_color Flags, e.g. #MUTT_PAGER_MESSAGE + * @param info Info about current mailbox (OPTIONAL) + * @retval 0 Success + * @retval -1 Error + */ int mutt_do_pager(const char *banner, const char *tempfile, int do_color, struct Pager *info) { int rc; @@ -465,6 +540,19 @@ int mutt_do_pager(const char *banner, const char *tempfile, int do_color, struct return rc; } +/** + * mutt_enter_fname_full - Ask the user to select a file + * @param[in] prompt Prompt + * @param[in] buf Buffer for the result + * @param[in] blen Length of the buffer + * @param[in] buffy If true, select mailboxes + * @param[in] multiple Allow multiple selections + * @param[out] files List of files selected + * @param[out] numfiles Number of files selected + * @param[in] flags Flags, e.g. #MUTT_SEL_FOLDER + * @retval 0 Success + * @retval -1 Error + */ int mutt_enter_fname_full(const char *prompt, char *buf, size_t blen, int buffy, int multiple, char ***files, int *numfiles, int flags) { @@ -519,6 +607,13 @@ int mutt_enter_fname_full(const char *prompt, char *buf, size_t blen, int buffy, return 0; } +/** + * mutt_unget_event - Return a keystroke to the input buffer + * @param ch Key press + * @param op Operation, e.g. OP_DELETE + * + * This puts events into the `UngetKeyEvents` buffer + */ void mutt_unget_event(int ch, int op) { struct Event tmp; @@ -532,6 +627,12 @@ void mutt_unget_event(int ch, int op) UngetKeyEvents[UngetCount++] = tmp; } +/** + * mutt_unget_string - Return a string to the input buffer + * @param s String to return + * + * This puts events into the `UngetKeyEvents` buffer + */ void mutt_unget_string(char *s) { char *p = s + mutt_str_strlen(s) - 1; @@ -563,6 +664,12 @@ void mutt_push_macro_event(int ch, int op) MacroEvents[MacroBufferCount++] = tmp; } +/** + * mutt_flush_macro_to_endcond - Drop a macro from the input buffer + * + * All the macro text is deleted until an OP_END_COND command, + * or the buffer is empty. + */ void mutt_flush_macro_to_endcond(void) { UngetCount = 0; @@ -589,6 +696,9 @@ void mutt_flush_unget_to_endcond(void) } } +/** + * mutt_flushinp - Empty all the keyboard buffers + */ void mutt_flushinp(void) { UngetCount = 0; @@ -621,6 +731,13 @@ void mutt_curs_set(int cursor) } #endif +/** + * mutt_multi_choice - Offer the user a multiple choice question + * @param prompt Message prompt + * @param letters Allowable selection keys + * @retval >=0 0-based user selection + * @retval -1 Selection aborted + */ int mutt_multi_choice(char *prompt, char *letters) { struct Event ch; diff --git a/curs_lib.h b/curs_lib.h index edab4cfd8..a81a6da84 100644 --- a/curs_lib.h +++ b/curs_lib.h @@ -45,7 +45,7 @@ bool message_is_visible(struct Context *ctx, int index); int mutt_addwch(wchar_t wc); int mutt_any_key_to_continue(const char *s); int mutt_do_pager(const char *banner, const char *tempfile, int do_color, struct Pager *info); -void mutt_edit_file(const char *editor, const char *data); +void mutt_edit_file(const char *editor, const char *file); void mutt_endwin(void); int mutt_enter_fname_full(const char *prompt, char *buf, size_t blen, int buffy, int multiple, char ***files, int *numfiles, int flags); void mutt_flushinp(void); diff --git a/enter.c b/enter.c index 484034d1a..1f52f0c72 100644 --- a/enter.c +++ b/enter.c @@ -169,9 +169,9 @@ int mutt_enter_string(char *buf, size_t buflen, int col, int flags) * @param[out] files List of files selected * @param[out] numfiles Number of files selected * @param[out] state Current state (if function is called repeatedly) - * @retval 1 need to redraw the screen and call me again - * @retval 0 if input was given - * @retval -1 if abort + * @retval 1 Redraw the screen and call the function again + * @retval 0 Selection made + * @retval -1 Aborted */ int mutt_enter_string_full(char *buf, size_t buflen, int col, int flags, int multiple, char ***files, int *numfiles, struct EnterState *state) diff --git a/hdrline.c b/hdrline.c index 10f10c9f2..f81315d14 100644 --- a/hdrline.c +++ b/hdrline.c @@ -70,6 +70,11 @@ enum FlagChars FlagCharZEmpty }; +/** + * mutt_is_mail_list - Is this the email address of a mailing list? + * @param addr Address to test + * @retval true If it's a mailing list + */ bool mutt_is_mail_list(struct Address *addr) { if (!mutt_regexlist_match(UnMailLists, addr->mailbox)) @@ -77,6 +82,11 @@ bool mutt_is_mail_list(struct Address *addr) return false; } +/** + * mutt_is_subscribed_list - Is this the email address of a user-subscribed mailing list? + * @param addr Address to test + * @retval true If it's a subscribed mailing list + */ bool mutt_is_subscribed_list(struct Address *addr) { if (!mutt_regexlist_match(UnMailLists, addr->mailbox) && @@ -136,6 +146,13 @@ static bool check_for_mailing_list_addr(struct Address *addr, char *buf, int buf return false; } +/** + * first_mailing_list - Get the first mailing list in the list of addresses + * @param buf Buffer for the result + * @param buflen Length of buffer + * @param a Address list + * @retval true If a mailing list was found + */ static bool first_mailing_list(char *buf, size_t buflen, struct Address *a) { for (; a; a = a->next) @@ -310,6 +327,13 @@ static void make_from(struct Envelope *env, char *buf, size_t buflen, bool do_li snprintf(buf, buflen, "%s%s", make_from_prefix(disp), mutt_get_name(name)); } +/** + * make_from_addr - Create a 'from' address for a reply email + * @param hdr Envelope of current email + * @param buf Buffer for the result + * @param buflen Length of buffer + * @param do_lists If true, check for mailing lists + */ static void make_from_addr(struct Envelope *hdr, char *buf, size_t buflen, bool do_lists) { if (!hdr || !buf) @@ -335,6 +359,11 @@ static void make_from_addr(struct Envelope *hdr, char *buf, size_t buflen, bool *buf = 0; } +/** + * user_in_addr - Do any of the addresses refer to the user? + * @param a Address list + * @retval true If any of the addresses match one of the user's addresses + */ static bool user_in_addr(struct Address *a) { for (; a; a = a->next) @@ -386,6 +415,12 @@ static int user_is_recipient(struct Header *h) return h->recipient; } +/** + * apply_subject_mods - Apply regex modifications to the subject + * @param env Envelope of email + * @retval ptr Modified subject + * @retval NULL No modification made + */ static char *apply_subject_mods(struct Envelope *env) { if (!env) @@ -404,12 +439,24 @@ static char *apply_subject_mods(struct Envelope *env) return env->disp_subj; } +/** + * thread_is_new - Does the email thread contain any new emails? + * @param ctx Mailbox + * @param hdr Header of an email + * @retval true If thread contains new mail + */ static bool thread_is_new(struct Context *ctx, struct Header *hdr) { return hdr->collapsed && (hdr->num_hidden > 1) && (mutt_thread_contains_unread(ctx, hdr) == 1); } +/** + * thread_is_old - Does the email thread contain any unread emails? + * @param ctx Mailbox + * @param hdr Header of an email + * @retval true If thread contains unread mail + */ static bool thread_is_old(struct Context *ctx, struct Header *hdr) { return hdr->collapsed && (hdr->num_hidden > 1) && @@ -1379,6 +1426,15 @@ static const char *index_format_str(char *buf, size_t buflen, size_t col, int co return src; } +/** + * mutt_make_string_flags - Create formatted strings using mailbox expandos + * @param buf Buffer for the result + * @param buflen Buffer length + * @param s printf-line format string + * @param ctx Mailbox + * @param hdr Header of email + * @param flags Format flags + */ void mutt_make_string_flags(char *buf, size_t buflen, const char *s, struct Context *ctx, struct Header *hdr, enum FormatFlag flags) { @@ -1392,6 +1448,15 @@ void mutt_make_string_flags(char *buf, size_t buflen, const char *s, index_format_str, (unsigned long) &hfi, flags); } +/** + * mutt_make_string_info - Create pager status bar string + * @param buf Buffer for the result + * @param buflen Buffer length + * @param cols Number of screen columns + * @param s printf-line format string + * @param hfi Mailbox data to pass to the formatter + * @param flags Format flags + */ void mutt_make_string_info(char *buf, size_t buflen, int cols, const char *s, struct HdrFormatInfo *hfi, enum FormatFlag flags) { diff --git a/help.c b/help.c index 1628c216f..6c540da0d 100644 --- a/help.c +++ b/help.c @@ -43,6 +43,13 @@ static const char *HelpStrings[] = { NULL, }; +/** + * help_lookup_function - Find a keybinding for an operation + * @param op Operation, e.g. OP_DELETE + * @param menu Current Menu + * @retval ptr Key binding + * @retval NULL If none + */ static const struct Binding *help_lookup_function(int op, int menu) { const struct Binding *map = NULL; @@ -66,6 +73,16 @@ static const struct Binding *help_lookup_function(int op, int menu) return NULL; } +/** + * mutt_make_help - Create one entry for the help bar + * @param d Buffer for the result + * @param dlen Length of buffer + * @param txt Text part, e.g. "delete" + * @param menu Current Menu + * @param op Operation, e.g. OP_DELETE + * + * This will return something like: "d:delete" + */ void mutt_make_help(char *d, size_t dlen, const char *txt, int menu, int op) { char buf[SHORT_STRING]; @@ -81,6 +98,14 @@ void mutt_make_help(char *d, size_t dlen, const char *txt, int menu, int op) } } +/** + * mutt_compile_help - Create the text for the help menu + * @param buf Buffer for the result + * @param buflen Length of buffer + * @param menu Current Menu + * @param items Map of functions to display in the help bar + * @retval ptr Buffer containing result + */ char *mutt_compile_help(char *buf, size_t buflen, int menu, const struct Mapping *items) { char *pbuf = buf; @@ -101,6 +126,15 @@ char *mutt_compile_help(char *buf, size_t buflen, int menu, const struct Mapping return buf; } +/** + * print_macro - Print a macro string to a file + * @param[in] f File to write to + * @param[in] maxwidth Maximum width in screen columns + * @param[out] macro Macro string + * @retval num Number of screen columns used + * + * The `macro` pointer is move past the string we've printed + */ static int print_macro(FILE *f, int maxwidth, const char **macro) { int n = maxwidth; @@ -164,6 +198,14 @@ static int print_macro(FILE *f, int maxwidth, const char **macro) return maxwidth - n; } +/** + * get_wrapped_width - Wrap a string at a sensible place + * @param t String to wrap + * @param wid Maximum width + * @retval num Break after this many characters + * + * If the string's too long, look for some whitespace to break at. + */ static int get_wrapped_width(const char *t, size_t wid) { wchar_t wc; @@ -197,6 +239,14 @@ static int get_wrapped_width(const char *t, size_t wid) return n; } +/** + * pad - Write some padding to a file + * @param f File to write to + * @param col Current screen column + * @param i Screen column to pad until + * @retval col Padding was added + * @retval i Content was already wider than col + */ static int pad(FILE *f, int col, int i) { if (col < i) @@ -210,6 +260,21 @@ static int pad(FILE *f, int col, int i) return col + 1; } +/** + * format_line - Write a formatted line to a file + * @param f File to write to + * @param ismacro Layout mode, see below + * @param t1 Text part 1 + * @param t2 Text part 2 + * @param t3 Text part 3 + * + * Assemble the three columns of text. + * + * `ismacro` can be: + * * 1 : Macro with a description + * * 0 : Non-macro + * * -1 : Macro with no description + */ static void format_line(FILE *f, int ismacro, const char *t1, const char *t2, const char *t3) { int col; @@ -294,6 +359,11 @@ static void format_line(FILE *f, int ismacro, const char *t1, const char *t2, co fputc('\n', f); } +/** + * dump_menu - Write all the key bindings to a file + * @param f File to write to + * @param menu Current Menu + */ static void dump_menu(FILE *f, int menu) { struct Keymap *map = NULL; @@ -324,6 +394,12 @@ static void dump_menu(FILE *f, int menu) } } +/** + * is_bound - Does a function have a keybinding? + * @param map Keymap to examine + * @param op Operation, e.g. OP_DELETE + * @retval true If a key is bound to that operation + */ static bool is_bound(struct Keymap *map, int op) { for (; map; map = map->next) @@ -332,6 +408,13 @@ static bool is_bound(struct Keymap *map, int op) return false; } +/** + * dump_unbound - Write out all the operations with no key bindings + * @param f File to write to + * @param funcs All the bindings for the current menu + * @param map First key map to consider + * @param aux Second key map to consider + */ static void dump_unbound(FILE *f, const struct Binding *funcs, struct Keymap *map, struct Keymap *aux) { @@ -342,6 +425,10 @@ static void dump_unbound(FILE *f, const struct Binding *funcs, } } +/** + * mutt_help - Display the help menu + * @param menu Current Menu + */ void mutt_help(int menu) { char t[PATH_MAX]; diff --git a/muttlib.c b/muttlib.c index 4e4773068..b8d15eaad 100644 --- a/muttlib.c +++ b/muttlib.c @@ -106,11 +106,28 @@ void mutt_adv_mktemp(char *buf, size_t buflen) } } +/** + * mutt_expand_path - Create the canonical path + * @param s Buffer with path + * @param slen Length of buffer + * @retval ptr The expanded string + * + * @note The path is expanded in-place + */ char *mutt_expand_path(char *s, size_t slen) { return mutt_expand_path_regex(s, slen, false); } +/** + * mutt_expand_path_regex - Create the canonical path (with regex char escaping) + * @param s Buffer with path + * @param slen Length of buffer + * @param regex If true, escape any regex characters + * @retval ptr The expanded string + * + * @note The path is expanded in-place + */ char *mutt_expand_path_regex(char *s, size_t slen, bool regex) { char p[PATH_MAX] = ""; @@ -366,6 +383,11 @@ bool mutt_needs_mailcap(struct Body *m) return true; } +/** + * mutt_is_text_part - Is this part of an email in plain text? + * @param b Part of an email + * @retval true If part is in plain text + */ bool mutt_is_text_part(struct Body *b) { int t = b->type; @@ -394,6 +416,13 @@ bool mutt_is_text_part(struct Body *b) static FILE *frandom; +/** + * mutt_randbuf - Fill a buffer with randomness + * @param out Buffer for result + * @param len Size of buffer + * @retval 0 Success + * @retval -1 Error + */ int mutt_randbuf(void *out, size_t len) { if (len > 1048576) @@ -434,6 +463,11 @@ int mutt_randbuf(void *out, size_t len) static const unsigned char base32[] = "abcdefghijklmnopqrstuvwxyz234567"; +/** + * mutt_rand_base32 - Fill a buffer with a base32-encoded random string + * @param out Buffer for result + * @param len Length of buffer + */ void mutt_rand_base32(void *out, size_t len) { uint8_t *p = out; @@ -444,6 +478,10 @@ void mutt_rand_base32(void *out, size_t len) p[pos] = base32[p[pos] % 32]; } +/** + * mutt_rand32 - Create a 32-bit random number + * @retval num Random number + */ uint32_t mutt_rand32(void) { uint32_t ret = 0; @@ -453,6 +491,10 @@ uint32_t mutt_rand32(void) return ret; } +/** + * mutt_rand64 - Create a 64-bit random number + * @retval num Random number + */ uint64_t mutt_rand64(void) { uint64_t ret = 0; @@ -462,6 +504,17 @@ uint64_t mutt_rand64(void) return ret; } +/** + * mutt_mktemp_full - Create a temporary filename + * @param s Buffer for result + * @param slen Length of buffer + * @param prefix Prefix for filename + * @param suffix Suffix for filename + * @param src Source file of caller + * @param line Source line number of caller + * + * @note This doesn't create the file, only the name + */ void mutt_mktemp_full(char *s, size_t slen, const char *prefix, const char *suffix, const char *src, int line) { @@ -563,6 +616,15 @@ void mutt_pretty_mailbox(char *s, size_t buflen) } } +/** + * mutt_expand_file_fmt - Replace `%s` with a filename in a string + * @param dest Buffer for the result + * @param destlen Length of buffer + * @param fmt printf-like format string + * @param src Filename to substitute + * + * This function also quotes the file to prevent shell problems. + */ void mutt_expand_file_fmt(char *dest, size_t destlen, const char *fmt, const char *src) { char tmp[PATH_MAX]; @@ -571,6 +633,13 @@ void mutt_expand_file_fmt(char *dest, size_t destlen, const char *fmt, const cha mutt_expand_fmt(dest, destlen, fmt, tmp); } +/** + * mutt_expand_fmt - Replace `%s` with a filename in a string + * @param dest Buffer for the result + * @param destlen Length of buffer + * @param fmt printf-like format string + * @param src Filename to substitute + */ void mutt_expand_fmt(char *dest, size_t destlen, const char *fmt, const char *src) { const char *p = NULL; @@ -710,6 +779,15 @@ int mutt_check_overwrite(const char *attname, const char *path, char *fname, return 0; } +/** + * mutt_save_path - Turn an email address into a filename (for saving) + * @param d Buffer for the result + * @param dsize Length of buffer + * @param a Email address to use + * + * If the user hasn't set `$save_address` the name will be trucated to the '@' + * character. + */ void mutt_save_path(char *d, size_t dsize, struct Address *a) { if (a && a->mailbox) @@ -727,6 +805,14 @@ void mutt_save_path(char *d, size_t dsize, struct Address *a) *d = 0; } +/** + * mutt_safe_path - Make a safe filename from an email address + * @param s Buffer for the result + * @param l Length of buffer + * @param a Address to use + * + * The filename will be stripped of '/', space, etc to make it safe. + */ void mutt_safe_path(char *s, size_t l, struct Address *a) { mutt_save_path(s, l, a); @@ -1397,6 +1483,12 @@ int mutt_save_confirm(const char *s, struct stat *st) return ret; } +/** + * mutt_sleep - Sleep for a while + * @param s Number of seconds to sleep + * + * If the user config `SleepTime` is larger, sleep that long instead. + */ void mutt_sleep(short s) { if (SleepTime > s) @@ -1405,6 +1497,12 @@ void mutt_sleep(short s) sleep(s); } +/** + * mutt_make_version - Generate the NeoMutt version string + * @retval ptr Version string + * + * @note This returns a pointer to a static buffer + */ const char *mutt_make_version(void) { static char vstring[STRING]; @@ -1412,6 +1510,14 @@ const char *mutt_make_version(void) return vstring; } +/** + * mutt_encode_path - Convert a path into the user's preferred character set + * @param dest Buffer for the result + * @param dlen Length of buffer + * @param src Path to convert (OPTIONAL) + * + * If `src` is NULL, the path in `dest` will be converted in-place. + */ void mutt_encode_path(char *dest, size_t dlen, const char *src) { char *p = mutt_str_strdup(src); @@ -1472,6 +1578,12 @@ int mutt_set_xdg_path(enum XdgType type, char *buf, size_t bufsize) return rc; } +/** + * mutt_get_parent_path - Find the parent of a path (or mailbox) + * @param output Buffer for the result + * @param path Path to use + * @param olen Length of buffer + */ void mutt_get_parent_path(char *output, char *path, size_t olen) { #ifdef USE_IMAP diff --git a/ncrypt/crypt_gpgme.c b/ncrypt/crypt_gpgme.c index 6ff6ae436..930099fa3 100644 --- a/ncrypt/crypt_gpgme.c +++ b/ncrypt/crypt_gpgme.c @@ -133,6 +133,11 @@ static char *current_sender = NULL; #define PKA_NOTATION_NAME "pka-address@gnupg.org" +/** + * is_pka_notation - Is this the standard pka email address + * @param notation GPGME notation + * @retval true If it is + */ static bool is_pka_notation(gpgme_sig_notation_t notation) { return mutt_str_strcmp(notation->name, PKA_NOTATION_NAME) == 0; @@ -446,7 +451,7 @@ static int crypt_id_is_valid(struct CryptKeyInfo *key) } /** - * crypt_id_matches_addr - Does key ID match the address + * crypt_id_matches_addr - Does the key ID match the address * @param addr First email address * @param u_addr Second email address * @param key Key to use @@ -727,6 +732,10 @@ static char *data_object_to_tempfile(gpgme_data_t data, FILE **ret_fp) return mutt_str_strdup(tempf); } +/** + * free_recipient_set - Free a set of recipients + * @param p_rset Set of GPGME keys + */ static void free_recipient_set(gpgme_key_t **p_rset) { gpgme_key_t *rset = NULL; @@ -870,6 +879,11 @@ static int set_signer(gpgme_ctx_t ctx, bool for_smime) return 0; } +/** + * set_pka_sig_notation - Set the signature notation + * @param ctx GPGME context + * @retval num GPGME error code, e.g. GPG_ERR_NO_ERROR + */ static gpgme_error_t set_pka_sig_notation(gpgme_ctx_t ctx) { gpgme_error_t err; @@ -946,6 +960,10 @@ static char *encrypt_gpgme_object(gpgme_data_t plaintext, gpgme_key_t *rset, return outfile; } +/** + * strlower - Lower-case a string + * @param s String to alter + */ static void strlower(char *s) { for (; *s; ++s) @@ -997,6 +1015,11 @@ static int get_micalg(gpgme_ctx_t ctx, int use_smime, char *buf, size_t buflen) return *buf ? 0 : -1; } +/** + * print_time - Print the date/time according to the locale + * @param t Timestamp + * @param s State to write to + */ static void print_time(time_t t, struct State *s) { char p[STRING]; @@ -1382,6 +1405,11 @@ static int show_sig_summary(unsigned long sum, gpgme_ctx_t ctx, gpgme_key_t key, return severe; } +/** + * show_fingerprint - Write a key's fingerprint + * @param key GPGME key + * @param state State to write to + */ static void show_fingerprint(gpgme_key_t key, struct State *state) { const char *s = NULL; @@ -1475,6 +1503,13 @@ static void show_one_sig_validity(gpgme_ctx_t ctx, int idx, struct State *s) state_puts(txt, s); } +/** + * print_smime_keyinfo - Print key info about an SMIME key + * @param msg Prefix message to write + * @param sig GPGME signature + * @param key GPGME key + * @param s State to write to + */ static void print_smime_keyinfo(const char *msg, gpgme_signature_t sig, gpgme_key_t key, struct State *s) { @@ -2160,6 +2195,14 @@ int smime_gpgme_decrypt_mime(FILE *fpin, FILE **fpout, struct Body *b, struct Bo return *cur ? 0 : -1; } +/** + * pgp_gpgme_extract_keys - Write PGP keys to a file + * @param[in] keydata GPGME key data + * @param[out] fp Temporary file created with key info + * @param[in] dryrun If true, don't save the key to the user's keyring + * @retval 0 Success + * @retval -1 Error + */ static int pgp_gpgme_extract_keys(gpgme_data_t keydata, FILE **fp, int dryrun) { /* there's no side-effect free way to view key data in GPGME, @@ -2308,6 +2351,13 @@ static int line_compare(const char *a, size_t n, const char *b) #define BEGIN_PGP_SIGNATURE(_y) \ _LINE_COMPARE("-----BEGIN PGP SIGNATURE-----", _y) +/** + * pgp_check_traditional_one_body - Check one inline PGP body part + * @param fp File to read from + * @param b Body of the email + * @retval 1 Success + * @retval 0 Error + */ static int pgp_check_traditional_one_body(FILE *fp, struct Body *b) { char tempfile[PATH_MAX]; @@ -3161,6 +3211,14 @@ static int compare_key_address(const void *a, const void *b) return mutt_str_strcasecmp(crypt_fpr_or_lkeyid(*s), crypt_fpr_or_lkeyid(*t)) > 0; } +/** + * crypt_compare_address - Compare the addresses of two keys + * @param a First key + * @param b Second key + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int crypt_compare_address(const void *a, const void *b) { return (PgpSortKeys & SORT_REVERSE) ? !compare_key_address(a, b) : @@ -3188,6 +3246,14 @@ static int compare_keyid(const void *a, const void *b) return mutt_str_strcasecmp((*s)->uid, (*t)->uid) > 0; } +/** + * crypt_compare_keyid - Compare the IDs of two keys + * @param a First key ID + * @param b Second key ID + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int crypt_compare_keyid(const void *a, const void *b) { return (PgpSortKeys & SORT_REVERSE) ? !compare_keyid(a, b) : compare_keyid(a, b); @@ -3220,6 +3286,14 @@ static int compare_key_date(const void *a, const void *b) return mutt_str_strcasecmp((*s)->uid, (*t)->uid) > 0; } +/** + * crypt_compare_date - Compare the dates of two keys + * @param a First key + * @param b Second key + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int crypt_compare_date(const void *a, const void *b) { return (PgpSortKeys & SORT_REVERSE) ? !compare_key_date(a, b) : compare_key_date(a, b); @@ -3275,6 +3349,14 @@ static int compare_key_trust(const void *a, const void *b) return mutt_str_strcasecmp(crypt_fpr_or_lkeyid((*s)), crypt_fpr_or_lkeyid((*t))) > 0; } +/** + * crypt_compare_trust - Compare the trust levels of two keys + * @param a First key + * @param b Second key + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int crypt_compare_trust(const void *a, const void *b) { return (PgpSortKeys & SORT_REVERSE) ? !compare_key_trust(a, b) : @@ -3559,6 +3641,12 @@ enum KeyCap KEY_CAP_CAN_CERTIFY }; +/** + * key_check_cap - Check the capabilities of a key + * @param key GPGME key + * @param cap Flags, e.g. #KEY_CAP_CAN_ENCRYPT + * @retval >0 Key has the capabilities + */ static unsigned int key_check_cap(gpgme_key_t key, enum KeyCap cap) { gpgme_subkey_t subkey = NULL; @@ -4415,6 +4503,15 @@ static struct CryptKeyInfo *crypt_select_key(struct CryptKeyInfo *keys, return k; } +/** + * crypt_getkeybyaddr - Find a key by email address + * @param[in] a Address to match + * @param[in] abilities Abilities to match, e.g. #KEYFLAG_CANENCRYPT + * @param[in] app Application type, e.g. #APPLICATION_PGP + * @param[out] forced_valid Set to true if user overrode key's validity + * @param[in] oppenc_mode If true, use opportunistic encryption + * @retval ptr Matching key + */ static struct CryptKeyInfo *crypt_getkeybyaddr(struct Address *a, short abilities, unsigned int app, int *forced_valid, bool oppenc_mode) @@ -4537,6 +4634,14 @@ static struct CryptKeyInfo *crypt_getkeybyaddr(struct Address *a, return k; } +/** + * crypt_getkeybystr - Find a key by string + * @param[in] p String to match + * @param[in] abilities Abilities to match, e.g. #KEYFLAG_CANENCRYPT + * @param[in] app Application type, e.g. #APPLICATION_PGP + * @param[out] forced_valid Set to true if user overrode key's validity + * @retval ptr Matching key + */ static struct CryptKeyInfo *crypt_getkeybystr(char *p, short abilities, unsigned int app, int *forced_valid) { @@ -4903,6 +5008,9 @@ static void init_common(void) has_run = true; } +/** + * init_pgp - Initialise the PGP crypto backend + */ static void init_pgp(void) { if (gpgme_engine_check_version(GPGME_PROTOCOL_OpenPGP) != GPG_ERR_NO_ERROR) @@ -4911,6 +5019,9 @@ static void init_pgp(void) } } +/** + * init_smime - Initialise the SMIME crypto backend + */ static void init_smime(void) { if (gpgme_engine_check_version(GPGME_PROTOCOL_CMS) != GPG_ERR_NO_ERROR) @@ -4937,6 +5048,12 @@ void smime_gpgme_init(void) init_smime(); } +/** + * gpgme_send_menu - Show the user the encryption/signing menu + * @param msg Header of email + * @param is_smime True if an SMIME message + * @retval num Flags, e.g. #APPLICATION_SMIME | #ENCRYPT + */ static int gpgme_send_menu(struct Header *msg, int is_smime) { struct CryptKeyInfo *p = NULL; @@ -5109,6 +5226,11 @@ int smime_gpgme_send_menu(struct Header *msg) return gpgme_send_menu(msg, 1); } +/** + * verify_sender - Verify the sender of a message + * @param h Header of the email + * @retval true If sender is verified + */ static int verify_sender(struct Header *h) { struct Address *sender = NULL; diff --git a/ncrypt/pgpkey.c b/ncrypt/pgpkey.c index 73209839e..bfca3f44d 100644 --- a/ncrypt/pgpkey.c +++ b/ncrypt/pgpkey.c @@ -78,6 +78,13 @@ static struct PgpCache *id_defaults = NULL; static const char trust_flags[] = "?- +"; +/** + * pgp_key_abilities - Turn PGP key abilities into a string + * @param flags Flags, e.g. #KEYFLAG_CANENCRYPT + * @retval ptr Abilities string + * + * @note This returns a pointer to a static buffer + */ static char *pgp_key_abilities(int flags) { static char buf[3]; @@ -101,6 +108,11 @@ static char *pgp_key_abilities(int flags) return buf; } +/** + * pgp_flags - Turn PGP key flags into a string + * @param flags Flags, e.g. #KEYFLAG_REVOKED + * @retval char Flag character + */ static char pgp_flags(int flags) { if (flags & KEYFLAG_REVOKED) @@ -115,6 +127,11 @@ static char pgp_flags(int flags) return ' '; } +/** + * pgp_principal_key - Get the main (parent) PGP key + * @param key Key to start with + * @retval ptr PGP Key + */ static struct PgpKeyInfo *pgp_principal_key(struct PgpKeyInfo *key) { if (key->flags & KEYFLAG_SUBKEY && key->parent) @@ -151,15 +168,15 @@ struct PgpEntry * * | Expando | Description * |:--------|:-------------------------------------------------------- - * | \%a | Algorithm + * | \%a | Algorithm * | \%A | Algorithm of the princ. key - * | \%c | Capabilities + * | \%c | Capabilities * | \%C | Capabilities of the princ. key - * | \%f | Flags + * | \%f | Flags * | \%F | Flags of the princ. key * | \%k | Key id * | \%K | Key id of the principal key - * | \%l | Length + * | \%l | Length * | \%L | Length of the princ. key * | \%n | Number * | \%t | Trust/validity of the key-uid association @@ -356,12 +373,28 @@ static int compare_key_address(const void *a, const void *b) } } +/** + * pgp_compare_address - Compare the addresses of two PGP keys + * @param a First address + * @param b Second address + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int pgp_compare_address(const void *a, const void *b) { return (PgpSortKeys & SORT_REVERSE) ? !compare_key_address(a, b) : compare_key_address(a, b); } +/** + * compare_keyid - Compare Key IDs and addresses for sorting + * @param a First key ID + * @param b Second key ID + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int compare_keyid(const void *a, const void *b) { int r; @@ -376,11 +409,27 @@ static int compare_keyid(const void *a, const void *b) return mutt_str_strcasecmp((*s)->addr, (*t)->addr) > 0; } +/** + * pgp_compare_keyid - Compare key IDs + * @param a First key ID + * @param b Second key ID + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int pgp_compare_keyid(const void *a, const void *b) { return (PgpSortKeys & SORT_REVERSE) ? !compare_keyid(a, b) : compare_keyid(a, b); } +/** + * compare_keyid - Compare Key IDs and addresses for sorting + * @param a First key ID + * @param b Second key ID + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int compare_key_date(const void *a, const void *b) { int r; @@ -393,11 +442,30 @@ static int compare_key_date(const void *a, const void *b) return mutt_str_strcasecmp((*s)->addr, (*t)->addr) > 0; } +/** + * pgp_compare_date - Compare the dates of two PGP keys + * @param a First key + * @param b Second key + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int pgp_compare_date(const void *a, const void *b) { return (PgpSortKeys & SORT_REVERSE) ? !compare_key_date(a, b) : compare_key_date(a, b); } +/** + * compare_key_trust - Compare the trust of keys for sorting + * @param a First key + * @param b Second key + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + * + * Compare two trust values, the key length, the creation dates. the addresses + * and the key IDs. + */ static int compare_key_trust(const void *a, const void *b) { int r; @@ -425,12 +493,25 @@ static int compare_key_trust(const void *a, const void *b) pgp_fpr_or_lkeyid((*t)->parent)) > 0; } +/** + * pgp_compare_trust - Compare the trust levels of two PGP keys + * @param a First key + * @param b Second key + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int pgp_compare_trust(const void *a, const void *b) { return (PgpSortKeys & SORT_REVERSE) ? !compare_key_trust(a, b) : compare_key_trust(a, b); } +/** + * pgp_key_is_valid - Is a PGP key valid? + * @param k Key to examine + * @retval true If key is valid + */ static bool pgp_key_is_valid(struct PgpKeyInfo *k) { struct PgpKeyInfo *pk = pgp_principal_key(k); @@ -442,6 +523,11 @@ static bool pgp_key_is_valid(struct PgpKeyInfo *k) return true; } +/** + * pgp_id_is_strong - Is a PGP key strong? + * @param uid UID of a PGP key + * @retval true If key is strong + */ static bool pgp_id_is_strong(struct PgpUid *uid) { if ((uid->trust & 3) < 3) @@ -450,6 +536,11 @@ static bool pgp_id_is_strong(struct PgpUid *uid) return true; } +/** + * pgp_id_is_valid - Is a PGP key valid + * @param uid UID of a PGP key + * @retval true If key is valid + */ static bool pgp_id_is_valid(struct PgpUid *uid) { if (!pgp_key_is_valid(uid->parent)) @@ -467,6 +558,13 @@ static bool pgp_id_is_valid(struct PgpUid *uid) #define PGP_KV_MATCH (PGP_KV_ADDR | PGP_KV_STRING) +/** + * pgp_id_matches_addr - Does the key ID match the address + * @param addr First email address + * @param u_addr Second email address + * @param uid UID of PGP key + * @retval num Flags, e.g. #PGP_KV_VALID + */ static int pgp_id_matches_addr(struct Address *addr, struct Address *u_addr, struct PgpUid *uid) { int rc = 0; @@ -492,6 +590,13 @@ static int pgp_id_matches_addr(struct Address *addr, struct Address *u_addr, str return rc; } +/** + * pgp_select_key - Let the user select a key to use + * @param keys List of PGP keys + * @param p Address to match + * @param s String to match + * @retval ptr Selected PGP key + */ static struct PgpKeyInfo *pgp_select_key(struct PgpKeyInfo *keys, struct Address *p, const char *s) { @@ -712,6 +817,14 @@ static struct PgpKeyInfo *pgp_select_key(struct PgpKeyInfo *keys, return kp; } +/** + * pgp_ask_for_key - Ask the user for a PGP key + * @param tag Prompt for the user + * @param whatfor Use for key, e.g. "signing" + * @param abilities Abilities to match, e.g. #KEYFLAG_CANENCRYPT + * @param keyring PGP keyring to use + * @retval ptr Selected PGP key + */ struct PgpKeyInfo *pgp_ask_for_key(char *tag, char *whatfor, short abilities, enum PgpRing keyring) { struct PgpKeyInfo *key = NULL; @@ -860,6 +973,11 @@ static void pgp_add_string_to_hints(const char *str, struct ListHead *hints) FREE(&scratch); } +/** + * pgp_get_lastp - Get the last PGP key in a list + * @param p List of PGP keys + * @retval ptr Last PGP key in list + */ static struct PgpKeyInfo **pgp_get_lastp(struct PgpKeyInfo *p) { for (; p; p = p->next) @@ -869,6 +987,14 @@ static struct PgpKeyInfo **pgp_get_lastp(struct PgpKeyInfo *p) return NULL; } +/** + * pgp_getkeybyaddr - Find a PGP key by address + * @param a Email address to match + * @param abilities Abilities to match, e.g. #KEYFLAG_CANENCRYPT + * @param keyring PGP keyring to use + * @param oppenc_mode If true, use opportunistic encryption + * @retval ptr Matching PGP key + */ struct PgpKeyInfo *pgp_getkeybyaddr(struct Address *a, short abilities, enum PgpRing keyring, bool oppenc_mode) { @@ -997,6 +1123,13 @@ struct PgpKeyInfo *pgp_getkeybyaddr(struct Address *a, short abilities, return NULL; } +/** + * pgp_getkeybystr - Find a PGP key by string + * @param p String to match + * @param abilities Abilities to match, e.g. #KEYFLAG_CANENCRYPT + * @param keyring PGP keyring to use + * @retval ptr Matching PGP key + */ struct PgpKeyInfo *pgp_getkeybystr(char *p, short abilities, enum PgpRing keyring) { struct ListHead hints = STAILQ_HEAD_INITIALIZER(hints); diff --git a/ncrypt/smime.c b/ncrypt/smime.c index fe65bf126..5143f07ec 100644 --- a/ncrypt/smime.c +++ b/ncrypt/smime.c @@ -101,6 +101,10 @@ static char SmimeKeyToUse[PATH_MAX] = { 0 }; static char SmimeCertToUse[PATH_MAX]; static char SmimeIntermediateToUse[PATH_MAX]; +/** + * smime_free_key - Free a list of SMIME keys + * @param keylist List of keys to free + */ static void smime_free_key(struct SmimeKey **keylist) { struct SmimeKey *key = NULL; @@ -121,6 +125,11 @@ static void smime_free_key(struct SmimeKey **keylist) } } +/** + * smime_copy_key - Copy an SMIME key + * @param key Key to copy + * @retval ptr Newly allocated SMIME key + */ static struct SmimeKey *smime_copy_key(struct SmimeKey *key) { struct SmimeKey *copy = NULL; @@ -343,6 +352,13 @@ static const char *fmt_smime_command(char *buf, size_t buflen, size_t col, int c return src; } +/** + * smime_command - Format an SMIME command string + * @param buf Buffer for the result + * @param buflen Length of buffer + * @param cctx Data to pass to the formatter + * @param fmt printf-like formatting string + */ static void smime_command(char *buf, size_t buflen, struct SmimeCommandContext *cctx, const char *fmt) { @@ -403,6 +419,13 @@ static pid_t smime_invoke(FILE **smimein, FILE **smimeout, FILE **smimeerr, * Key and certificate handling. */ +/** + * smime_key_flags - Turn SMIME key flags into a string + * @param flags Flags, e.g. #KEYFLAG_CANENCRYPT + * @retval ptr Flag string + * + * Note: The string is statically allocated. + */ static char *smime_key_flags(int flags) { static char buf[3]; @@ -510,6 +533,12 @@ static void smime_entry(char *buf, size_t buflen, struct Menu *menu, int num) smime_key_flags(this->flags), truststate, this->email, this->label); } +/** + * smime_select_key - Get the user to select a key + * @param keys List of keys to select from + * @param query String to match + * @retval ptr Key selected by user + */ static struct SmimeKey *smime_select_key(struct SmimeKey *keys, char *query) { struct SmimeKey **table = NULL; @@ -608,6 +637,12 @@ static struct SmimeKey *smime_select_key(struct SmimeKey *keys, char *query) return selected_key; } +/** + * smime_parse_key - Parse an SMIME key block + * @param buf String to parse + * @retval ptr SMIME key + * @retval NULL Error + */ static struct SmimeKey *smime_parse_key(char *buf) { char *pend = NULL, *p = NULL; @@ -687,6 +722,12 @@ static struct SmimeKey *smime_parse_key(char *buf) return key; } +/** + * smime_get_candidates - Find keys matching a string + * @param search String to match + * @param public If true, only get the public keys + * @retval ptr Matching key + */ static struct SmimeKey *smime_get_candidates(char *search, bool public) { char index_file[PATH_MAX]; @@ -749,6 +790,14 @@ static struct SmimeKey *smime_get_key_by_hash(char *hash, bool public) return match; } +/** + * smime_get_key_by_addr - Find an SIME key by address + * @param mailbox Email address to match + * @param abilities Abilities to match, e.g. #KEYFLAG_CANENCRYPT + * @param public If true, only get the public keys + * @param may_ask If true, the user may be asked to select a key + * @retval ptr Matching key + */ static struct SmimeKey *smime_get_key_by_addr(char *mailbox, short abilities, bool public, bool may_ask) { @@ -821,6 +870,13 @@ static struct SmimeKey *smime_get_key_by_addr(char *mailbox, short abilities, return return_key; } +/** + * smime_get_key_by_str - Find an SMIME key by string + * @param str String to match + * @param abilities Abilities to match, e.g. #KEYFLAG_CANENCRYPT + * @param public If true, only get the public keys + * @retval ptr Matching key + */ static struct SmimeKey *smime_get_key_by_str(char *str, short abilities, bool public) { struct SmimeKey *results = NULL, *result = NULL; @@ -860,6 +916,13 @@ static struct SmimeKey *smime_get_key_by_str(char *str, short abilities, bool pu return return_key; } +/** + * smime_ask_for_key - Ask the user to select a key + * @param prompt Prompt to show the user + * @param abilities Abilities to match, e.g. #KEYFLAG_CANENCRYPT + * @param public If true, only get the public keys + * @retval ptr Selected SMIME key + */ static struct SmimeKey *smime_ask_for_key(char *prompt, short abilities, bool public) { struct SmimeKey *key = NULL; @@ -1029,6 +1092,17 @@ char *smime_class_find_keys(struct Address *addrlist, bool oppenc_mode) return keylist; } +/** + * smime_handle_cert_email - Process an email containing certificates + * @param[in] certificate Email with certificates + * @param[in] mailbox Email address + * @param[in] copy If true, save the certificates to buffer + * @param[out] buffer Buffer allocated to hold certificates + * @param[out] num Number of certificates in buffer + * @retval 0 Success + * @retval -1 Error + * @retval -2 Error + */ static int smime_handle_cert_email(char *certificate, char *mailbox, int copy, char ***buffer, int *num) { @@ -1119,6 +1193,11 @@ static int smime_handle_cert_email(char *certificate, char *mailbox, int copy, return rc; } +/** + * smime_extract_certificate - Extract an SMIME certificate from a file + * @param infile File to read + * @retval ptr Filename of temporary file containing certificate + */ static char *smime_extract_certificate(char *infile) { char pk7out[PATH_MAX], certfile[PATH_MAX]; @@ -1221,6 +1300,11 @@ static char *smime_extract_certificate(char *infile) return mutt_str_strdup(certfile); } +/** + * smime_extract_signer_certificate - Extract the signer's certificate + * @param infile File to read + * @retval ptr Name of temporary file containing certificate + */ static char *smime_extract_signer_certificate(char *infile) { char certfile[PATH_MAX]; diff --git a/sort.c b/sort.c index 92b7c60f9..ead1a23ef 100644 --- a/sort.c +++ b/sort.c @@ -45,6 +45,15 @@ bool ReverseAlias; /* function to use as discriminator when normal sort method is equal */ static sort_t *AuxSort = NULL; +/** + * perform_auxsort - Compare two emails using the auxilliary sort method + * @param retval Result of normal sort method + * @param a First email + * @param b Second email + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ int perform_auxsort(int retval, const void *a, const void *b) { /* If the items compared equal by the main sort @@ -62,6 +71,14 @@ int perform_auxsort(int retval, const void *a, const void *b) return retval; } +/** + * compare_score - Compare two emails using their scores + * @param a First email + * @param b Second email + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int compare_score(const void *a, const void *b) { struct Header **pa = (struct Header **) a; @@ -71,6 +88,14 @@ static int compare_score(const void *a, const void *b) return SORTCODE(result); } +/** + * compare_size - Compare the size of two emails + * @param a First email + * @param b Second email + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int compare_size(const void *a, const void *b) { struct Header **pa = (struct Header **) a; @@ -80,6 +105,14 @@ static int compare_size(const void *a, const void *b) return SORTCODE(result); } +/** + * compare_date_sent - Compare the sent date of two emails + * @param a First email + * @param b Second email + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int compare_date_sent(const void *a, const void *b) { struct Header **pa = (struct Header **) a; @@ -89,6 +122,14 @@ static int compare_date_sent(const void *a, const void *b) return SORTCODE(result); } +/** + * compare_subject - Compare the subject of two emails + * @param a First email + * @param b Second email + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int compare_subject(const void *a, const void *b) { struct Header **pa = (struct Header **) a; @@ -110,6 +151,16 @@ static int compare_subject(const void *a, const void *b) return SORTCODE(rc); } +/** + * mutt_get_name - Pick the best name to display from an address + * @param a Address to use + * @retval ptr Display name + * + * This function uses: + * 1. Alias for email address + * 2. Personal name + * 3. Email address + */ const char *mutt_get_name(struct Address *a) { struct Address *ali = NULL; @@ -127,6 +178,14 @@ const char *mutt_get_name(struct Address *a) return ""; } +/** + * compare_to - Compare the 'to' fields of two emails + * @param a First email + * @param b Second email + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int compare_to(const void *a, const void *b) { struct Header **ppa = (struct Header **) a; @@ -140,6 +199,14 @@ static int compare_to(const void *a, const void *b) return SORTCODE(result); } +/** + * compare_from - Compare the 'from' fields of two emails + * @param a First email + * @param b Second email + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int compare_from(const void *a, const void *b) { struct Header **ppa = (struct Header **) a; @@ -153,6 +220,14 @@ static int compare_from(const void *a, const void *b) return SORTCODE(result); } +/** + * compare_date_received - Compare the date received of two emails + * @param a First email + * @param b Second email + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int compare_date_received(const void *a, const void *b) { struct Header **pa = (struct Header **) a; @@ -162,6 +237,14 @@ static int compare_date_received(const void *a, const void *b) return SORTCODE(result); } +/** + * compare_order - Restore the 'unsorted' order of emails + * @param a First email + * @param b Second email + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int compare_order(const void *a, const void *b) { struct Header **ha = (struct Header **) a; @@ -171,6 +254,14 @@ static int compare_order(const void *a, const void *b) return SORTCODE((*ha)->index - (*hb)->index); } +/** + * compare_spam - Compare the spam values of two emails + * @param a First email + * @param b Second email + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int compare_spam(const void *a, const void *b) { struct Header **ppa = (struct Header **) a; @@ -227,6 +318,14 @@ static int compare_spam(const void *a, const void *b) return SORTCODE(result); } +/** + * compare_label - Compare the labels of two emails + * @param a First email + * @param b Second email + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a + */ static int compare_label(const void *a, const void *b) { struct Header **ppa = (struct Header **) a; @@ -257,6 +356,11 @@ static int compare_label(const void *a, const void *b) return SORTCODE(result); } +/** + * mutt_get_sort_func - Get the sort function for a given sort id + * @param method Sort id, e.g. #SORT_DATE + * @retval ptr qsort-compatible sort function + */ sort_t *mutt_get_sort_func(int method) { switch (method & SORT_MASK) @@ -292,6 +396,11 @@ sort_t *mutt_get_sort_func(int method) /* not reached */ } +/** + * mutt_sort_headers - Sort emails by their headers + * @param ctx Mailbox + * @param init If true, rebuild the thread + */ void mutt_sort_headers(struct Context *ctx, int init) { struct Header *h = NULL;