From: Richard Russon Date: Sun, 15 Jul 2018 22:33:48 +0000 (+0100) Subject: doxygen: lots of docs X-Git-Tag: 2019-10-25~753 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=25bff4295d461623ae10566128c27ccc30c1b870;p=neomutt doxygen: lots of docs --- diff --git a/bcache.c b/bcache.c index 33f07636c..33088dde1 100644 --- a/bcache.c +++ b/bcache.c @@ -67,8 +67,7 @@ static int bcache_path(struct Account *account, const char *mailbox, char *dst, /* make up a Url we can turn into a string */ mutt_account_tourl(account, &url); - /* - * mutt_account_tourl() just sets up some pointers; + /* mutt_account_tourl() just sets up some pointers; * if this ever changes, we have a memleak here */ url.path = NULL; diff --git a/browser.c b/browser.c index 05fc85de1..5fb15a774 100644 --- a/browser.c +++ b/browser.c @@ -112,6 +112,7 @@ static char LastDir[PATH_MAX] = ""; /** * destroy_state - Free the BrowserState + * @param state State to free * * Frees up the memory allocated for the local-global variables. */ @@ -204,6 +205,11 @@ static int browser_compare_count_new(const void *a, const void *b) /** * browser_compare - Sort the items in the browser + * @param a First item + * @param b Second item + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a * * Wild compare function that calls the others. It's useful because it provides * a way to tell "../" is always on the top of the list, independently of the @@ -239,6 +245,7 @@ static int browser_compare(const void *a, const void *b) /** * browser_sort - Sort the entries in the browser + * @param state Browser state * * Call to qsort using browser_compare function. * Some specific sort methods are not used via NNTP. @@ -724,7 +731,13 @@ static void init_state(struct BrowserState *state, struct Menu *menu) } /** - * examine_directory - get list of all files/newsgroups with mask + * examine_directory - Get list of all files/newsgroups with mask + * @param menu Current Menu + * @param state State of browser + * @param d Directory + * @param prefix Files/newsgroups must match this prefix + * @retval 0 Success + * @retval -1 Error */ static int examine_directory(struct Menu *menu, struct BrowserState *state, char *d, const char *prefix) @@ -863,6 +876,10 @@ static int examine_vfolders(struct Menu *menu, struct BrowserState *state) /** * examine_mailboxes - Get list of mailboxes/subscribed newsgroups + * @param menu Current menu + * @param state State of browser + * @retval 0 Success + * @retval -1 Error */ static int examine_mailboxes(struct Menu *menu, struct BrowserState *state) { @@ -1026,6 +1043,8 @@ static void vfolder_entry(char *buf, size_t buflen, struct Menu *menu, int num) /** * browser_highlight_default - Decide which browser item should be highlighted + * @param state Browser state + * @param menu Current Menu * * This function takes a menu and a state and defines the current entry that * should be highlighted. @@ -1154,6 +1173,7 @@ static int file_tag(struct Menu *menu, int n, int m) /** * mutt_browser_select_dir - Remember the last directory selected + * @param f Directory name to save * * This function helps the browser to know which directory has been selected. * It should be called anywhere a confirm hit is done to open a new diff --git a/color.c b/color.c index 6c5e4f22b..f2564af49 100644 --- a/color.c +++ b/color.c @@ -493,6 +493,13 @@ static void do_uncolor(struct Buffer *buf, struct Buffer *s, /** * parse_uncolor - Parse an 'uncolor' command + * @param buf Temporary Buffer space + * @param s Buffer containing string to be parsed + * @param data Flags associated with the command + * @param err Buffer for error messages + * @param parse_uncolor If true, 'uncolor', else 'unmono' + * @retval 0 Success + * @retval -1 Error * * usage: * * uncolor index pattern [pattern...] @@ -853,6 +860,14 @@ static int fgbgattr_to_color(int fg, int bg, int attr) /** * parse_color - Parse a "color" command + * @param buf Temporary Buffer space + * @param s Buffer containing string to be parsed + * @param err Buffer for error messages + * @param callback Function to handle command + * @param dry_run If true, test the command, but don't apply it + * @param color If true "color", else "mono" + * @retval 0 Success + * @retval -1 Error * * usage: color OBJECT FG BG [ REGEX ] * mono OBJECT ATTR [ REGEX ] diff --git a/commands.c b/commands.c index da36b7730..2a4fad73f 100644 --- a/commands.c +++ b/commands.c @@ -407,6 +407,14 @@ static void pipe_msg(struct Header *h, FILE *fp, int decode, int print) /** * pipe_message - Pipe message to a command + * @param h Header of email + * @param cmd Command to pipe to + * @param decode Should the message be decrypted + * @param print True if this is a print job + * @param split Should a separator be send between messages? + * @param sep Separator string + * @retval 0 Success + * @retval 1 Error * * The following code is shared between printing and piping. */ @@ -712,8 +720,7 @@ void mutt_display_address(struct Envelope *env) if (!addr) return; - /* - * Note: We don't convert IDNA to local representation this time. + /* Note: We don't convert IDNA to local representation this time. * That is intentional, so the user has an opportunity to copy & * paste the on-the-wire form of the address to other, IDN-unable * software. @@ -796,6 +803,10 @@ int mutt_save_message_ctx(struct Header *h, int delete, int decode, int decrypt, /** * mutt_save_message - Save an email + * @param h Header of email + * @param delete If true, delete the original (save) + * @param decode If true, decode the message + * @param decrypt If true, decrypt the message * @retval 0 Copy/save was successful * @retval -1 Error/abort */ @@ -1004,11 +1015,15 @@ void mutt_version(void) mutt_message("NeoMutt %s%s", PACKAGE_VERSION, GitVer); } -/* - * Returns: - * 1 when a structural change is made. - * recvattach requires this to know when to regenerate the actx. - * 0 otherwise. +/** + * mutt_edit_content_type - Edit the content type of an attachment + * @param h Header of email + * @param b Attachment + * @param fp File handle to the attachment + * @retval 1 A structural change is made + * @retval 0 Otherwise + * + * recvattach requires the return code to know when to regenerate the actx. */ int mutt_edit_content_type(struct Header *h, struct Body *b, FILE *fp) { diff --git a/complete.c b/complete.c index 487229b63..20118836e 100644 --- a/complete.c +++ b/complete.c @@ -208,8 +208,7 @@ int mutt_complete(char *buf, size_t buflen) return -1; } - /* - * special case to handle when there is no filepart yet. find the first + /* special case to handle when there is no filepart yet. find the first * file/directory which is not ``.'' or ``..'' */ len = mutt_str_strlen(filepart); diff --git a/compose.c b/compose.c index 500e9c6d5..a934a71e2 100644 --- a/compose.c +++ b/compose.c @@ -1654,10 +1654,9 @@ int mutt_compose_menu(struct Header *msg, char *fcc, size_t fcclen, ret = mutt_get_field(_("Send attachment with name: "), fname, sizeof(fname), MUTT_FILE); if (ret == 0) { - /* - * As opposed to RENAME_FILE, we don't check fname[0] because it's - * valid to set an empty string here, to erase what was set - */ + /* As opposed to RENAME_FILE, we don't check fname[0] because it's + * valid to set an empty string here, to erase what was set + */ mutt_str_replace(&CURATTACH->content->d_filename, fname); menu->redraw = REDRAW_CURRENT; } diff --git a/conn/socket.c b/conn/socket.c index d7cf66a18..b6f81d7a3 100644 --- a/conn/socket.c +++ b/conn/socket.c @@ -328,6 +328,7 @@ struct Connection *mutt_socket_new(enum ConnectionType type) /** * mutt_socket_free - remove connection from connection list and free it + * @param conn Connection to free */ void mutt_socket_free(struct Connection *conn) { diff --git a/copy.c b/copy.c index 8e5bd9e93..5bfb462be 100644 --- a/copy.c +++ b/copy.c @@ -652,10 +652,7 @@ int mutt_copy_message_fp(FILE *fpout, FILE *fpin, struct Header *hdr, int flags, /* update the total size of the mailbox to reflect this deletion */ Context->size -= body->length - new_length; - /* - * if the message is visible, update the visible size of the mailbox - * as well. - */ + /* if the message is visible, update the visible size of the mailbox as well. */ if (Context->v2r[hdr->msgno] != -1) Context->vsize -= body->length - new_length; diff --git a/curs_lib.c b/curs_lib.c index a8062d2f7..e3b47ab5a 100644 --- a/curs_lib.c +++ b/curs_lib.c @@ -248,8 +248,7 @@ int mutt_yesorno(const char *msg, int def) reno_ok = (expr = nl_langinfo(NOEXPR)) && (expr[0] == '^') && (REGCOMP(&reno, expr, REG_NOSUB) == 0); - /* - * In order to prevent the default answer to the question to wrapped + /* In order to prevent the default answer to the question to wrapped * around the screen in the even the question is wider than the screen, * ensure there is enough room for the answer and truncate the question * to fit. @@ -545,6 +544,8 @@ void mutt_unget_string(char *s) /** * mutt_push_macro_event - Add the character/operation to the macro buffer + * @param ch Character to add + * @param op Operation to add * * Adds the ch/op to the macro buffer. * This should be used for macros, push, and exec commands only. @@ -701,6 +702,9 @@ int mutt_multi_choice(char *prompt, char *letters) /** * mutt_addwch - addwch would be provided by an up-to-date curses library + * @param wc Wide char to display + * @retval 0 Success + * @retval -1 Error */ int mutt_addwch(wchar_t wc) { diff --git a/curs_main.c b/curs_main.c index 68fb5c68f..c3353821d 100644 --- a/curs_main.c +++ b/curs_main.c @@ -247,6 +247,7 @@ static int ci_previous_undeleted(int msgno) /** * ci_first_message - Get index of first new message + * @retval num Index of first new message * * Return the index of the first new message, or failing that, the first * unread message. @@ -289,6 +290,9 @@ static int ci_first_message(void) /** * mx_toggle_write - Toggle the mailbox's readonly flag + * @param ctx Mailbox + * @retval 0 Success + * @retval -1 Error * * This should be in mx.c, but it only gets used here. */ @@ -841,6 +845,7 @@ static void index_menu_redraw(struct Menu *menu) /** * mutt_index_menu - Display a list of emails + * @retval num How the menu was finished, e.g. OP_QUIT, OP_EXIT * * This function handles the message index window as well as commands returned * from the pager (MENU_PAGER). @@ -1049,8 +1054,7 @@ int mutt_index_menu(void) mutt_resize_screen(); SigWinch = 0; menu->top = 0; /* so we scroll the right amount */ - /* - * force a real complete redraw. clrtobot() doesn't seem to be able + /* force a real complete redraw. clrtobot() doesn't seem to be able * to handle every case without this. */ clearok(stdscr, true); @@ -1741,9 +1745,7 @@ int mutt_index_menu(void) else if (check == MUTT_NEW_MAIL || check == MUTT_REOPENED) update_index(menu, Context, check, oc, index_hint); - /* - * do a sanity check even if mx_mbox_sync failed. - */ + /* do a sanity check even if mx_mbox_sync failed. */ if (menu->current < 0 || menu->current >= Context->vcount) menu->current = ci_first_message(); @@ -2126,8 +2128,7 @@ int mutt_index_menu(void) CHECK_MSGCOUNT; CHECK_VISIBLE; - /* - * toggle the weeding of headers so that a user can press the key + /* toggle the weeding of headers so that a user can press the key * again while reading the message. */ if (op == OP_DISPLAY_HEADERS) diff --git a/edit.c b/edit.c index ffade7c81..29db5922f 100644 --- a/edit.c +++ b/edit.c @@ -46,8 +46,7 @@ /* These Config Variables are only used in edit.c */ char *Escape; -/* - * SLcurses_waddnstr() can't take a "const char *", so this is only +/* SLcurses_waddnstr() can't take a "const char *", so this is only * declared "static" (sigh) */ static char *EditorHelp1 = diff --git a/email/from.c b/email/from.c index f20e8f936..0f7686636 100644 --- a/email/from.c +++ b/email/from.c @@ -179,8 +179,7 @@ bool is_from(const char *s, char *path, size_t pathlen, time_t *tp) if (!*s) return false; - /* - * some places have two timezone fields after the time, e.g. + /* some places have two timezone fields after the time, e.g. * From xxxx@yyyyyyy.fr Wed Aug 2 00:39:12 MET DST 1995 */ if (isalpha((unsigned char) *s)) diff --git a/email/url.h b/email/url.h index 1c7ec4eea..0615f08a7 100644 --- a/email/url.h +++ b/email/url.h @@ -52,7 +52,6 @@ enum UrlScheme * struct UrlQueryString - Parsed Query String * * The arguments in a URL are saved in a linked list. - * */ struct UrlQueryString { diff --git a/flags.c b/flags.c index 4852bf5ce..88ed13012 100644 --- a/flags.c +++ b/flags.c @@ -107,8 +107,7 @@ void mutt_set_flag_update(struct Context *ctx, struct Header *h, int flag, bool ctx->changed = true; } #endif - /* - * If the user undeletes a message which is marked as + /* If the user undeletes a message which is marked as * "trash" in the maildir folder on disk, the folder has * been changed, and is marked accordingly. However, we do * _not_ mark the message itself changed, because trashing diff --git a/hdrline.c b/hdrline.c index e08364159..d36340a36 100644 --- a/hdrline.c +++ b/hdrline.c @@ -115,9 +115,12 @@ static bool check_for_mailing_list(struct Address *addr, const char *pfx, char * /** * check_for_mailing_list_addr - Check an address list for a mailing list + * @param addr Address list + * @param buf Buffer for the result + * @param buflen Length of buffer + * @retval true Mailing list found * - * If one is found, print the address of the list into buf, then return 1. - * Otherwise, simply return 0. + * If one is found, print the address of the list into buf. */ static bool check_for_mailing_list_addr(struct Address *addr, char *buf, int buflen) { @@ -342,6 +345,7 @@ static bool user_in_addr(struct Address *a) /** * user_is_recipient - Is the user a recipient of the message + * @param h Header of email to test * @retval 0 User is not in list * @retval 1 User is unique recipient * @retval 2 User is in the TO list diff --git a/imap/message.c b/imap/message.c index f81083d78..f5ad9f079 100644 --- a/imap/message.c +++ b/imap/message.c @@ -1200,6 +1200,9 @@ bail: /** * imap_msg_close - Close an email + * @param ctx Mailbox + * @param msg Message to close + * @retval 0 Success * * @note May also return EOF Failure, see errno */ diff --git a/imap/utf7.c b/imap/utf7.c index cb5f04e79..93786f57b 100644 --- a/imap/utf7.c +++ b/imap/utf7.c @@ -196,8 +196,7 @@ static char *utf8_to_utf7(const char *u8, size_t u8len, char **u7, size_t *u7len int n, b = 0, k = 0; bool base64 = false; - /* - * In the worst case we convert 2 chars to 7 chars. For example: + /* In the worst case we convert 2 chars to 7 chars. For example: * "\x10&\x10&..." -> "&ABA-&-&ABA-&-...". */ char *buf = mutt_mem_malloc((u8len / 2) * 7 + 6); diff --git a/init.c b/init.c index f16accd7c..d344561c6 100644 --- a/init.c +++ b/init.c @@ -1945,9 +1945,7 @@ static int parse_path_unlist(struct Buffer *buf, struct Buffer *s, do { mutt_extract_token(buf, s, 0); - /* - * Check for deletion of entire list - */ + /* Check for deletion of entire list */ if (mutt_str_strcmp(buf->data, "*") == 0) { mutt_list_free((struct ListHead *) data); @@ -3272,9 +3270,7 @@ static int parse_unstailq(struct Buffer *buf, struct Buffer *s, do { mutt_extract_token(buf, s, 0); - /* - * Check for deletion of entire list - */ + /* Check for deletion of entire list */ if (mutt_str_strcmp(buf->data, "*") == 0) { mutt_list_free((struct ListHead *) data); diff --git a/mbox/mbox.c b/mbox/mbox.c index 3f925c844..4e09d0e04 100644 --- a/mbox/mbox.c +++ b/mbox/mbox.c @@ -261,6 +261,10 @@ static int mmdf_parse_mailbox(struct Context *ctx) /** * mbox_parse_mailbox - Read a mailbox from disk + * @param ctx Mailbox + * @retval 0 Success + * @retval -1 Error + * @retval -2 Aborted * * Note that this function is also called when new mail is appended to the * currently open folder, and NOT just when the mailbox is initially read. @@ -355,8 +359,7 @@ static int mbox_parse_mailbox(struct Context *ctx) if ((tmploc > 0) && (tmploc < ctx->size)) { - /* - * check to see if the content-length looks valid. we expect to + /* check to see if the content-length looks valid. we expect to * to see a valid message separator at this point in the stream */ if (fseeko(ctx->fp, tmploc, SEEK_SET) != 0 || @@ -426,8 +429,7 @@ static int mbox_parse_mailbox(struct Context *ctx) loc = ftello(ctx->fp); } - /* - * Only set the content-length of the previous message if we have read more + /* Only set the content-length of the previous message if we have read more * than one message during _this_ invocation. If this routine is called * when new mail is received, we need to make sure not to clobber what * previously was the last message since the headers may be sorted. @@ -832,8 +834,7 @@ static int mbox_mbox_check(struct Context *ctx, int *index_hint) unlock = 1; } - /* - * Check to make sure that the only change to the mailbox is that + /* Check to make sure that the only change to the mailbox is that * message(s) were appended to this file. My heuristic is that we should * see the message separator at *exactly* what used to be the end of the * folder. @@ -917,6 +918,8 @@ static bool mbox_has_new(struct Context *ctx) /** * mbox_reset_atime - Reset the access time on the mailbox file + * @param ctx Mailbox + * @param st Timestamp * * if mailbox has at least 1 new message, sets mtime > atime of mailbox so * buffy check reports new mail @@ -936,8 +939,7 @@ void mbox_reset_atime(struct Context *ctx, struct stat *st) utimebuf.actime = st->st_atime; utimebuf.modtime = st->st_mtime; - /* - * When $mbox_check_recent is set, existing new mail is ignored, so do not + /* When $mbox_check_recent is set, existing new mail is ignored, so do not * reset the atime to mtime-1 to signal new mail. */ if (!MailCheckRecent && utimebuf.actime >= utimebuf.modtime && mbox_has_new(ctx)) @@ -1073,8 +1075,7 @@ static int mbox_mbox_sync(struct Context *ctx, int *index_hint) { if (!ctx->quiet) mutt_progress_update(&progress, i, (int) (ftello(ctx->fp) / (ctx->size / 100 + 1))); - /* - * back up some information which is needed to restore offsets when + /* back up some information which is needed to restore offsets when * something fails. */ diff --git a/menu.c b/menu.c index d9f4d2994..adfb344be 100644 --- a/menu.c +++ b/menu.c @@ -1116,7 +1116,7 @@ void mutt_menu_set_redraw_full(int menu_type) /** * mutt_menu_current_redraw - Redraw the current menu */ -void mutt_menu_current_redraw() +void mutt_menu_current_redraw(void) { struct Menu *current_menu = get_current_menu(); if (current_menu) diff --git a/mutt_attach.c b/mutt_attach.c index 2915da0f5..60d540ec7 100644 --- a/mutt_attach.c +++ b/mutt_attach.c @@ -51,6 +51,12 @@ #include "sendlib.h" #include "state.h" +/** + * mutt_get_tmp_attachment - Get a temporary copy of an attachment + * @param a Attachment to copy + * @retval 0 Success + * @retval -1 Error + */ int mutt_get_tmp_attachment(struct Body *a) { char type[STRING]; @@ -93,6 +99,7 @@ int mutt_get_tmp_attachment(struct Body *a) /** * mutt_compose_attachment - Create an attachment + * @param a Body of email * @retval 1 if require full screen redraw * @retval 0 otherwise */ @@ -587,7 +594,7 @@ int mutt_view_attachment(FILE *fp, struct Body *a, int flag, struct Header *hdr, { /* Use built-in handler */ OptViewAttach = true; /* disable the "use 'v' to view this part" - * message in case of error */ + * message in case of error */ if (mutt_decode_save_attachment(fp, a, pagerfile, MUTT_DISPLAY, 0)) { OptViewAttach = false; @@ -644,6 +651,10 @@ return_error: /** * mutt_pipe_attachment - Pipe an attachment to a command + * @param fp File to pipe into the command + * @param b Attachment + * @param path Path to command + * @param outfile File to save output to * @retval 1 Success * @retval 0 Error */ @@ -731,9 +742,7 @@ bail: if (outfile && *outfile) close(out); - /* - * check for error exit from child process - */ + /* check for error exit from child process */ if (mutt_wait_filter(thepid) != 0) rc = 0; @@ -742,6 +751,12 @@ bail: return rc; } +/** + * save_attachment_open - Open a file to write an attachment to + * @param path Path to file to open + * @param flags Flags, e.g. #MUTT_SAVE_APPEND + * @retval ptr File handle to attachment file + */ static FILE *save_attachment_open(char *path, int flags) { if (flags == MUTT_SAVE_APPEND) @@ -879,6 +894,11 @@ int mutt_save_attachment(FILE *fp, struct Body *m, char *path, int flags, struct /** * mutt_decode_save_attachment - Decode, then save an attachment + * @param fp File to read from (OPTIONAL) + * @param m Attachment + * @param path Path to save the Attachment to + * @param displaying Flags, e.g. #MUTT_DISPLAY + * @param flags Flags, e.g. #MUTT_SAVE_APPEND * @retval 0 Success * @retval -1 Error */ @@ -969,6 +989,10 @@ int mutt_decode_save_attachment(FILE *fp, struct Body *m, char *path, int displa /** * mutt_print_attachment - Print out an attachment + * @param fp File to write to + * @param a Attachment + * @retval 1 Success + * @retval 0 Error * * Ok, the difference between send and receive: * recv: Body->filename is a suggested name, and Context|Header points diff --git a/mutt_body.c b/mutt_body.c index 0ca37d02f..0933931e1 100644 --- a/mutt_body.c +++ b/mutt_body.c @@ -89,9 +89,8 @@ int mutt_body_copy(FILE *fp, struct Body **tgt, struct Body *src) b->d_filename = mutt_str_strdup(src->filename); b->description = mutt_str_strdup(b->description); - /* - * we don't seem to need the Header structure currently. - * XXX - this may change in the future + /* we don't seem to need the Header structure currently. + * XXX this may change in the future */ if (b->hdr) diff --git a/mutt_header.c b/mutt_header.c index 20d097842..d893aacf9 100644 --- a/mutt_header.c +++ b/mutt_header.c @@ -77,6 +77,10 @@ static void label_ref_inc(struct Context *ctx, char *label) /** * label_message - add an X-Label: field + * @param[in] ctx Mailbox + * @param[in] hdr Header of email + * @param[out] new Set to true if this is a new label + * @retval true If the label was added */ static bool label_message(struct Context *ctx, struct Header *hdr, char *new) { diff --git a/mutt_parse.c b/mutt_parse.c index 3301e63b7..186a04103 100644 --- a/mutt_parse.c +++ b/mutt_parse.c @@ -36,6 +36,11 @@ struct Context; #define MUTT_PARTS_TOPLEVEL (1 << 0) /* is the top-level part */ +/** + * mutt_parse_mime_message - Parse a MIME email + * @param ctx Mailbox + * @param cur Header of email + */ void mutt_parse_mime_message(struct Context *ctx, struct Header *cur) { struct Message *msg = NULL; @@ -101,6 +106,12 @@ static bool count_body_parts_check(struct ListHead *checklist, struct Body *b, b return false; } +/** + * count_body_parts - Count the MIME Body parts + * @param body Body of email + * @param flags Flags, e.g. #MUTT_PARTS_TOPLEVEL + * @retval num Number of MIME Body parts + */ static int count_body_parts(struct Body *body, int flags) { int count = 0; @@ -194,6 +205,12 @@ static int count_body_parts(struct Body *body, int flags) return (count < 0) ? 0 : count; } +/** + * mutt_count_body_parts - Count the MIME Body parts + * @param ctx Mailbox + * @param hdr Header of email + * @retval num Number of MIME Body parts + */ int mutt_count_body_parts(struct Context *ctx, struct Header *hdr) { bool keep_parts = false; diff --git a/mutt_thread.c b/mutt_thread.c index 68eaaec8b..720e01f13 100644 --- a/mutt_thread.c +++ b/mutt_thread.c @@ -54,6 +54,9 @@ static bool is_visible(struct Header *hdr, struct Context *ctx) /** * need_display_subject - Determines whether to display a message's subject + * @param ctx Mailbox + * @param hdr Header of email + * @retval true If the subject should be displayed */ static int need_display_subject(struct Context *ctx, struct Header *hdr) { @@ -132,6 +135,8 @@ static void linearize_tree(struct Context *ctx) /** * calculate_visibility - Are tree nodes visible + * @param ctx Mailbox + * @param max_depth Maximum depth to check * * this calculates whether a node is the root of a subtree that has visible * nodes, whether a node itself is visible, whether, if invisible, it has @@ -244,6 +249,7 @@ static void calculate_visibility(struct Context *ctx, int *max_depth) /** * mutt_draw_tree - Draw a tree of threaded emails + * @param ctx Mailbox * * Since the graphics characters have a value >255, I have to resort to using * escape sequences to pass the information to print_enriched_string(). These @@ -480,6 +486,7 @@ static struct Hash *make_subj_hash(struct Context *ctx) /** * pseudo_threads - Thread messages by subject + * @param ctx Mailbox * * Thread by subject things that didn't get threaded by message-id */ @@ -1268,6 +1275,10 @@ int mutt_traverse_thread(struct Context *ctx, struct Header *cur, int flag) /** * mutt_messages_in_thread - Count the messages in a thread + * @param ctx Mailbox + * @param hdr Header of email + * @param flag Flag, see notes below + * @retval num Number of message / Our position * * If flag is 0, we want to know how many messages are in the thread. * If flag is 1, we want to know our position in the thread. diff --git a/mutt_url.c b/mutt_url.c index 4d53f9253..8ab2368e8 100644 --- a/mutt_url.c +++ b/mutt_url.c @@ -30,6 +30,14 @@ #include "mutt.h" #include "globals.h" +/** + * url_parse_mailto - Parse a mailto:// url + * @param[in] e Envelope to fill + * @param[out] body Body to + * @param[in] src String to parse + * @retval 0 Success + * @retval -1 Error + */ int url_parse_mailto(struct Envelope *e, char **body, const char *src) { char *p = NULL; diff --git a/muttlib.c b/muttlib.c index b7504dc79..84d07cc72 100644 --- a/muttlib.c +++ b/muttlib.c @@ -73,6 +73,8 @@ static const char *xdg_defaults[] = { /** * mutt_adv_mktemp - Advanced mktemp(3) + * @param s Buffer for result + * @param l Length of buffer * * Modified by blong to accept a "suggestion" for file name. If that file * exists, then construct one with unique name but keep any extension. This @@ -285,6 +287,10 @@ char *mutt_expand_path_regex(char *s, size_t slen, bool regex) /** * mutt_gecos_name - Lookup a user's real name in /etc/passwd + * @param dest Buffer for the result + * @param destlen Length of buffer + * @param pw Passwd entry + * @retval ptr Result buffer on success * * Extract the real name from /etc/passwd's GECOS field. When set, honor the * regular expression in GecosMask, otherwise assume that the GECOS field is a @@ -479,6 +485,8 @@ void mutt_mktemp_full(char *s, size_t slen, const char *prefix, /** * mutt_pretty_mailbox - Shorten a mailbox path using '~' or '=' + * @param s Buffer containing string to shorten + * @param buflen Length of buffer * * Collapse the pathname using ~ or = when possible */ @@ -614,6 +622,12 @@ void mutt_expand_fmt(char *dest, size_t destlen, const char *fmt, const char *sr /** * mutt_check_overwrite - Ask the user if overwriting is necessary + * @param[in] attname Attachment name + * @param[in] path Path to save the file + * @param[out] fname Buffer for filename + * @param[out] flen Length of buffer + * @param[out] append Flags set to #MUTT_SAVE_APPEND or #MUTT_SAVE_OVERWRITE + * @param[out] directory Directory to save under (OPTIONAL) * @retval 0 Success * @retval -1 Abort * @retval 1 Error @@ -1240,6 +1254,9 @@ void mutt_expando_format(char *buf, size_t buflen, size_t col, int cols, const c /** * mutt_open_read - Run a command to read from + * @param[in] path Path to command + * @param[out] thepid PID of the command + * @retval ptr File containing output of command * * This function allows the user to specify a command to read stdout from in * place of a normal file. If the last character in the string is a pipe (|), @@ -1284,6 +1301,8 @@ FILE *mutt_open_read(const char *path, pid_t *thepid) /** * mutt_save_confirm - Ask the user to save + * @param s Save location + * @param st Timestamp * @retval 0 if OK to proceed * @retval -1 to abort * @retval 1 to retry diff --git a/mx.c b/mx.c index 1690663bd..0a9ac28be 100644 --- a/mx.c +++ b/mx.c @@ -793,8 +793,7 @@ int mx_mbox_close(struct Context *ctx, int *index_hint) } } - /* - * There is no point in asking whether or not to purge if we are + /* There is no point in asking whether or not to purge if we are * just marking messages as "trash". */ if (ctx->deleted && !(ctx->magic == MUTT_MAILDIR && MaildirTrash)) diff --git a/ncrypt/crypt.c b/ncrypt/crypt.c index faba921de..46d5e0c9e 100644 --- a/ncrypt/crypt.c +++ b/ncrypt/crypt.c @@ -69,6 +69,8 @@ bool SmimeSelfEncrypt; /** * crypt_current_time - Print the current time + * @param s State to use + * @param app_name App name, e.g. "PGP" * * print the current time to avoid spoofing of the signature output */ @@ -130,6 +132,9 @@ static void disable_coredumps(void) /** * crypt_valid_passphrase - Check that we have a usable passphrase, ask if not + * @param flags Flags, e.g. #APPLICATION_PGP + * @retval 0 Success + * @retval -1 Failure */ int crypt_valid_passphrase(int flags) { @@ -411,6 +416,9 @@ int mutt_is_valid_multipart_pgp_encrypted(struct Body *b) /** * mutt_is_malformed_multipart_pgp_encrypted - Check for malformed layout + * @param b Body of email + * @retval PGPENCRYPT Success + * @retval 0 Error * * This checks for the malformed layout caused by MS Exchange in * some cases: @@ -586,6 +594,9 @@ int mutt_is_application_smime(struct Body *m) /** * crypt_query - Check out the type of encryption used + * @param m Body of email + * @retval num Flags, e.g. #GOODSIGN + * @retval 0 Error * * Set the cached status values if there are any. */ @@ -652,6 +663,11 @@ int crypt_query(struct Body *m) /** * crypt_write_signed - Write the message body/part + * @param a Body to write + * @param s State to use + * @param tempfile File to write to + * @retval 0 Success + * @retval -1 Error * * Body/part A described by state S to the given TEMPFILE. */ @@ -862,6 +878,11 @@ void crypt_extract_keys_from_messages(struct Header *h) /** * crypt_get_keys - Check we have all the keys we need + * @param[in] msg Message with addresses to match + * @param[out] keylist Keys needed + * @param[in] oppenc_mode If true, use opportunistic encryption + * @retval 0 Success + * @retval -1 Error * * Do a quick check to make sure that we can find all of the * encryption keys if the user has requested this service. @@ -936,6 +957,7 @@ int crypt_get_keys(struct Header *msg, char **keylist, bool oppenc_mode) /** * crypt_opportunistic_encrypt - Can all recipients be determined + * @param msg Header of email * * Check if all recipients keys can be automatically determined. * Enable encryption if they can, otherwise disable encryption. @@ -983,6 +1005,10 @@ static void crypt_fetch_signatures(struct Body ***signatures, struct Body *a, in /** * mutt_signed_handler - Verify a "multipart/signed" body + * @param a Body to verify + * @param s State to use + * @retval 0 Success + * @retval -1 Error */ int mutt_signed_handler(struct Body *a, struct State *s) { @@ -1207,6 +1233,8 @@ const char *crypt_get_fingerprint_or_id(char *p, const char **pphint, /** * crypt_is_numerical_keyid - Is this a numerical keyid + * @param s Key to test + * @retval true If keyid is numeric * * Check if a crypt-hook value is a key id. */ diff --git a/ncrypt/crypt_gpgme.c b/ncrypt/crypt_gpgme.c index c2f868e9b..dfeea3599 100644 --- a/ncrypt/crypt_gpgme.c +++ b/ncrypt/crypt_gpgme.c @@ -131,10 +131,6 @@ static struct CryptCache *id_defaults = NULL; static gpgme_key_t signature_key = NULL; static char *current_sender = NULL; -/* - * General helper functions. - */ - #define PKA_NOTATION_NAME "pka-address@gnupg.org" static bool is_pka_notation(gpgme_sig_notation_t notation) @@ -144,6 +140,7 @@ static bool is_pka_notation(gpgme_sig_notation_t notation) /** * redraw_if_needed - accommodate for a redraw if needed + * @param ctx GPGME handle */ static void redraw_if_needed(gpgme_ctx_t ctx) { @@ -173,9 +170,11 @@ static int digit_or_letter(const unsigned char *s) /** * print_utf8 - Write a UTF-8 string to a file + * @param fp File to write to + * @param buf Buffer to read from + * @param len Length to read * - * Print the utf-8 encoded string BUF of length LEN bytes to stream FP. Convert - * the character set. + * Convert the character set. */ static void print_utf8(FILE *fp, const char *buf, size_t len) { @@ -197,6 +196,8 @@ static void print_utf8(FILE *fp, const char *buf, size_t len) /** * crypt_keyid - Find the ID for the key + * @param k Key to use + * @retval ptr ID string for the key * * Return the keyID for the key K. * Note that this string is valid as long as K is valid @@ -220,6 +221,8 @@ static const char *crypt_keyid(struct CryptKeyInfo *k) /** * crypt_long_keyid - Find the Long ID for the key + * @param k Key to use + * @retval ptr Long ID string for the key * * Return the long keyID for the key K. */ @@ -236,7 +239,9 @@ static const char *crypt_long_keyid(struct CryptKeyInfo *k) } /** - * crypt_short_keyid - Get the short keyID for the key K + * crypt_short_keyid - Get the short keyID for a key + * @param k Key to use + * @retval ptr Short key string */ static const char *crypt_short_keyid(struct CryptKeyInfo *k) { @@ -253,7 +258,9 @@ static const char *crypt_short_keyid(struct CryptKeyInfo *k) } /** - * crypt_fpr - Get the hexstring fingerprint from the key K + * crypt_fpr - Get the hexstring fingerprint from a key + * @param k Key to use + * @retval ptr Hexstring fingerprint */ static const char *crypt_fpr(struct CryptKeyInfo *k) { @@ -288,6 +295,8 @@ static const char *crypt_fpr_or_lkeyid(struct CryptKeyInfo *k) /** * crypt_key_abilities - Parse key flags into a string + * @param flags Flags, e.g. #KEYFLAG_CANENCRYPT + * @retval ptr Flag string * * Note: The string is statically allocated. */ @@ -316,6 +325,8 @@ static char *crypt_key_abilities(int flags) /** * crypt_flags - Parse the key flags into a single character + * @param flags Flags, e.g. #KEYFLAG_EXPIRED + * @retval char Flag character * * The returned character describes the most important flag. */ @@ -335,6 +346,8 @@ static char crypt_flags(int flags) /** * crypt_copy_key - Return a copy of KEY + * @param key Key to copy + * @retval ptr Copy of key */ static struct CryptKeyInfo *crypt_copy_key(struct CryptKeyInfo *key) { @@ -374,7 +387,8 @@ static void crypt_free_key(struct CryptKeyInfo **keylist) /** * crypt_key_is_valid - Is the key valid - * @retval true when key K is valid + * @param k Key to test + * @retval true If key is valid */ static bool crypt_key_is_valid(struct CryptKeyInfo *k) { @@ -385,7 +399,8 @@ static bool crypt_key_is_valid(struct CryptKeyInfo *k) /** * crypt_id_is_strong - Is the key strong - * @retval true when validity of KEY is sufficient + * @param key Key to test + * @retval true Validity of key is sufficient */ static int crypt_id_is_strong(struct CryptKeyInfo *key) { @@ -417,7 +432,10 @@ static int crypt_id_is_strong(struct CryptKeyInfo *key) /** * crypt_id_is_valid - Is key ID valid - * ~return true when the KEY is valid, i.e. not marked as unusable + * @param key Key to test + * @retval true Key is valid + * + * When the key is not marked as unusable */ static int crypt_id_is_valid(struct CryptKeyInfo *key) { @@ -429,6 +447,10 @@ static int crypt_id_is_valid(struct CryptKeyInfo *key) /** * crypt_id_matches_addr - Does key ID match the address + * @param addr First email address + * @param u_addr Second email address + * @param key Key to use + * @retval num Flags, e.g. #CRYPT_KV_VALID * * Return a bit vector describing how well the addresses ADDR and U_ADDR match * and whether KEY is valid. @@ -462,10 +484,6 @@ static int crypt_id_matches_addr(struct Address *addr, struct Address *u_addr, return rc; } -/* - * GPGME convenient functions. - */ - /** * create_gpgme_context - Create a new GPGME context * @param for_smime If true, protocol of the context is set to CMS @@ -498,8 +516,11 @@ static gpgme_ctx_t create_gpgme_context(bool for_smime) /** * create_gpgme_data - Create a new GPGME data object + * @retval ptr GPGPE data object * * This is a wrapper to die on error. + * + * @note Call gpgme_data_release() to free the data object */ static gpgme_data_t create_gpgme_data(void) { @@ -517,10 +538,9 @@ static gpgme_data_t create_gpgme_data(void) /** * body_to_data_object - Create GPGME object from the mail body - * - * Create a new GPGME Data object from the mail body A. With CONVERT passed as - * true, the lines are converted to CR,LF if required. Return NULL on error or - * the gpgme_data_t object on success. + * @param a Body to use + * @param convert If trye, lines are converted to CR-LF if required + * @retval ptr Newly created GPGME data object */ static gpgme_data_t body_to_data_object(struct Body *a, int convert) { @@ -585,9 +605,10 @@ static gpgme_data_t body_to_data_object(struct Body *a, int convert) /** * file_to_data_object - Create GPGME data object from file - * - * Create a GPGME data object from the stream FP but limit the object - * to LENGTH bytes starting at OFFSET bytes from the beginning of the file. + * @param fp File to read from + * @param offset Offset to start reading from + * @param length Length of data to read + * @retval ptr Newly created GPGME data object */ static gpgme_data_t file_to_data_object(FILE *fp, long offset, size_t length) { @@ -606,6 +627,10 @@ static gpgme_data_t file_to_data_object(FILE *fp, long offset, size_t length) /** * data_object_to_stream - Write a GPGME data object to a file + * @param data GPGME data object + * @param fp File to write to + * @retval 0 Success + * @retval -1 Error */ static int data_object_to_stream(gpgme_data_t data, FILE *fp) { @@ -646,10 +671,14 @@ static int data_object_to_stream(gpgme_data_t data, FILE *fp) /** * data_object_to_tempfile - Copy a data object to a temporary file + * @param[in] data GPGME data object + * @param[out] ret_fp Temporary file + * @retval ptr Name of temporary file * * If ret_fp is passed in, the file will be rewound, left open, and returned * via that parameter. - * The tempfile name is returned, and must be freed. + * + * @note The caller must free the returned file name */ static char *data_object_to_tempfile(gpgme_data_t data, FILE **ret_fp) { @@ -721,8 +750,9 @@ static void free_recipient_set(gpgme_key_t **p_rset) /** * create_recipient_set - Create a GpgmeRecipientSet from a string of keys - * - * The keys must be space delimited. + * @param keylist Keys, space-separated + * @param protocol GPGME protocol + * @retval ptr GPGME key set */ static gpgme_key_t *create_recipient_set(const char *keylist, gpgme_protocol_t protocol) { @@ -792,7 +822,7 @@ static gpgme_key_t *create_recipient_set(const char *keylist, gpgme_protocol_t p /** * set_signer - Make sure that the correct signer is set - * @param ctx gpgme Context + * @param ctx GPGME handle * @param for_smime Use S/MIME * @retval 0 Success * @retval -1 Error @@ -856,11 +886,11 @@ static gpgme_error_t set_pka_sig_notation(gpgme_ctx_t ctx) /** * encrypt_gpgme_object - Encrypt the GPGPME data object - * - * Encrypt the gpgme data object PLAINTEXT to the recipients in RSET and return - * an allocated filename to a temporary file containing the enciphered text. - * With USE_SMIME set to true, the smime backend is used. With COMBINED_SIGNED - * a PGP message is signed and encrypted. Returns NULL in case of error + * @param plaintext GPGME data object with plain text message + * @param rset Set of recipients to encrypt to + * @param use_smime If true, use SMIME + * @param combined_signed If true, sign and encrypt the message (PGP only) + * @retval ptr Name of temporary file containing encrypted text */ static char *encrypt_gpgme_object(gpgme_data_t plaintext, gpgme_key_t *rset, bool use_smime, bool combined_signed) @@ -924,12 +954,15 @@ static void strlower(char *s) /** * get_micalg - Find the "micalg" parameter from the last GPGME operation + * @param ctx GPGME handle + * @param use_smime If set, use SMIME instead of PGP + * @param buf Buffer for the result + * @param buflen Length of buffer + * @retval 0 Success + * @retval -1 Error * - * Find the "micalg" parameter from the last Gpgme operation on context CTX. - * It is expected that this operation was a sign operation. Return the - * algorithm name as a C string in buffer BUF which must have been allocated by - * the caller with size BUFLEN. Returns 0 on success or -1 in case of an - * error. The return string is truncated to BUFLEN - 1. + * Find the "Message Integrity Check algorithm" from the last GPGME operation. + * It is expected that this operation was a sign operation. */ static int get_micalg(gpgme_ctx_t ctx, int use_smime, char *buf, size_t buflen) { @@ -1212,7 +1245,14 @@ struct Body *smime_gpgme_build_smime_entity(struct Body *a, char *keylist) /** * show_sig_summary - Show a signature summary - * @retval 1 if there is is a severe warning + * @param sum Flags, e.g. GPGME_SIGSUM_KEY_REVOKED + * @param ctx GPGME handle + * @param key Set of keys + * @param idx Index into key set + * @param s State to use + * @param sig GPGME signature + * @retval 0 Success + * @retval 1 There is is a severe warning * * Display the common attributes of the signature summary SUM. */ @@ -1395,6 +1435,9 @@ static void show_fingerprint(gpgme_key_t key, struct State *state) /** * show_one_sig_validity - Show the validity of a key used for one signature + * @param ctx GPGME handle + * @param idx Index of signature to check + * @param s State to use */ static void show_one_sig_validity(gpgme_ctx_t ctx, int idx, struct State *s) { @@ -1490,14 +1533,15 @@ static void print_smime_keyinfo(const char *msg, gpgme_signature_t sig, /** * show_one_sig_status - Show information about one signature + * @param ctx GPGME handle of a successful verification + * @param idx Index + * @param s State to use * @retval 0 Normal procession * @retval 1 A bad signature * @retval 2 A signature with a warning * @retval -1 No more signature * - * This function is called with the context CTX of a successful verification - * operation and the enumerator IDX which should start at 0 and increment for - * each call/signature. + * The index should start at 0 and increment for each call/signature. */ static int show_one_sig_status(gpgme_ctx_t ctx, int idx, struct State *s) { @@ -1755,10 +1799,14 @@ int smime_gpgme_verify_one(struct Body *sigbdy, struct State *s, const char *tem /** * decrypt_part - Decrypt a PGP or SMIME message + * @param[in] a Body of message + * @param[in] s State to use + * @param[in] fpout File to write to + * @param[in] is_smime True if an SMIME message + * @param[out] r_is_signed Flag, R_IS_SIGNED (PGP only) + * @retval ptr Newly allocated Body * - * (depending on the boolean flag IS_SMIME) with body A described further by - * state S. Write plaintext out to file FPOUT and return a new body. For PGP - * returns a flag in R_IS_SIGNED to indicate whether this is a combined + * For PGP returns a flag in R_IS_SIGNED to indicate whether this is a combined * encrypted and signed message, for S/MIME it returns true when it is not a * encrypted but a signed message. */ @@ -1899,9 +1947,7 @@ restart: tattach = mutt_read_mime_header(fpout, 0); if (tattach) { - /* - * Need to set the length of this body part. - */ + /* Need to set the length of this body part. */ fstat(fileno(fpout), &info); tattach->length = info.st_size - tattach->offset; @@ -2377,6 +2423,9 @@ void pgp_gpgme_invoke_import(const char *fname) /** * copy_clearsigned - Copy a clearsigned message + * @param data GPGME data object + * @param s State to use + * @param charset Charset of message * * strip the signature and PGP's dash-escaping. * @@ -2604,12 +2653,10 @@ int pgp_gpgme_application_handler(struct Body *m, struct State *s) gpgme_release(ctx); } - /* - * Now, copy cleartext to the screen. NOTE - we expect that PGP - * outputs utf-8 cleartext. This may not always be true, but it - * seems to be a reasonable guess. - */ - + /* Now, copy cleartext to the screen. NOTE - we expect that PGP + * outputs utf-8 cleartext. This may not always be true, but it + * seems to be a reasonable guess. + */ if (s->flags & MUTT_DISPLAY) { if (needpass) @@ -2801,11 +2848,9 @@ int smime_gpgme_application_handler(struct Body *a, struct State *s) s->fpin = savefp; } - /* - * if a multipart/signed is the _only_ sub-part of a - * multipart/encrypted, cache signature verification - * status. - */ + /* if a multipart/signed is the _only_ sub-part of a multipart/encrypted, + * cache signature verification status. + */ if (mutt_is_multipart_signed(tattach) && !tattach->next) { a->goodsig = tattach->goodsig; @@ -3097,6 +3142,11 @@ static void crypt_entry(char *buf, size_t buflen, struct Menu *menu, int num) /** * compare_key_address - Compare Key addresses and IDs 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 */ static int compare_key_address(const void *a, const void *b) { @@ -3119,6 +3169,11 @@ static int crypt_compare_address(const void *a, const void *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) { @@ -3140,6 +3195,11 @@ static int crypt_compare_keyid(const void *a, const void *b) /** * compare_key_date - Compare Key creation dates and addresses 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 */ static int compare_key_date(const void *a, const void *b) { @@ -3167,6 +3227,11 @@ static int crypt_compare_date(const void *a, const void *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. @@ -3218,6 +3283,11 @@ static int crypt_compare_trust(const void *a, const void *b) /** * print_dn_part - Print the X.500 Distinguished Name + * @param fp File to write to + * @param dn Distinguished Name + * @param key Key string + * @retval 1 If any DN keys match the given key string + * @retval 0 Otherwise * * Print the X.500 Distinguished Name part KEY from the array of parts DN to FP. */ @@ -3240,6 +3310,8 @@ static int print_dn_part(FILE *fp, struct DnArray *dn, const char *key) /** * print_dn_parts - Print all parts of a DN in a standard sequence + * @param fp File to write to + * @param dn Array of Distinguished Names */ static void print_dn_parts(FILE *fp, struct DnArray *dn) { @@ -3277,7 +3349,12 @@ static void print_dn_parts(FILE *fp, struct DnArray *dn) } /** - * parse_dn_part - Parse an RDN; this is a helper to parse_dn() + * parse_dn_part - Parse an RDN + * @param array Array for results + * @param string String to parse + * @retval ptr First character after Distinguished Name + * + * This is a helper to parse_dn() */ static const char *parse_dn_part(struct DnArray *array, const char *string) { @@ -3370,6 +3447,8 @@ static const char *parse_dn_part(struct DnArray *array, const char *string) /** * parse_dn - Parse a DN and return an array-ized one + * @param string String to parse + * @retval ptr Array of Distinguished Names * * This is not a validating parser and it does not support any old-stylish * syntax; gpgme is expected to return only rfc2253 compatible strings. @@ -3430,10 +3509,11 @@ failure: /** * parse_and_print_user_id - Print a nice representation of the userid + * @param fp File to write to + * @param userid String returned by GPGME key functions (utf-8 encoded) * * Make sure it is displayed in a proper way, which does mean to reorder some - * parts for S/MIME's DNs. USERID is a string as returned by the gpgme key - * functions. It is utf-8 encoded. + * parts for S/MIME's DNs. */ static void parse_and_print_user_id(FILE *fp, const char *userid) { @@ -3557,6 +3637,8 @@ int KeyInfoPadding[KIP_END] = { 0 }; /** * print_key_info - Verbose information about a key or certificate to a file + * @param key Key to use + * @param fp File to write to */ static void print_key_info(gpgme_key_t key, FILE *fp) { @@ -3813,6 +3895,7 @@ static void print_key_info(gpgme_key_t key, FILE *fp) /** * verify_key - Show detailed information about the selected key + * @param key Key to show */ static void verify_key(struct CryptKeyInfo *key) { @@ -4119,9 +4202,14 @@ static void crypt_add_string_to_hints(const char *str, struct ListHead *hints) /** * crypt_select_key - Get the user to select a key + * @param[in] keys List of keys to select from + * @param[in] p Address to match + * @param[in] s Real name to display + * @param[in] app Flags, e.g. #APPLICATION_PGP + * @param[out] forced_valid Set to true if user overrode key's validity + * @retval ptr Key selected by user * - * Display a menu to select a key from the array KEYS. FORCED_VALID will be set - * to true on return if the user did override the key's validity. + * Display a menu to select a key from the array of keys. */ static struct CryptKeyInfo *crypt_select_key(struct CryptKeyInfo *keys, struct Address *p, const char *s, @@ -4428,18 +4516,14 @@ static struct CryptKeyInfo *crypt_getkeybyaddr(struct Address *a, } else if (the_strong_valid_key && !multi) { - /* - * There was precisely one strong match on a valid ID. - * - * Proceed without asking the user. - */ + /* There was precisely one strong match on a valid ID. + * Proceed without asking the user. + */ k = crypt_copy_key(the_strong_valid_key); } else { - /* - * Else: Ask the user. - */ + /* Else: Ask the user. */ k = crypt_select_key(matches, a, NULL, app, forced_valid); } @@ -4516,12 +4600,15 @@ static struct CryptKeyInfo *crypt_getkeybystr(char *p, short abilities, /** * crypt_ask_for_key - Ask the user for a key + * @param[in] tag Prompt to display + * @param[in] whatfor Label to use (OPTIONAL) + * @param[in] abilities Flags, e.g. #KEYFLAG_CANSIGN + * @param[in] app Application type, e.g. #APPLICATION_PGP + * @param[out] forced_valid Set to true if user overrode key's validity + * @retval ptr Copy of the selected key * - * Display TAG as a prompt to ask for a key. If WHATFOR is not null use it as - * default and store it under that label as the next default. ABILITIES - * describe the required key abilities (sign, encrypt) and APP the type of the - * requested key; ether S/MIME or PGP. Return a copy of the key or NULL if not - * found. + * If whatfor is not null use it as default and store it under that label as + * the next default. */ static struct CryptKeyInfo *crypt_ask_for_key(char *tag, char *whatfor, short abilities, unsigned int app, int *forced_valid) @@ -4859,8 +4946,7 @@ static int gpgme_send_menu(struct Header *msg, int is_smime) else msg->security |= APPLICATION_PGP; - /* - * Opportunistic encrypt is controlling encryption. + /* Opportunistic encrypt is controlling encryption. * NOTE: "Signing" and "Clearing" only adjust the sign bit, so we have different * letter choices for those. */ @@ -4885,10 +4971,7 @@ static int gpgme_send_menu(struct Header *msg, int is_smime) choices = "SamCo"; } } - /* - * Opportunistic encryption option is set, but is toggled off - * for this message. - */ + /* Opportunistic encryption option is set, but is toggled off for this message. */ else if (CryptOpportunisticEncrypt) { if (is_smime) @@ -4910,9 +4993,7 @@ static int gpgme_send_menu(struct Header *msg, int is_smime) choices = "esabmcO"; } } - /* - * Opportunistic encryption is unset - */ + /* Opportunistic encryption is unset */ else { if (is_smime) @@ -5063,8 +5144,7 @@ static int verify_sender(struct Header *h) } else { - /* - * Assume address is 'mailbox@domainname'. + /* Assume address is 'mailbox@domainname'. * The mailbox part is case-sensitive, * the domainname is not. (RFC2821) */ diff --git a/ncrypt/crypt_mod.c b/ncrypt/crypt_mod.c index 7111fe552..1e6df5eca 100644 --- a/ncrypt/crypt_mod.c +++ b/ncrypt/crypt_mod.c @@ -35,15 +35,16 @@ * * A type of a variable to keep track of registered crypto modules. */ +static STAILQ_HEAD(CryptModuleHead, CryptModule) CryptModules = STAILQ_HEAD_INITIALIZER(CryptModules); struct CryptModule { struct CryptModuleSpecs *specs; STAILQ_ENTRY(CryptModule) entries; }; -static STAILQ_HEAD(, CryptModule) CryptModules = STAILQ_HEAD_INITIALIZER(CryptModules); /** * crypto_module_register - Register a new crypto module + * @param specs API functions */ void crypto_module_register(struct CryptModuleSpecs *specs) { @@ -54,8 +55,9 @@ void crypto_module_register(struct CryptModuleSpecs *specs) /** * crypto_module_lookup - Lookup a crypto module by name + * @param identifier Name, e.g. #APPLICATION_PGP + * @retval ptr Crypto module * - * Return the crypto module specs for IDENTIFIER. * This function is usually used via the CRYPT_MOD_CALL[_CHECK] macros. */ struct CryptModuleSpecs *crypto_module_lookup(int identifier) diff --git a/ncrypt/pgp.c b/ncrypt/pgp.c index accb5897f..7613abf7e 100644 --- a/ncrypt/pgp.c +++ b/ncrypt/pgp.c @@ -179,6 +179,8 @@ static char *pgp_fingerprint(struct PgpKeyInfo *k) /** * pgp_fpr_or_lkeyid - Get the fingerprint or long keyid + * @param k PGP key + * @retval ptr String fingerprint or long keyid * * Grab the longest key identifier available: fingerprint or else * the long keyid. @@ -198,6 +200,10 @@ char *pgp_fpr_or_lkeyid(struct PgpKeyInfo *k) /** * pgp_copy_checksig - Copy PGP output and look for signs of a good signature + * @param fpin File to read from + * @param fpout File to write to + * @retval 0 Success + * @retval -1 Error */ static int pgp_copy_checksig(FILE *fpin, FILE *fpout) { @@ -241,6 +247,9 @@ static int pgp_copy_checksig(FILE *fpin, FILE *fpout) /** * pgp_check_decryption_okay - Check PGP output to look for successful outcome + * @param fpin File to read from + * @retval 0 Success + * @retval -1 Error * * Checks PGP output messages to look for the $pgp_decryption_okay message. * This protects against messages with multipart/encrypted headers but which @@ -278,7 +287,16 @@ static int pgp_check_pgp_decryption_okay_regex(FILE *fpin) return rc; } -/* Checks GnuPGP status fd output for various status codes indicating +/** + * pgp_check_decryption_okay - Check GPG output for status codes + * @param fpin File to read from + * @retval 1 - no patterns were matched (if delegated to decryption_okay_regexp) + * @retval 0 - DECRYPTION_OKAY was seen, with no PLAINTEXT outside. + * @retval -1 - No decryption status codes were encountered + * @retval -2 - PLAINTEXT was encountered outside of DECRYPTION delimeters. + * @retval -3 - DECRYPTION_FAILED was encountered + * + * Checks GnuPGP status fd output for various status codes indicating * an issue. If $pgp_check_gpg_decrypt_status_fd is unset, it falls * back to the old behavior of just scanning for $pgp_decryption_okay. * @@ -288,13 +306,6 @@ static int pgp_check_pgp_decryption_okay_regex(FILE *fpin) * On the other hand, for pgp_application_pgp_handler(), a * "BEGIN PGP MESSAGE" could indicate a signed and armored message. * For that we allow -1 and -2 as "valid" (with a warning). - * - * Returns: - * 1 - no patterns were matched (if delegated to decryption_okay_regexp) - * 0 - DECRYPTION_OKAY was seen, with no PLAINTEXT outside. - * -1 - No decryption status codes were encountered - * -2 - PLAINTEXT was encountered outside of DECRYPTION delimeters. - * -3 - DECRYPTION_FAILED was encountered */ static int pgp_check_decryption_okay(FILE *fpin) { @@ -349,6 +360,9 @@ static int pgp_check_decryption_okay(FILE *fpin) /** * pgp_copy_clearsigned - Copy a clearsigned message, stripping the signature + * @param fpin File to read from + * @param s State to use + * @param charset Charset of file * * XXX charset handling: We assume that it is safe to do character set * decoding first, dash decoding second here, while we do it the other way @@ -584,8 +598,7 @@ int pgp_class_application_handler(struct Body *m, struct State *s) if (rc == 0) have_any_sigs = true; - /* - * Sig is bad if + /* Sig is bad if * gpg_good_sign-pattern did not match || pgp_decode_command returned not 0 * Sig _is_ correct if * gpg_good_sign="" && pgp_decode_command returned 0 @@ -621,10 +634,7 @@ int pgp_class_application_handler(struct Body *m, struct State *s) } } - /* - * Now, copy cleartext to the screen. - */ - + /* Now, copy cleartext to the screen. */ if (s->flags & MUTT_DISPLAY) { if (needpass) @@ -657,8 +667,7 @@ int pgp_class_application_handler(struct Body *m, struct State *s) mutt_ch_fgetconv_close(&fc); } - /* - * Multiple PGP blocks can exist, so these need to be closed and + /* Multiple PGP blocks can exist, so these need to be closed and * unlinked inside the loop. */ mutt_file_fclose(&tmpfp); @@ -871,6 +880,8 @@ int pgp_class_verify_one(struct Body *sigbdy, struct State *s, const char *tempf /** * pgp_extract_keys_from_attachment - Extract pgp keys from messages/attachments + * @param fp File to read from + * @param top Top Attachment */ static void pgp_extract_keys_from_attachment(FILE *fp, struct Body *top) { @@ -1029,14 +1040,11 @@ static struct Body *pgp_decrypt_part(struct Body *a, struct State *s, tattach = mutt_read_mime_header(fpout, 0); if (tattach) { - /* - * Need to set the length of this body part. - */ + /* Need to set the length of this body part. */ fstat(fileno(fpout), &info); tattach->length = info.st_size - tattach->offset; /* See if we need to recurse on this MIME part. */ - mutt_parse_part(fpout, tattach); } @@ -1155,13 +1163,10 @@ int pgp_class_encrypted_handler(struct Body *a, struct State *s) rc = mutt_body_handler(tattach, s); s->fpin = fpin; - /* - * if a multipart/signed is the _only_ sub-part of a + /* if a multipart/signed is the _only_ sub-part of a * multipart/encrypted, cache signature verification * status. - * */ - if (mutt_is_multipart_signed(tattach) && !tattach->next) a->goodsig |= tattach->goodsig; @@ -1244,8 +1249,7 @@ struct Body *pgp_class_sign_message(struct Body *a) fputc('\n', pgpin); mutt_file_fclose(&pgpin); - /* - * Read back the PGP signature. Also, change MESSAGE=>SIGNATURE as + /* Read back the PGP signature. Also, change MESSAGE=>SIGNATURE as * recommended for future releases of PGP. */ while (fgets(buffer, sizeof(buffer) - 1, pgpout) != NULL) @@ -1780,8 +1784,7 @@ int pgp_class_send_menu(struct Header *msg) One of them will appear in each of the three strings marked "(inline"), below. */ mime_inline = _("(i)nline"); } - /* - * Opportunistic encrypt is controlling encryption. Allow to toggle + /* Opportunistic encrypt is controlling encryption. Allow to toggle * between inline and mime, but not turn encryption on or off. * NOTE: "Signing" and "Clearing" only adjust the sign bit, so we have different * letter choices for those. @@ -1810,8 +1813,7 @@ int pgp_class_send_menu(struct Header *msg) choices = "SaCo"; } } - /* - * Opportunistic encryption option is set, but is toggled off + /* Opportunistic encryption option is set, but is toggled off * for this message. */ else if (CryptOpportunisticEncrypt) @@ -1842,9 +1844,7 @@ int pgp_class_send_menu(struct Header *msg) choices = "esabcO"; } } - /* - * Opportunistic encryption is unset - */ + /* Opportunistic encryption is unset */ else { if (msg->security & (ENCRYPT | SIGN)) diff --git a/ncrypt/pgpinvoke.c b/ncrypt/pgpinvoke.c index 17f16b934..dc03f275c 100644 --- a/ncrypt/pgpinvoke.c +++ b/ncrypt/pgpinvoke.c @@ -167,10 +167,6 @@ static void mutt_pgp_command(char *buf, size_t buflen, mutt_debug(2, "%s\n", buf); } -/* - * Glue. - */ - static pid_t pgp_invoke(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd, int pgpoutfd, int pgperrfd, bool need_passphrase, const char *fname, const char *sig_fname, const char *ids, const char *format) diff --git a/ncrypt/pgpkey.c b/ncrypt/pgpkey.c index dd68765f8..43725cfba 100644 --- a/ncrypt/pgpkey.c +++ b/ncrypt/pgpkey.c @@ -123,20 +123,6 @@ static struct PgpKeyInfo *pgp_principal_key(struct PgpKeyInfo *key) return key; } -/* - * Format an entry on the PGP key selection menu. - * - * %n number - * %k key id %K key id of the principal key - * %u user id - * %a algorithm %A algorithm of the princ. key - * %l length %L length of the princ. key - * %f flags %F flags of the princ. key - * %c capabilities %C capabilities of the princ. key - * %t trust/validity of the key-uid association - * %[...] date of key using strftime(3) - */ - /** * struct PgpEntry - An entry in a PGP key menu */ @@ -146,6 +132,40 @@ struct PgpEntry struct PgpUid *uid; }; +/** + * pgp_entry_fmt - Format an entry on the PGP key selection menu + * @param[out] buf Buffer in which to save string + * @param[in] buflen Buffer length + * @param[in] col Starting column + * @param[in] cols Number of screen columns + * @param[in] op printf-like operator, e.g. 't' + * @param[in] src printf-like format string + * @param[in] prec Field precision, e.g. "-3.4" + * @param[in] if_str If condition is met, display this string + * @param[in] else_str Otherwise, display this string + * @param[in] data Pointer to the mailbox Context + * @param[in] flags Format flags + * @retval src (unchanged) + * + * pgp_entry_fmt() is a callback function for mutt_expando_format(). + * + * | Expando | Description + * |:--------|:-------------------------------------------------------- + * | \%a | Algorithm + * | \%A | Algorithm of the princ. key + * | \%c | Capabilities + * | \%C | Capabilities of the princ. key + * | \%f | Flags + * | \%F | Flags of the princ. key + * | \%k | Key id + * | \%K | Key id of the principal key + * | \%l | Length + * | \%L | Length of the princ. key + * | \%n | Number + * | \%t | Trust/validity of the key-uid association + * | \%u | User id + * | \%[...] | Date of key using strftime(3) + */ static const char *pgp_entry_fmt(char *buf, size_t buflen, size_t col, int cols, char op, const char *src, const char *prec, const char *if_str, const char *else_str, @@ -955,9 +975,7 @@ struct PgpKeyInfo *pgp_getkeybyaddr(struct Address *a, short abilities, } else if (the_strong_valid_key && !multi) { - /* - * There was precisely one strong match on a valid ID. - * + /* There was precisely one strong match on a valid ID. * Proceed without asking the user. */ pgp_remove_key(&matches, the_strong_valid_key); @@ -965,9 +983,7 @@ struct PgpKeyInfo *pgp_getkeybyaddr(struct Address *a, short abilities, } else { - /* - * Else: Ask the user. - */ + /* Else: Ask the user. */ k = pgp_select_key(matches, a, NULL); if (k) pgp_remove_key(&matches, k); diff --git a/ncrypt/pgplib.c b/ncrypt/pgplib.c index bfaba7c3d..5c3824910 100644 --- a/ncrypt/pgplib.c +++ b/ncrypt/pgplib.c @@ -80,13 +80,6 @@ bool pgp_cansign(unsigned char type) } } -/* return values: - - * 1 = sign only - * 2 = encrypt only - * 3 = both - */ - short pgp_get_abilities(unsigned char type) { return (pgp_canencrypt(type) << 1) | pgp_cansign(type); diff --git a/ncrypt/smime.c b/ncrypt/smime.c index 5fdd65f1a..5f59af898 100644 --- a/ncrypt/smime.c +++ b/ncrypt/smime.c @@ -184,8 +184,33 @@ int smime_class_valid_passphrase(void) /** * fmt_smime_command - Format an SMIME command + * @param[out] buf Buffer in which to save string + * @param[in] buflen Buffer length + * @param[in] col Starting column + * @param[in] cols Number of screen columns + * @param[in] op printf-like operator, e.g. 't' + * @param[in] src printf-like format string + * @param[in] prec Field precision, e.g. "-3.4" + * @param[in] if_str If condition is met, display this string + * @param[in] else_str Otherwise, display this string + * @param[in] data Pointer to the mailbox Context + * @param[in] flags Format flags + * @retval src (unchanged) * * This is almost identical to pgp's invoking interface. + * + * fmt_smime_command() is a callback function for mutt_expando_format(). + * + * | Expando | Description + * |:--------|:----------------------------------------------------------------- + * | \%a | Algorithm used for encryption + * | \%C | CA location: Depending on whether $smime_ca_location points to a directory or file + * | \%c | One or more certificate IDs + * | \%d | Message digest algorithm specified with $smime_sign_digest_alg + * | \%f | File containing a message + * | \%i | Intermediate certificates + * | \%k | The key-pair specified with $smime_default_key + * | \%s | File containing the signature part of a multipart/signed attachment when verifying it */ static const char *fmt_smime_command(char *buf, size_t buflen, size_t col, int cols, char op, const char *src, const char *prec, @@ -679,6 +704,9 @@ static struct SmimeKey *smime_get_candidates(char *search, short public) /** * smime_get_key_by_hash - Find a key by its hash + * @param hash Hash to find + * @param public If true, only get the public keys + * @retval ptr Matching key * * Returns the first matching key record, without prompting or checking of * abilities or trust. @@ -838,6 +866,7 @@ static struct SmimeKey *smime_ask_for_key(char *prompt, short abilities, short p /** * getkeys - Get the keys for a mailbox + * @param mailbox Email address * * This sets the '*ToUse' variables for an upcoming decryption, where the * required key is different from SmimeDefaultKey. @@ -1512,11 +1541,15 @@ struct Body *smime_class_build_smime_entity(struct Body *a, char *certlist) /** * openssl_md_to_smime_micalg - Change the algorithm names + * @param md OpenSSL message digest name + * @retval ptr SMIME Message Integrity Check algorithm * * The openssl -md doesn't want hyphens: * md5, sha1, sha224, sha256, sha384, sha512 * However, the micalg does: * md5, sha-1, sha-224, sha-256, sha-384, sha-512 + * + * @note The caller should free the returned string */ static char *openssl_md_to_smime_micalg(char *md) { @@ -1805,6 +1838,10 @@ int smime_class_verify_one(struct Body *sigbdy, struct State *s, const char *tem /** * smime_handle_entity - Handle type application/pkcs7-mime + * @param m Body to handle + * @param s State to use + * @param out_file File for the result + * @retval ptr Body for parsed MIME part * * This can either be a signed or an encrypted message. */ @@ -2096,8 +2133,7 @@ int smime_class_send_menu(struct Header *msg) msg->security |= APPLICATION_SMIME; - /* - * Opportunistic encrypt is controlling encryption. + /* Opportunistic encrypt is controlling encryption. * NOTE: "Signing" and "Clearing" only adjust the sign bit, so we have different * letter choices for those. */ @@ -2110,8 +2146,7 @@ int smime_class_send_menu(struct Header *msg) letters = _("swaco"); choices = "SwaCo"; } - /* - * Opportunistic encryption option is set, but is toggled off + /* Opportunistic encryption option is set, but is toggled off * for this message. */ else if (CryptOpportunisticEncrypt) @@ -2123,9 +2158,7 @@ int smime_class_send_menu(struct Header *msg) letters = _("eswabco"); choices = "eswabcO"; } - /* - * Opportunistic encryption is unset - */ + /* Opportunistic encryption is unset */ else { /* L10N: S/MIME options */ diff --git a/notmuch/mutt_notmuch.c b/notmuch/mutt_notmuch.c index d6bf7b85a..e8a5566d8 100644 --- a/notmuch/mutt_notmuch.c +++ b/notmuch/mutt_notmuch.c @@ -976,8 +976,7 @@ static int init_header(struct Header *h, const char *path, notmuch_message_t *ms h->data = mutt_mem_calloc(1, sizeof(struct NmHdrData)); h->free_cb = deinit_header; - /* - * Notmuch ensures that message Id exists (if not notmuch Notmuch will + /* Notmuch ensures that message Id exists (if not notmuch Notmuch will * generate an ID), so it's more safe than use neomutt Header->env->id */ ((struct NmHdrData *) h->data)->virtual_id = mutt_str_strdup(id); @@ -1598,8 +1597,7 @@ static int remove_filename(struct NmCtxData *data, const char *path) if (trans < 0) return -1; - /* - * note that unlink() is probably unnecessary here, it's already removed + /* note that unlink() is probably unnecessary here, it's already removed * by mh_sync_mailbox_message(), but for sure... */ st = notmuch_database_remove_message(db, path); diff --git a/pager.c b/pager.c index 65013475a..8ff9ea5bc 100644 --- a/pager.c +++ b/pager.c @@ -1147,6 +1147,9 @@ static int grok_ansi(unsigned char *buf, int pos, struct AnsiAttr *a) /** * trim_incomplete_mbyte - Remove an incomplete character + * @param buf Buffer containing string + * @param len Length of buffer + * @retval num Number of bytes remaining * * trim tail of buf so that it contains complete multibyte characters */ @@ -1676,8 +1679,7 @@ static int display_line(FILE *f, LOFF_T *last_pos, struct Line **line_info, if (special || (col != pager_window->cols && (flags & (MUTT_SHOWCOLOR | MUTT_SEARCH)))) resolve_color(*line_info, n, vch, flags, 0, &a); - /* - * Fill the blank space at the end of the line with the prevailing color. + /* Fill the blank space at the end of the line with the prevailing color. * ncurses does an implicit clrtoeol() when you do addch('\n') so we have * to make sure to reset the color *after* that */ @@ -1695,8 +1697,7 @@ static int display_line(FILE *f, LOFF_T *last_pos, struct Line **line_info, if (col < pager_window->cols) mutt_window_clrtoeol(pager_window); - /* - * reset the color back to normal. This *must* come after the + /* reset the color back to normal. This *must* come after the * clrtoeol, otherwise the color for this line will not be * filled to the right margin. */ @@ -2089,6 +2090,12 @@ static void pager_menu_redraw(struct Menu *pager_menu) /** * mutt_pager - Display a file, or help, in a window + * @param banner Title to display in status bar + * @param fname Name of file to read + * @param flags Flags, e.g. #MUTT_SHOWCOLOR + * @param extra Info about email to display + * @retval 0 Success + * @retval -1 Error * * This pager is actually not so simple as it once was. It now operates in two * modes: one for viewing messages and the other for viewing help. These can diff --git a/pop/pop.c b/pop/pop.c index db46ce200..25d435aeb 100644 --- a/pop/pop.c +++ b/pop/pop.c @@ -395,8 +395,7 @@ static int pop_fetch_headers(struct Context *ctx) char *uidl = mutt_str_strdup(ctx->hdrs[i]->data); int refno = ctx->hdrs[i]->refno; int index = ctx->hdrs[i]->index; - /* - * - POP dynamically numbers headers and relies on h->refno + /* - POP dynamically numbers headers and relies on h->refno * to map messages; so restore header and overwrite restored * refno with current refno, same for index * - h->data needs to a separate pointer as it's driver-specific @@ -426,8 +425,7 @@ static int pop_fetch_headers(struct Context *ctx) } #endif - /* - * faked support for flags works like this: + /* faked support for flags works like this: * - if 'hcached' is true, we have the message in our hcache: * - if we also have a body: read * - if we don't have a body: old @@ -633,8 +631,7 @@ static int pop_msg_open(struct Context *ctx, struct Message *msg, int msgno) if (msg->fp) return 0; - /* - * see if we already have the message in our cache in + /* see if we already have the message in our cache in * case $message_cachedir is unset */ cache = &pop_data->cache[h->index % POP_CACHE_LEN]; diff --git a/pop/pop_lib.c b/pop/pop_lib.c index 1533395d8..0df2e3520 100644 --- a/pop/pop_lib.c +++ b/pop/pop_lib.c @@ -495,6 +495,11 @@ int pop_query_d(struct PopData *pop_data, char *buf, size_t buflen, char *msg) /** * pop_fetch_data - Read Headers with callback function + * @param pop_data POP data + * @param query POP query to send to server + * @param progressbar Progress bar + * @param funct Function called for each header read + * @param data Data to pass to the callback * @retval 0 Successful * @retval -1 Connection lost * @retval -2 Invalid command or execution error diff --git a/postpone.c b/postpone.c index 731e70351..a6fd8dd6c 100644 --- a/postpone.c +++ b/postpone.c @@ -616,11 +616,9 @@ int mutt_prepare_template(FILE *fp, struct Context *ctx, struct Header *newhdr, mutt_clear_error(); } - /* - * remove a potential multipart/signed layer - useful when + /* remove a potential multipart/signed layer - useful when * resending messages */ - if ((WithCrypto != 0) && mutt_is_multipart_signed(newhdr->content)) { newhdr->security |= SIGN; @@ -639,16 +637,13 @@ int mutt_prepare_template(FILE *fp, struct Context *ctx, struct Header *newhdr, newhdr->content = mutt_remove_multipart(newhdr->content); } - /* - * We don't need no primary multipart. + /* We don't need no primary multipart. * Note: We _do_ preserve messages! * * XXX - we don't handle multipart/alternative in any * smart way when sending messages. However, one may * consider this a feature. - * */ - if (newhdr->content->type == TYPE_MULTIPART) newhdr->content = mutt_remove_multipart(newhdr->content); diff --git a/progress.c b/progress.c index a36cd404f..fb2709c32 100644 --- a/progress.c +++ b/progress.c @@ -162,6 +162,10 @@ void mutt_progress_init(struct Progress *progress, const char *msg, * * If percent is -1, then the percentage will be calculated using pos and the * size in progress. + * + * If percent is positive, it is displayed as percentage, otherwise + * percentage is calculated from progress->size and pos if progress + * was initialized with positive size, otherwise no percentage is shown */ void mutt_progress_update(struct Progress *progress, long pos, int percent) { diff --git a/progress.h b/progress.h index 9021a3872..8070da0aa 100644 --- a/progress.h +++ b/progress.h @@ -48,9 +48,6 @@ struct Progress void mutt_progress_init(struct Progress *progress, const char *msg, unsigned short flags, unsigned short inc, size_t size); -/* If percent is positive, it is displayed as percentage, otherwise - * percentage is calculated from progress->size and pos if progress - * was initialized with positive size, otherwise no percentage is shown */ void mutt_progress_update(struct Progress *progress, long pos, int percent); #endif /* _MUTT_PROGRESS_H */ diff --git a/recvattach.c b/recvattach.c index 065a91dab..ed5abe29f 100644 --- a/recvattach.c +++ b/recvattach.c @@ -1125,6 +1125,16 @@ int mutt_attach_display_loop(struct Menu *menu, int op, struct Header *hdr, return op; } +/** + * mutt_generate_recvattach_list - Create a list of attachments + * @param actx Attachment context + * @param hdr Header of the email + * @param m Body of email + * @param fp File to read from + * @param parent_type Type, e.g. #TYPE_MULTIPART + * @param level Attachment depth + * @param decrypted True if attachment has been decrypted + */ static void mutt_generate_recvattach_list(struct AttachCtx *actx, struct Header *hdr, struct Body *m, FILE *fp, int parent_type, int level, int decrypted) @@ -1226,6 +1236,10 @@ static void mutt_generate_recvattach_list(struct AttachCtx *actx, struct Header } } +/** + * mutt_attach_init - Create a new Attachment context + * @param actx Attachment context + */ void mutt_attach_init(struct AttachCtx *actx) { /* Collapse the attachments if '$digest_collapse' is set AND if... @@ -1245,6 +1259,12 @@ void mutt_attach_init(struct AttachCtx *actx) } } +/** + * mutt_update_recvattach_menu - Update the Attachment Menu + * @param actx Attachment context + * @param menu Menu listing Attachments + * @param init If true, create a new Attachments context + */ static void mutt_update_recvattach_menu(struct AttachCtx *actx, struct Menu *menu, bool init) { if (init) diff --git a/recvcmd.c b/recvcmd.c index 3836ae5c9..6526bd81f 100644 --- a/recvcmd.c +++ b/recvcmd.c @@ -52,6 +52,9 @@ unsigned char MimeForwardRest; /** * check_msg - Are we working with an RFC822 message + * @param b Body of email + * @param err If true, display a message if this isn't an RFC822 message + * @retval true This is an RFC822 message * * some helper functions to verify that we are exclusively operating on * message/rfc822 attachments @@ -86,7 +89,10 @@ static bool check_all_msg(struct AttachCtx *actx, struct Body *cur, bool err) } /** - * check_can_decode - can we decode all tagged attachments? + * check_can_decode - Can we decode all tagged attachments? + * @param actx Attachment context + * @param cur Body of email + * @retval true All tagged attachments are decodable */ static bool check_can_decode(struct AttachCtx *actx, struct Body *cur) { @@ -112,6 +118,9 @@ static short count_tagged(struct AttachCtx *actx) /** * count_tagged_children - tagged children below a multipart/message attachment + * @param actx Attachment context + * @param i Index of first attachment + * @retval num Number of tagged attachments */ static short count_tagged_children(struct AttachCtx *actx, short i) { @@ -127,6 +136,9 @@ static short count_tagged_children(struct AttachCtx *actx, short i) /** * mutt_attach_bounce - Bounce function, from the attachment menu + * @param fp Handle of message + * @param actx Attachment context + * @param cur Body of email */ void mutt_attach_bounce(FILE *fp, struct AttachCtx *actx, struct Body *cur) { @@ -199,9 +211,7 @@ void mutt_attach_bounce(FILE *fp, struct AttachCtx *actx, struct Body *cur) mutt_addr_write(buf, sizeof(buf), addr, true); #define EXTRA_SPACE (15 + 7 + 2) - /* - * See commands.c. - */ + /* See commands.c. */ snprintf(prompt, sizeof(prompt) - 4, ngettext("Bounce message to %s", "Bounce messages to %s", p), buf); @@ -246,6 +256,9 @@ void mutt_attach_bounce(FILE *fp, struct AttachCtx *actx, struct Body *cur) /** * mutt_attach_resend - resend-message, from the attachment menu + * @param fp File containing email + * @param actx Attachment context + * @param cur Attachment */ void mutt_attach_resend(FILE *fp, struct AttachCtx *actx, struct Body *cur) { @@ -268,6 +281,10 @@ void mutt_attach_resend(FILE *fp, struct AttachCtx *actx, struct Body *cur) /** * find_common_parent - find a common parent message for the tagged attachments + * @param actx Attachment context + * @param nattach Number of tagged attachments + * @retval ptr Parent attachment + * @retval NULL Failure, no common parent */ static struct AttachPtr *find_common_parent(struct AttachCtx *actx, short nattach) { @@ -293,6 +310,10 @@ static struct AttachPtr *find_common_parent(struct AttachCtx *actx, short nattac /** * is_parent - Check whether one attachment is the parent of another + * @param i Index of parent Attachment + * @param actx Attachment context + * @param cur Potential child Attachemnt + * @retval true Attachment * * check whether attachment i is a parent of the attachment pointed to by cur * @@ -364,6 +385,10 @@ static void include_header(int quote, FILE *ifp, struct Header *hdr, FILE *ofp, /** * copy_problematic_attachments - Attach the body parts which can't be decoded + * @param[out] last Body pointer to update + * @param[in] actx Attachment context + * @param[in] force If true, attach parts that can't be decoded + * @retval ptr Pointer to last Body part * * This code is shared by forwarding and replying. */ @@ -384,6 +409,11 @@ static struct Body **copy_problematic_attachments(struct Body **last, /** * attach_forward_bodies - forward one or several MIME bodies + * @param fp File to read from + * @param hdr Header of email + * @param actx Attachment Context + * @param cur Body of email + * @param nattach Number of tagged attachments * * (non-message types) */ @@ -398,12 +428,10 @@ static void attach_forward_bodies(FILE *fp, struct Header *hdr, struct AttachCtx char prefix[STRING]; int rc = 0; - /* - * First, find the parent message. + /* First, find the parent message. * Note: This could be made an option by just * putting the following lines into an if block. */ - struct AttachPtr *parent = find_parent(actx, cur, nattach); if (parent) { @@ -446,14 +474,12 @@ static void attach_forward_bodies(FILE *fp, struct Header *hdr, struct AttachCtx include_header(ForwardQuote, parent_fp, parent_hdr, tmpfp, prefix); - /* - * Now, we have prepared the first part of the message body: The + /* Now, we have prepared the first part of the message body: The * original message's header. * * The next part is more interesting: either include the message bodies, * or attach them. */ - if ((!cur || mutt_can_decode(cur)) && (rc = query_quadoption(MimeForward, _("Forward as attachments?"))) == MUTT_YES) { @@ -464,11 +490,9 @@ static void attach_forward_bodies(FILE *fp, struct Header *hdr, struct AttachCtx goto bail; } - /* - * shortcut MIMEFWDREST when there is only one attachment. Is - * this intuitive? + /* shortcut MIMEFWDREST when there is only one attachment. + * Is this intuitive? */ - if (!mime_fwd_all && !cur && (nattach > 1) && !check_can_decode(actx, cur)) { rc = query_quadoption( @@ -552,6 +576,10 @@ bail: /** * attach_forward_msgs - Forward one or several message-type attachments + * @param fp File handle to attachment + * @param actx Attachment Context + * @param cur Attachment to forward (OPTIONAL) + * @param flags Send mode, e.g. #SEND_RESEND * * This is different from the previous function since we want to mimic the * index menu's behavior. @@ -685,6 +713,12 @@ void mutt_attach_forward(FILE *fp, struct Header *hdr, struct AttachCtx *actx, /** * attach_reply_envelope_defaults - Create the envelope defaults for a reply + * @param env Envelope to fill in + * @param actx Attachment Context + * @param parent Header of parent email + * @param flags Flags, e.g. #SEND_LIST_REPLY + * @retval 0 Success + * @retval -1 Error * * This function can be invoked in two ways. * @@ -782,6 +816,9 @@ static int attach_reply_envelope_defaults(struct Envelope *env, struct AttachCtx /** * attach_include_reply - This is _very_ similar to send.c's include_reply() + * @param fp File handle to attachment + * @param tmpfp File handle to temporary file + * @param cur Header of email */ static void attach_include_reply(FILE *fp, FILE *tmpfp, struct Header *cur) { diff --git a/remailer.c b/remailer.c index e230ac2ac..8eafa8523 100644 --- a/remailer.c +++ b/remailer.c @@ -130,6 +130,8 @@ static void mix_free_remailer(struct Remailer **r) /** * mix_type2_list - parse the type2.list as given by mixmaster -T + * @param[out] l Length of list + * @retval ptr type2.list */ static struct Remailer **mix_type2_list(size_t *l) { @@ -706,6 +708,9 @@ void mix_make_chain(struct ListHead *chainhead) /** * mix_check_message - Safety-check the message before passing it to mixmaster + * @param msg Header of email + * @retval 0 Success + * @retval -1 Error */ int mix_check_message(struct Header *msg) { diff --git a/resize.c b/resize.c index 005fbe3aa..746c3b014 100644 --- a/resize.c +++ b/resize.c @@ -42,6 +42,10 @@ #endif #endif +/** + * mutt_get_winsize - Use an ioctl to get the window size + * @retval obj Window size + */ struct winsize mutt_get_winsize(void) { struct winsize w = { 0 }; @@ -55,6 +59,9 @@ struct winsize mutt_get_winsize(void) } #ifdef USE_SLANG_CURSES +/** + * mutt_resize_screen - Update NeoMutt's opinion about the window size (SLANG) + */ void mutt_resize_screen(void) { struct winsize w = mutt_get_winsize(); @@ -85,6 +92,9 @@ void mutt_resize_screen(void) mutt_window_reflow(); } #else +/** + * mutt_resize_screen - Update NeoMutt's opinion about the window size (CURSES) + */ void mutt_resize_screen(void) { struct winsize w = mutt_get_winsize(); diff --git a/rfc1524.c b/rfc1524.c index 69802096d..a68ca722f 100644 --- a/rfc1524.c +++ b/rfc1524.c @@ -319,8 +319,7 @@ static int rfc1524_mailcap_parse(struct Body *a, char *filename, char *type, } else if (mutt_str_strncasecmp(field, "test", 4) == 0) { - /* - * This routine executes the given test command to determine + /* This routine executes the given test command to determine * if this is the right entry. */ char *test_command = NULL; diff --git a/rfc3676.c b/rfc3676.c index 6d4e22a9c..7660e7272 100644 --- a/rfc3676.c +++ b/rfc3676.c @@ -69,6 +69,8 @@ static int get_quote_level(const char *line) /** * space_quotes - Should we add spaces between quote levels + * @param s State to use + * @retval true If spaces should be added * * Determines whether to add spacing between/after each quote level: * ` >>>foo` @@ -88,6 +90,9 @@ static int space_quotes(struct State *s) /** * add_quote_suffix - Should we add a trailing space to quotes + * @param s State to use + * @param ql Quote level + * @retval true If spaces should be added * * Determines whether to add a trailing space to quotes: * ` >>> foo` @@ -156,6 +161,9 @@ static void flush_par(struct State *s, struct FlowedState *fst) /** * quote_width - Calculate the paragraph width based upon the quote level + * @param s State to use + * @param ql Quote level + * @retval int Paragraph width * * The start of a quoted line will be ">>> ", so we need to subtract the space * required for the prefix from the terminal width. @@ -265,7 +273,10 @@ static void print_fixed_line(const char *line, struct State *s, int ql, struct F } /** - * rfc3676_handler - body handler implementing RFC3676 for format=flowed + * rfc3676_handler - Body handler implementing RFC3676 for format=flowed + * @param a Body to handle + * @param s State to use + * @retval 0 Always */ int rfc3676_handler(struct Body *a, struct State *s) { @@ -336,6 +347,7 @@ int rfc3676_handler(struct Body *a, struct State *s) /** * rfc3676_space_stuff - Perform required RFC3676 space stuffing + * @param hdr Header of email * * Space stuffing means that we have to add leading spaces to * certain lines: diff --git a/send.c b/send.c index c360aa293..074db824a 100644 --- a/send.c +++ b/send.c @@ -116,6 +116,10 @@ char *Signature; bool SigOnTop; bool UseFrom; +/** + * append_signature - Append a signature to an email + * @param f File to write to + */ static void append_signature(FILE *f) { FILE *tmpfp = NULL; @@ -249,6 +253,13 @@ static struct Address *find_mailing_lists(struct Address *t, struct Address *c) return top; } +/** + * edit_address - Edit an email address + * @param a Address to edit + * @param field Prompt for user + * @retval 0 Success + * @retval -1 Failure + */ static int edit_address(struct Address **a, /* const */ char *field) { char buf[HUGE_STRING]; @@ -385,6 +396,10 @@ static char *nntp_get_header(const char *s) } #endif +/** + * process_user_recips - Process the user headers + * @param env Envelope to populate + */ static void process_user_recips(struct Envelope *env) { struct ListNode *uh = NULL; @@ -407,6 +422,10 @@ static void process_user_recips(struct Envelope *env) } } +/** + * process_user_header - Process the user headers + * @param env Envelope to populate + */ static void process_user_header(struct Envelope *env) { struct ListNode *uh = NULL; @@ -451,6 +470,12 @@ static void process_user_header(struct Envelope *env) } } +/** + * mutt_forward_intro - Add the "start of forwarded message" text + * @param ctx Mailbox + * @param cur Header of email + * @param fp File to write to + */ void mutt_forward_intro(struct Context *ctx, struct Header *cur, FILE *fp) { if (!ForwardAttributionIntro || !fp) @@ -464,6 +489,12 @@ void mutt_forward_intro(struct Context *ctx, struct Header *cur, FILE *fp) fputs("\n\n", fp); } +/** + * mutt_forward_trailer - Add a "end of forwarded message" text + * @param ctx Mailbox + * @param cur Header of email + * @param fp File to write to + */ void mutt_forward_trailer(struct Context *ctx, struct Header *cur, FILE *fp) { if (!ForwardAttributionTrailer || !fp) @@ -478,6 +509,14 @@ void mutt_forward_trailer(struct Context *ctx, struct Header *cur, FILE *fp) fputc('\n', fp); } +/** + * include_forward - Write out a forwarded message + * @param ctx Mailbox + * @param cur Header of email + * @param out File to write to + * @retval 0 Success + * @retval -1 Failure + */ static int include_forward(struct Context *ctx, struct Header *cur, FILE *out) { int chflags = CH_DECODE, cmflags = 0; @@ -515,6 +554,12 @@ static int include_forward(struct Context *ctx, struct Header *cur, FILE *out) return 0; } +/** + * mutt_make_attribution - Add "on DATE, PERSON wrote" header + * @param ctx Mailbox + * @param cur Header of email + * @param out File to write to + */ void mutt_make_attribution(struct Context *ctx, struct Header *cur, FILE *out) { if (!Attribution || !out) @@ -528,6 +573,12 @@ void mutt_make_attribution(struct Context *ctx, struct Header *cur, FILE *out) fputc('\n', out); } +/** + * mutt_make_post_indent - Add suffix to replied email text + * @param ctx Mailbox + * @param cur Header of email + * @param out File to write to + */ void mutt_make_post_indent(struct Context *ctx, struct Header *cur, FILE *out) { if (!PostIndentString || !out) @@ -539,6 +590,14 @@ void mutt_make_post_indent(struct Context *ctx, struct Header *cur, FILE *out) fputc('\n', out); } +/** + * include_reply - Generate the reply text for an email + * @param ctx Mailbox + * @param cur Header of email + * @param out File to write to + * @retval 0 Success + * @retval -1 Failure + */ static int include_reply(struct Context *ctx, struct Header *cur, FILE *out) { int cmflags = MUTT_CM_PREFIX | MUTT_CM_DECODE | MUTT_CM_CHARCONV | MUTT_CM_REPLYING; @@ -571,6 +630,15 @@ static int include_reply(struct Context *ctx, struct Header *cur, FILE *out) return 0; } +/** + * default_to - Generate default email addresses + * @param to 'To' address + * @param env Envelope to populate + * @param flags Flags, e.g. #SEND_LIST_REPLY + * @param hmfupto If true, add 'followup-to' address to 'to' address + * @retval 0 Success + * @retval -1 Aborted + */ static int default_to(struct Address **to, struct Envelope *env, int flags, int hmfupto) { char prompt[STRING]; @@ -646,6 +714,14 @@ static int default_to(struct Address **to, struct Envelope *env, int flags, int return 0; } +/** + * mutt_fetch_recips - Generate recpients for a reply email + * @param out Envelope to populate + * @param in Envelope of source email + * @param flags Flags, e.g. SENDLISTREPLY + * @retval 0 Success + * @retval -1 Failure + */ int mutt_fetch_recips(struct Envelope *out, struct Envelope *in, int flags) { struct Address *tmp = NULL; @@ -719,6 +795,10 @@ static void add_message_id(struct ListHead *head, struct Envelope *e) } } +/** + * mutt_fix_reply_recipients - Remove duplicate recipients + * @param env Envelope to fix + */ void mutt_fix_reply_recipients(struct Envelope *env) { if (!Metoo) @@ -742,6 +822,12 @@ void mutt_fix_reply_recipients(struct Envelope *env) } } +/** + * mutt_make_forward_subject - Create a subject for a forwarded email + * @param env Envelope for result + * @param ctx Mailbox + * @param cur Header of email + */ void mutt_make_forward_subject(struct Envelope *env, struct Context *ctx, struct Header *cur) { if (!env) @@ -754,6 +840,11 @@ void mutt_make_forward_subject(struct Envelope *env, struct Context *ctx, struct mutt_str_replace(&env->subject, buffer); } +/** + * mutt_make_misc_reply_headers - Set subject for a reply + * @param env Envelope for result + * @param curenv Envelope of source email + */ void mutt_make_misc_reply_headers(struct Envelope *env, struct Envelope *curenv) { if (!env || !curenv) @@ -772,6 +863,11 @@ void mutt_make_misc_reply_headers(struct Envelope *env, struct Envelope *curenv) env->subject = mutt_str_strdup(EmptySubject); } +/** + * mutt_add_to_reference_headers - Generate references for a reply email + * @param env Envelope for result + * @param curenv Envelope of source email + */ void mutt_add_to_reference_headers(struct Envelope *env, struct Envelope *curenv) { add_references(&env->references, curenv); @@ -784,6 +880,12 @@ void mutt_add_to_reference_headers(struct Envelope *env, struct Envelope *curenv #endif } +/** + * make_reference_headers - Generate reference headers for an email + * @param curenv Envelope of source email + * @param env Envelope for result + * @param ctx Mailbox + */ static void make_reference_headers(struct Envelope *curenv, struct Envelope *env, struct Context *ctx) { @@ -811,6 +913,15 @@ static void make_reference_headers(struct Envelope *curenv, } } +/** + * envelope_defaults - Fill in some defaults for a new email + * @param env Envelope for result + * @param ctx Mailbox + * @param cur Header of email + * @param flags Flags, e.g. #SEND_REPLY + * @retval 0 Success + * @retval -1 Failure + */ static int envelope_defaults(struct Envelope *env, struct Context *ctx, struct Header *cur, int flags) { @@ -1009,13 +1120,16 @@ static int generate_body(FILE *tempfp, struct Header *msg, int flags, return 0; } +/** + * mutt_set_followup_to - Set followup-to field + * @param e Envelope to modify + */ void mutt_set_followup_to(struct Envelope *e) { struct Address *t = NULL; struct Address *from = NULL; - /* - * Only generate the Mail-Followup-To if the user has requested it, and + /* Only generate the Mail-Followup-To if the user has requested it, and * it hasn't already been set */ @@ -1224,6 +1338,8 @@ static int send_message(struct Header *msg) /** * mutt_encode_descriptions - rfc2047 encode the content-descriptions + * @param b Body of email + * @param recurse If true, encode children parts */ void mutt_encode_descriptions(struct Body *b, short recurse) { @@ -1240,6 +1356,7 @@ void mutt_encode_descriptions(struct Body *b, short recurse) /** * decode_descriptions - rfc2047 decode them in case of an error + * @param b MIME parts to decode */ static void decode_descriptions(struct Body *b) { @@ -1254,6 +1371,10 @@ static void decode_descriptions(struct Body *b) } } +/** + * fix_end_of_file - Ensure a file ends with a linefeed + * @param data Name of file to fix + */ static void fix_end_of_file(const char *data) { FILE *fp = mutt_file_fopen(data, "a+"); @@ -1294,6 +1415,15 @@ int mutt_compose_to_sender(struct Header *hdr) return ci_send_message(0, msg, NULL, NULL, NULL); } +/** + * mutt_resend_message - Resend an email + * @param fp File containing email + * @param ctx Mailbox + * @param cur Header of email to resend + * @retval 0 Message was successfully sent + * @retval -1 Message was aborted or an error occurred + * @retval 1 Message was postponed + */ int mutt_resend_message(FILE *fp, struct Context *ctx, struct Header *cur) { struct Header *msg = mutt_header_new(); diff --git a/sendlib.c b/sendlib.c index 9e91470bb..dea071176 100644 --- a/sendlib.c +++ b/sendlib.c @@ -342,6 +342,13 @@ static void encode_8bit(struct FgetConv *fc, FILE *fout) } } +/** + * mutt_write_mime_header - Create a MIME header + * @param a Body part + * @param f File to write to + * @retval 0 Success + * @retval -1 Failure + */ int mutt_write_mime_header(struct Body *a, FILE *f) { fprintf(f, "Content-Type: %s/%s", TYPE(a), a->subtype); @@ -575,6 +582,13 @@ struct ContentState bool was_cr; }; +/** + * update_content_info - Cache some info about an email + * @param info Info about an Attachment + * @param s Info about the Body of an email + * @param buf Buffer for the result + * @param buflen Length of the buffer + */ static void update_content_info(struct Content *info, struct ContentState *s, char *buf, size_t buflen) { @@ -858,6 +872,14 @@ static size_t convert_file_to(FILE *file, const char *fromcode, int ncodes, /** * convert_file_from_to - Convert a file between encodings + * @param[in] file File to read from + * @param[in] fromcodes Charsets to try converting FROM + * @param[in] tocodes Charsets to try converting TO + * @param[out] fromcode From charset selected + * @param[out] tocode To charset selected + * @param[out] info Info about the file + * @retval num Characters converted + * @retval -1 Error (as a size_t) * * Find the first of the fromcodes that gives a valid conversion and the best * charset conversion of the file into one of the tocodes. If successful, set @@ -1301,6 +1323,8 @@ cleanup: /** * set_encoding - determine which Content-Transfer-Encoding to use + * @param[in] b Body of email + * @param[out] info Info about the email */ static void set_encoding(struct Body *b, struct Content *info) { @@ -1629,6 +1653,8 @@ static int get_toplevel_encoding(struct Body *a) /** * check_boundary - check for duplicate boundary + * @param boundary Boundary to look for + * @param b Body parts to check * @retval true if duplicate found */ static bool check_boundary(const char *boundary, struct Body *b) @@ -1696,6 +1722,10 @@ struct Body *mutt_remove_multipart(struct Body *b) /** * mutt_write_address_list - wrapper around mutt_write_address() + * @param addr Address list + * @param fp File to write to + * @param linelen Line length to use + * @param display True if these addresses will be displayed to the user * * So we can handle very large recipient lists without needing a huge temporary * buffer in memory @@ -1782,6 +1812,16 @@ void mutt_write_references(const struct ListHead *r, FILE *f, size_t trim) FREE(&ref); } +/** + * print_val - Add pieces to an email header, wrapping where necessary + * @param fp File to write to + * @param pfx Prefix for headers + * @param value Text to be added + * @param flags Flags, e.g. #CH_DISPLAY + * @param col Column that this text starts at + * @retval 0 Success + * @retval -1 Failure + */ static int print_val(FILE *fp, const char *pfx, const char *value, int flags, size_t col) { while (value && *value) @@ -1816,6 +1856,17 @@ static int print_val(FILE *fp, const char *pfx, const char *value, int flags, si return 0; } +/** + * fold_one_header - Fold one header line + * @param fp File to write to + * @param tag Header key, e.g. "From" + * @param value Header value + * @param pfx Prefix for header + * @param wraplen Column to wrap at + * @param flags Flags, e.g. #CH_DISPLAY + * @retval 0 Success + * @retval -1 Failure + */ static int fold_one_header(FILE *fp, const char *tag, const char *value, const char *pfx, int wraplen, int flags) { @@ -1884,7 +1935,7 @@ static int fold_one_header(FILE *fp, const char *tag, const char *value, * even none) on a line if the trailing spaces are located at our * current line width * XXX this covers ASCII space only, for display we probably - * XXX want something like iswspace() here */ + * want something like iswspace() here */ const char *sp = next; while (*sp && (*sp == ' ' || *sp == '\t')) sp++; @@ -1943,6 +1994,19 @@ static char *unfold_header(char *s) return s; } +/** + * write_one_header - Write out one header line + * @param fp File to write to + * @param pfxw Width of prefix string + * @param max Max width + * @param wraplen Column to wrap at + * @param pfx Prefix for header + * @param start Start of header line + * @param end End of header line + * @param flags Flags, e.g. #CH_DISPLAY + * @retval 0 Success + * @retval -1 Failure + */ static int write_one_header(FILE *fp, int pfxw, int max, int wraplen, const char *pfx, const char *start, const char *end, int flags) { @@ -2022,6 +2086,14 @@ static int write_one_header(FILE *fp, int pfxw, int max, int wraplen, const char /** * mutt_write_one_header - Write one header line to a file + * @param fp File to write to + * @param tag Header key, e.g. "From" + * @param value Header value + * @param pfx Prefix for header + * @param wraplen Column to wrap at + * @param flags Flags, e.g. #CH_DISPLAY + * @retval 0 Success + * @retval -1 Failure * * split several headers into individual ones and call write_one_header * for each one @@ -2105,13 +2177,23 @@ out: return rc; } -/* Note: all RFC2047 encoding should be done outside of this routine, except +/** + * mutt_rfc822_write_header - Write out one RFC822 header line + * @param fp File to write to + * @param env Envelope of email + * @param attach Attachment + * @param mode Mode, see notes below + * @param privacy If true, remove headers that might identify the user + * @retval 0 Success + * @retval -1 Failure + * + * Note: all RFC2047 encoding should be done outside of this routine, except * for the "real name." This will allow this routine to be used more than * once, if necessary. * * Likewise, all IDN processing should happen outside of this routine. * - * mode == 1 => "lite" mode (used for edit_headers) + * mode == 1 => "light" mode (used for edit_headers) * mode == 0 => normal mode. write full header + MIME headers * mode == -1 => write just the envelope info (used for postponing messages) * @@ -2861,6 +2943,16 @@ void mutt_unprepare_envelope(struct Envelope *env) rfc2047_decode(&env->subject); } +/** + * bounce_message - Bounce an email message + * @param fp Handle of message + * @param h Header of email + * @param to Address to bounce to + * @param resent_from Address of new sender + * @param env_from Envelope of original sender + * @retval 0 Success + * @retval -1 Failure + */ static int bounce_message(FILE *fp, struct Header *h, struct Address *to, const char *resent_from, struct Address *env_from) { @@ -2928,6 +3020,14 @@ static int bounce_message(FILE *fp, struct Header *h, struct Address *to, return rc; } +/** + * mutt_bounce_message - Bounce an email message + * @param fp Handle of message + * @param h Header of the email + * @param to Address to bounce to + * @retval 0 Success + * @retval -1 Failure + */ int mutt_bounce_message(FILE *fp, struct Header *h, struct Address *to) { const char *fqdn = mutt_fqdn(true); @@ -3047,6 +3147,14 @@ static void set_noconv_flags(struct Body *b, short flag) /** * mutt_write_multiple_fcc - Handle FCC with multiple, comma separated entries + * @param[in] path Path to mailboxes (comma separated) + * @param[in] hdr Header of the email + * @param[in] msgid Message id + * @param[in] post If true, postpone message + * @param[in] fcc fcc setting to save (postpone only) + * @param[out] finalpath Final path of email + * @retval 0 Success + * @retval -1 Failure */ int mutt_write_multiple_fcc(const char *path, struct Header *hdr, const char *msgid, int post, char *fcc, char **finalpath) @@ -3084,6 +3192,17 @@ int mutt_write_multiple_fcc(const char *path, struct Header *hdr, const char *ms return 0; } +/** + * mutt_write_fcc - Write email to FCC mailbox + * @param[in] path Path to mailbox + * @param[in] hdr Header of the email + * @param[in] msgid Message id + * @param[in] post If true, postpone message + * @param[in] fcc fcc setting to save (postpone only) + * @param[out] finalpath Final path of email + * @retval 0 Success + * @retval -1 Failure + */ int mutt_write_fcc(const char *path, struct Header *hdr, const char *msgid, int post, char *fcc, char **finalpath) { @@ -3251,7 +3370,7 @@ int mutt_write_fcc(const char *path, struct Header *hdr, const char *msgid, mutt_debug(1, "%s: write failed.\n", tempfile); mutt_file_fclose(&tempfp); unlink(tempfile); - mx_msg_commit(&f, msg); /* XXX - really? */ + mx_msg_commit(&f, msg); /* XXX really? */ mx_msg_close(&f, &msg); mx_mbox_close(&f, NULL); goto done; diff --git a/signal.c b/signal.c index e14b21f61..a482683be 100644 --- a/signal.c +++ b/signal.c @@ -46,8 +46,7 @@ static void exit_handler(int sig) curs_set(1); endwin(); /* just to be safe */ - /* - * if sys_siglist is not defined, HAVE_DECL_SYS_SIGLIST will be set to 0 + /* if sys_siglist is not defined, HAVE_DECL_SYS_SIGLIST will be set to 0 * so we must check it with #if and not #ifdef */ #if HAVE_DECL_SYS_SIGLIST diff --git a/smtp.c b/smtp.c index 9e1a866a0..3931224b5 100644 --- a/smtp.c +++ b/smtp.c @@ -245,6 +245,7 @@ static int smtp_data(struct Connection *conn, const char *msgfile) /** * address_uses_unicode - Do any addresses use Unicode + * @param a Address list to check * @retval true if any of the string of addresses use 8-bit characters */ static bool address_uses_unicode(const char *a) @@ -264,6 +265,7 @@ static bool address_uses_unicode(const char *a) /** * addresses_use_unicode - Do any of a list of addresses use Unicode + * @param a Address list to check * @retval true if any use 8-bit characters */ static bool addresses_use_unicode(const struct Address *a)