From: Richard Russon Date: Sun, 16 Jul 2017 19:49:10 +0000 (+0100) Subject: doxygen: convert existing comments X-Git-Tag: neomutt-20170907~66^2 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=5b823ab1362e6c1ca4fe6b0353c65c3d7016f7df;p=neomutt doxygen: convert existing comments Lots of functions were already commented. This commit re-formats the comments to be doxygen-compatible. Despite the size of the commit, no code has changed. --- diff --git a/account.c b/account.c index 6a7418cdd..25f017ee7 100644 --- a/account.c +++ b/account.c @@ -34,7 +34,9 @@ #include "protos.h" #include "url.h" -/* mutt_account_match: compare account info (host/port/user) */ +/** + * mutt_account_match - compare account info (host/port/user) + */ int mutt_account_match(const struct Account *a1, const struct Account *a2) { const char *user = NONULL(Username); @@ -78,7 +80,9 @@ int mutt_account_match(const struct Account *a1, const struct Account *a2) return 1; } -/* mutt_account_fromurl: fill account with information from url. */ +/** + * mutt_account_fromurl - fill account with information from url + */ int mutt_account_fromurl(struct Account *account, struct CissUrl *url) { /* must be present */ @@ -106,10 +110,13 @@ int mutt_account_fromurl(struct Account *account, struct CissUrl *url) return 0; } -/* mutt_account_tourl: fill URL with info from account. The URL information - * is a set of pointers into account - don't free or edit account until - * you've finished with url (make a copy of account if you need it for - * a while). */ +/** + * mutt_account_tourl - fill URL with info from account + * + * The URL information is a set of pointers into account - don't free or edit + * account until you've finished with url (make a copy of account if you need + * it for a while). + */ void mutt_account_tourl(struct Account *account, struct CissUrl *url) { url->scheme = U_UNKNOWN; @@ -167,7 +174,9 @@ void mutt_account_tourl(struct Account *account, struct CissUrl *url) url->pass = account->pass; } -/* mutt_account_getuser: retrieve username into Account, if necessary */ +/** + * mutt_account_getuser - retrieve username into Account, if necessary + */ int mutt_account_getuser(struct Account *account) { char prompt[SHORT_STRING]; @@ -231,7 +240,9 @@ int mutt_account_getlogin(struct Account *account) return 0; } -/* mutt_account_getpass: fetch password into Account, if necessary */ +/** + * mutt_account_getpass - fetch password into Account, if necessary + */ int mutt_account_getpass(struct Account *account) { char prompt[SHORT_STRING]; diff --git a/alias.c b/alias.c index ef8c87306..ede00b001 100644 --- a/alias.c +++ b/alias.c @@ -158,7 +158,9 @@ void mutt_expand_aliases_env(struct Envelope *env) } -/* +/** + * write_safe_address - Defang malicious email addresses + * * if someone has an address like * From: Michael `/bin/rm -f ~` Elkins * and the user creates an alias for this, Mutt could wind up executing @@ -238,9 +240,11 @@ static void recode_buf(char *buf, size_t buflen) FREE(&s); } -/* - * Sanity-check an alias name: Only characters which are non-special to both - * the RFC 822 and the mutt configuration parser are permitted. +/** + * check_alias_name - Sanity-check an alias name + * + * Only characters which are non-special to both the RFC 822 and the mutt + * configuration parser are permitted. */ int check_alias_name(const char *s, char *dest, size_t destlen) { @@ -451,9 +455,8 @@ fseek_err: return; } -/* - * This routine looks to see if the user has an alias defined for the given - * address. +/** + * alias_reverse_lookup - Does the user have an alias for the given address */ struct Address *alias_reverse_lookup(struct Address *a) { @@ -498,7 +501,8 @@ void mutt_alias_delete_reverse(struct Alias *t) } } -/* alias_complete() -- alias completion routine +/** + * mutt_alias_complete - alias completion routine * * given a partial alias, this routine attempts to fill in the alias * from the alias list as much as possible. if given empty search string @@ -619,7 +623,10 @@ static bool string_is_address(const char *str, const char *u, const char *d) return false; } -/* returns true if the given address belongs to the user. */ +/** + * mutt_addr_is_user - Does the address belong to the user + * @return true if the given address belongs to the user + */ bool mutt_addr_is_user(struct Address *addr) { const char *fqdn = NULL; diff --git a/attach.c b/attach.c index 7d4377bc2..4d865bcfb 100644 --- a/attach.c +++ b/attach.c @@ -91,7 +91,12 @@ int mutt_get_tmp_attachment(struct Body *a) } -/* return 1 if require full screen redraw, 0 otherwise */ +/** + * mutt_compose_attachment - Create an attachment + * @return + * * 1 if require full screen redraw + * * 0 otherwise + */ int mutt_compose_attachment(struct Body *a) { char type[STRING]; @@ -336,7 +341,12 @@ void mutt_check_lookup_list(struct Body *b, char *type, int len) } } -/* returns -1 on error, 0 or the return code from mutt_do_pager() on success */ +/** + * mutt_view_attachment - View an attachment + * @return + * * -1 on error + * * 0 or the return code from mutt_do_pager() on success + */ int mutt_view_attachment(FILE *fp, struct Body *a, int flag, struct Header *hdr, struct AttachPtr **idx, short idxlen) { @@ -608,7 +618,12 @@ return_error: return rc; } -/* returns 1 on success, 0 on error */ +/** + * mutt_pipe_attachment - Pipe an attachment to a command + * @return + * * 1 on success + * * 0 on error + */ int mutt_pipe_attachment(FILE *fp, struct Body *b, const char *path, char *outfile) { pid_t thepid; @@ -711,7 +726,12 @@ static FILE *save_attachment_open(char *path, int flags) return safe_fopen(path, "w"); } -/* returns 0 on success, -1 on error */ +/** + * mutt_save_attachment - Save an attachment + * @return + * * 0 on success + * * -1 on error + */ int mutt_save_attachment(FILE *fp, struct Body *m, char *path, int flags, struct Header *hdr) { if (!m) @@ -825,7 +845,10 @@ int mutt_save_attachment(FILE *fp, struct Body *m, char *path, int flags, struct return 0; } -/* returns 0 on success, -1 on error */ +/** + * mutt_decode_save_attachment - Decode, then save an attachment + * @return 0 on success, -1 on error + */ int mutt_decode_save_attachment(FILE *fp, struct Body *m, char *path, int displaying, int flags) { struct State s; @@ -911,7 +934,10 @@ int mutt_decode_save_attachment(FILE *fp, struct Body *m, char *path, int displa return ret; } -/* Ok, the difference between send and receive: +/** + * mutt_print_attachment - Print out an attachment + * + * Ok, the difference between send and receive: * recv: Body->filename is a suggested name, and Context|Header points * to the attachment in mailbox which is encoded * send: Body->filename points to the un-encoded file which contains the diff --git a/browser.c b/browser.c index ac9d3af87..0f27472d3 100644 --- a/browser.c +++ b/browser.c @@ -105,7 +105,11 @@ struct Folder static char OldLastDir[_POSIX_PATH_MAX] = ""; static char LastDir[_POSIX_PATH_MAX] = ""; -/* Frees up the memory allocated for the local-global variables. */ +/** + * destroy_state - Free the BrowserState + * + * Frees up the memory allocated for the local-global variables. + */ static void destroy_state(struct BrowserState *state) { for (int c = 0; c < state->entrylen; c++) @@ -193,9 +197,12 @@ static int browser_compare_count_new(const void *a, const void *b) return ((BrowserSort & SORT_REVERSE) ? -r : r); } -/* 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 sort method. +/** + * browser_compare - Sort the items in the browser + * + * 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 + * sort method. */ static int browser_compare(const void *a, const void *b) { @@ -225,8 +232,11 @@ static int browser_compare(const void *a, const void *b) } } -/* Call to qsort using browser_compare function. Some - * specific sort methods are not used via NNTP. +/** + * browser_sort - Sort the entries in the browser + * + * Call to qsort using browser_compare function. + * Some specific sort methods are not used via NNTP. */ static void browser_sort(struct BrowserState *state) { @@ -645,7 +655,9 @@ static void init_state(struct BrowserState *state, struct Menu *menu) menu->data = state->entry; } -/* get list of all files/newsgroups with mask */ +/** + * examine_directory - get list of all files/newsgroups with mask + */ static int examine_directory(struct Menu *menu, struct BrowserState *state, char *d, const char *prefix) { @@ -768,7 +780,9 @@ static int examine_vfolders(struct Menu *menu, struct BrowserState *state) } #endif -/* get list of mailboxes/subscribed newsgroups */ +/** + * examine_mailboxes - Get list of mailboxes/subscribed newsgroups + */ static int examine_mailboxes(struct Menu *menu, struct BrowserState *state) { struct stat s; @@ -907,9 +921,11 @@ static void vfolder_entry(char *s, size_t slen, struct Menu *menu, int num) } #endif -/* - * This function takes a menu and a state and defines the current - * entry that should be highlighted. +/** + * browser_highlight_default - Decide which browser item should be highlighted + * + * This function takes a menu and a state and defines the current entry that + * should be highlighted. */ static void browser_highlight_default(struct BrowserState *state, struct Menu *menu) { @@ -1028,11 +1044,12 @@ static int file_tag(struct Menu *menu, int n, int m) return ff->tagged - ot; } -/* Public function +/** + * mutt_browser_select_dir - Remember the last directory selected * - * 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 directory/file which is a maildir/mbox. + * 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 + * directory/file which is a maildir/mbox. * * We could check if the sort method is appropriate with this feature. */ diff --git a/buffer.c b/buffer.c index de9f0a210..a23ec76f6 100644 --- a/buffer.c +++ b/buffer.c @@ -30,7 +30,9 @@ #include "lib.h" #include "myvar.h" -/* creates and initializes a Buffer */ +/** + * mutt_buffer_new - creates and initializes a Buffer + */ struct Buffer *mutt_buffer_new(void) { struct Buffer *b = NULL; @@ -42,14 +44,18 @@ struct Buffer *mutt_buffer_new(void) return b; } -/* initialize a new Buffer */ +/** + * mutt_buffer_init - initialize a new Buffer + */ struct Buffer *mutt_buffer_init(struct Buffer *b) { memset(b, 0, sizeof(struct Buffer)); return b; } -/* +/** + * mutt_buffer_from - Create Buffer from an existing Buffer + * * Creates and initializes a Buffer*. If passed an existing Buffer*, * just initializes. Frees anything already in the buffer. Copies in * the seed string. @@ -121,9 +127,13 @@ int mutt_buffer_printf(struct Buffer *buf, const char *fmt, ...) return len; } -/* dynamically grows a Buffer to accommodate s, in increments of 128 bytes. - * Always one byte bigger than necessary for the null terminator, and - * the buffer is always null-terminated */ +/** + * mutt_buffer_add - Add a string to a Buffer, expanding it if necessary + * + * dynamically grows a Buffer to accommodate s, in increments of 128 bytes. + * Always one byte bigger than necessary for the null terminator, and the + * buffer is always null-terminated + */ static void mutt_buffer_add(struct Buffer *buf, const char *s, size_t len) { if (!buf || !s) diff --git a/buffy.c b/buffy.c index e3e747cf4..871314f65 100644 --- a/buffy.c +++ b/buffy.c @@ -57,8 +57,10 @@ time_t BuffyDoneTime = 0; /* last time we knew for sure how much mail there was. static short BuffyCount = 0; /* how many boxes with new mail */ static short BuffyNotify = 0; /* # of unnotified new boxes */ -/* Find the last message in the file. - * upon success return 0. If no message found - return -1 */ +/** + * fseek_last_message - Find the last message in the file + * @return 0 on success, -1 if no message found + */ static int fseek_last_message(FILE *f) { LOFF_T pos; @@ -104,7 +106,10 @@ static int fseek_last_message(FILE *f) return -1; } -/* Return 1 if the last message is new */ +/** + * test_last_status_new - Is the last message new + * @return 1 if the last message is new + */ static int test_last_status_new(FILE *f) { struct Header *hdr = NULL; @@ -441,7 +446,9 @@ static void buffy_check(struct Buffy *tmp, struct stat *contex_sb, int check_sta BuffyNotify++; } -/* fetch buffy object for given path, if present */ +/** + * buffy_get - fetch buffy object for given path, if present + */ static struct Buffy *buffy_get(const char *path) { struct Buffy *cur = NULL; @@ -669,7 +676,10 @@ int mutt_parse_unmailboxes(struct Buffer *path, struct Buffer *s, return 0; } -/* Check all Incoming for new mail and total/new/flagged messages +/** + * mutt_buffy_check - Check all Incoming for new mail + * + * Check all Incoming for new mail and total/new/flagged messages * force: if true, ignore BuffyTimeout and check for new mail anyway */ int mutt_buffy_check(bool force) diff --git a/charset.c b/charset.c index 071809f7c..aa22119ed 100644 --- a/charset.c +++ b/charset.c @@ -219,8 +219,12 @@ void mutt_set_langinfo_charset(void) Charset = safe_strdup("iso-8859-1"); } -/* this first ties off any charset extension such as //TRANSLIT, - canonicalizes the charset and re-adds the extension */ +/** + * mutt_canonical_charset - Canonicalise the charset of a string + * + * this first ties off any charset extension such as //TRANSLIT, + * canonicalizes the charset and re-adds the extension + */ void mutt_canonical_charset(char *dest, size_t dlen, const char *name) { char *p = NULL, *ext = NULL; @@ -305,7 +309,9 @@ char *mutt_get_default_charset(void) return strcpy(fcharset, "us-ascii"); } -/* +/** + * mutt_iconv_open - Set up iconv for conversions + * * Like iconv_open, but canonicalises the charsets, applies charset-hooks, * recanonicalises, and finally applies iconv-hooks. Parameter flags=0 skips * charset-hooks, while MUTT_ICONV_HOOK_FROM applies them to fromcode. Callers @@ -350,7 +356,9 @@ iconv_t mutt_iconv_open(const char *tocode, const char *fromcode, int flags) } -/* +/** + * mutt_iconv - Change the encoding of a string + * * Like iconv, but keeps going even when the input is invalid * If you're supplying inrepls, the source charset should be stateless; * if you're supplying an outrepl, the target charset should be. @@ -421,11 +429,11 @@ size_t mutt_iconv(iconv_t cd, ICONV_CONST char **inbuf, size_t *inbytesleft, } -/* - * Convert a string - * Used in rfc2047.c, rfc2231.c, crypt_gpgme.c, mutt_idna.c, and more. - * Parameter flags is given as-is to mutt_iconv_open(). See there - * for its meaning and usage policy. +/** + * mutt_convert_string - Convert a string between encodings + * + * Parameter flags is given as-is to mutt_iconv_open(). + * See there for its meaning and usage policy. */ int mutt_convert_string(char **ps, const char *from, const char *to, int flags) { @@ -503,9 +511,11 @@ struct FgetConvNot iconv_t cd; }; -/* - * Parameter flags is given as-is to mutt_iconv_open(). See there for its - * meaning and usage policy. +/** + * fgetconv_open - Open a file and convert its encoding + * + * Parameter flags is given as-is to mutt_iconv_open(). + * See there for its meaning and usage policy. */ FGETCONV *fgetconv_open(FILE *file, const char *from, const char *to, int flags) { diff --git a/color.c b/color.c index e6cd6c9bd..1e3f430dc 100644 --- a/color.c +++ b/color.c @@ -505,8 +505,12 @@ static void do_uncolor(struct Buffer *buf, struct Buffer *s, } while (MoreArgs(s)); } -/* usage: uncolor index pattern [pattern...] - * unmono index pattern [pattern...] +/** + * _mutt_parse_uncolor - Parse an 'uncolor' command + * + * usage: + * * uncolor index pattern [pattern...] + * * unmono index pattern [pattern...] */ static int _mutt_parse_uncolor(struct Buffer *buf, struct Buffer *s, unsigned long data, struct Buffer *err, short parse_uncolor) @@ -833,8 +837,11 @@ static int fgbgattr_to_color(int fg, int bg, int attr) return attr; } -/* usage: color [ ] - * mono [ ] +/** + * _mutt_parse_color - Parse a "color" command + * + * usage: color OBJECT FG BG [ REGEXP ] + * mono OBJECT ATTR [ REGEXP ] */ static int _mutt_parse_color(struct Buffer *buf, struct Buffer *s, struct Buffer *err, parser_callback_t callback, bool dry_run) diff --git a/commands.c b/commands.c index def931586..4fb6f8db0 100644 --- a/commands.c +++ b/commands.c @@ -387,7 +387,11 @@ static void pipe_msg(struct Header *h, FILE *fp, int decode, int print) } -/* the following code is shared between printing and piping */ +/** + * _mutt_pipe_message - Pipe message to a command + * + * The following code is shared between printing and piping. + */ static int _mutt_pipe_message(struct Header *h, char *cmd, int decode, int print, int split, char *sep) { @@ -595,7 +599,9 @@ int mutt_select_sort(int reverse) return (Sort != method ? 0 : -1); /* no need to resort if it's the same */ } -/* invoke a command in a subshell */ +/** + * mutt_shell_escape - invoke a command in a subshell + */ void mutt_shell_escape(void) { char buf[LONG_STRING]; @@ -617,7 +623,9 @@ void mutt_shell_escape(void) } } -/* enter a mutt command */ +/** + * mutt_enter_command - enter a mutt command + */ void mutt_enter_command(void) { struct Buffer err, token; @@ -735,7 +743,12 @@ int _mutt_save_message(struct Header *h, struct Context *ctx, int delete, int de return 0; } -/* returns 0 if the copy/save was successful, or -1 on error/abort */ +/** + * mutt_save_message - Save an email + * @return + * * 0 if the copy/save was successful + * * -1 on error/abort + */ int mutt_save_message(struct Header *h, int delete, int decode, int decrypt) { int i, need_buffy_cleanup; diff --git a/compose.c b/compose.c index 7f81c5d93..b37765f22 100644 --- a/compose.c +++ b/compose.c @@ -192,11 +192,13 @@ static void calc_header_width_padding(int idx, const char *header, int calc_max) } -/* The padding needed for each header is strlen() + max_width - strwidth(). +/** + * init_header_padding - Calculate how much padding the compose table will need + * + * The padding needed for each header is strlen() + max_width - strwidth(). * - * calc_header_width_padding sets each entry in HeaderPadding to - * strlen - width. Then, afterwards, we go through and add max_width - * to each entry. + * calc_header_width_padding sets each entry in HeaderPadding to strlen - + * width. Then, afterwards, we go through and add max_width to each entry. */ static void init_header_padding(void) { @@ -628,13 +630,13 @@ static unsigned long cum_attachs_size(struct Menu *menu) return s; } -/* - * compose_format_str() +/** + * compose_format_str - Format strings like printf() * - * %a = total number of attachments - * %h = hostname [option] - * %l = approx. length of current message (in bytes) - * %v = Mutt version + * * \%a Total number of attachments + * * \%h Hostname [option] + * * \%l Approx. length of current message (in bytes) + * * \%v Mutt version * * This function is similar to status_format_str(). Look at that function for * help when modifying this function. @@ -695,11 +697,12 @@ static void compose_status_line(char *buf, size_t buflen, size_t col, int cols, mutt_FormatString(buf, buflen, col, cols, p, compose_format_str, (unsigned long) menu, 0); } -/* return values: - * - * 1 message should be postponed - * 0 normal exit - * -1 abort message +/** + * mutt_compose_menu - Allow the user to edit the message envelope + * @return + * * 1 Message should be postponed + * * 0 Normal exit + * * -1 Abort message */ int mutt_compose_menu(struct Header *msg, /* structure for new message */ char *fcc, /* where to save a copy of the message */ diff --git a/copy.c b/copy.c index 54f681390..9cca5164c 100644 --- a/copy.c +++ b/copy.c @@ -54,9 +54,12 @@ static int address_header_decode(char **str); static int copy_delete_attach(struct Body *b, FILE *fpin, FILE *fpout, char *date); -/* Ok, the only reason for not merging this with mutt_copy_header() - * below is to avoid creating a Header structure in message_handler(). - * Also, this one will wrap headers much more aggressively than the other one. +/** + * mutt_copy_hdr - Copy header from one file to another + * + * Ok, the only reason for not merging this with mutt_copy_header() below is to + * avoid creating a Header structure in message_handler(). Also, this one will + * wrap headers much more aggressively than the other one. */ int mutt_copy_hdr(FILE *in, FILE *out, LOFF_T off_start, LOFF_T off_end, int flags, const char *prefix) @@ -345,28 +348,31 @@ int mutt_copy_hdr(FILE *in, FILE *out, LOFF_T off_start, LOFF_T off_end, return 0; } -/* flags - CH_DECODE RFC2047 header decoding - CH_FROM retain the "From " message separator - CH_FORCE_FROM give CH_FROM precedence over CH_WEED - CH_MIME ignore MIME fields - CH_NOLEN don't write Content-Length: and Lines: - CH_NONEWLINE don't output a newline after the header - CH_NOSTATUS ignore the Status: and X-Status: - CH_PREFIX quote header with $indent_string - CH_REORDER output header in order specified by `hdr_order' - CH_TXTPLAIN generate text/plain MIME headers [hack alert.] - CH_UPDATE write new Status: and X-Status: - CH_UPDATE_LEN write new Content-Length: and Lines: - CH_XMIT ignore Lines: and Content-Length: - CH_WEED do header weeding - CH_NOQFROM ignore ">From " line - CH_UPDATE_IRT update the In-Reply-To: header - CH_UPDATE_REFS update the References: header - CH_VIRTUAL write virtual header lines too - - prefix - string to use if CH_PREFIX is set +/** + * mutt_copy_header - Copy email header + * + * flags: + * * #CH_DECODE RFC2047 header decoding + * * #CH_FROM retain the "From " message separator + * * #CH_FORCE_FROM give CH_FROM precedence over CH_WEED + * * #CH_MIME ignore MIME fields + * * #CH_NOLEN don't write Content-Length: and Lines: + * * #CH_NONEWLINE don't output a newline after the header + * * #CH_NOSTATUS ignore the Status: and X-Status: + * * #CH_PREFIX quote header with $indent_string + * * #CH_REORDER output header in order specified by `hdr_order' + * * #CH_TXTPLAIN generate text/plain MIME headers [hack alert.] + * * #CH_UPDATE write new Status: and X-Status: + * * #CH_UPDATE_LEN write new Content-Length: and Lines: + * * #CH_XMIT ignore Lines: and Content-Length: + * * #CH_WEED do header weeding + * * #CH_NOQFROM ignore ">From " line + * * #CH_UPDATE_IRT update the In-Reply-To: header + * * #CH_UPDATE_REFS update the References: header + * * #CH_VIRTUAL write virtual header lines too + * + * prefix + * * string to use if CH_PREFIX is set */ int mutt_copy_header(FILE *in, struct Header *h, FILE *out, int flags, const char *prefix) { @@ -487,7 +493,11 @@ int mutt_copy_header(FILE *in, struct Header *h, FILE *out, int flags, const cha return 0; } -/* Count the number of lines and bytes to be deleted in this body */ +/** + * count_delete_lines - Count lines to be deleted in this email body + * + * Count the number of lines and bytes to be deleted in this body + */ static int count_delete_lines(FILE *fp, struct Body *b, LOFF_T *length, size_t datelen) { int dellines = 0; @@ -519,22 +529,23 @@ static int count_delete_lines(FILE *fp, struct Body *b, LOFF_T *length, size_t d return dellines; } -/* make a copy of a message +/** + * _mutt_copy_message - make a copy of a message + * @param fpout Where to write output + * @param fpin Where to get input + * @param hdr Header of message being copied + * @param body Structure of message being copied + * @param flags See below + * @param chflags Flags to mutt_copy_header() * - * fpout where to write output - * fpin where to get input - * hdr header of message being copied - * body structure of message being copied - * flags - * MUTT_CM_NOHEADER don't copy header - * MUTT_CM_PREFIX quote header and body - * MUTT_CM_DECODE decode message body to text/plain - * MUTT_CM_DISPLAY displaying output to the user - * MUTT_CM_PRINTING printing the message - * MUTT_CM_UPDATE update structures in memory after syncing - * MUTT_CM_DECODE_PGP used for decoding PGP messages - * MUTT_CM_CHARCONV perform character set conversion - * chflags flags to mutt_copy_header() + * * #MUTT_CM_NOHEADER don't copy header + * * #MUTT_CM_PREFIX quote header and body + * * #MUTT_CM_DECODE decode message body to text/plain + * * #MUTT_CM_DISPLAY displaying output to the user + * * #MUTT_CM_PRINTING printing the message + * * #MUTT_CM_UPDATE update structures in memory after syncing + * * #MUTT_CM_DECODE_PGP used for decoding PGP messages + * * #MUTT_CM_CHARCONV perform character set conversion */ int _mutt_copy_message(FILE *fpout, FILE *fpin, struct Header *hdr, struct Body *body, int flags, int chflags) @@ -738,8 +749,12 @@ int _mutt_copy_message(FILE *fpout, FILE *fpin, struct Header *hdr, return rc; } -/* should be made to return -1 on fatal errors, and 1 on non-fatal errors - * like partial decode, where it is worth displaying as much as possible */ +/** + * mutt_copy_message - Copy a message + * + * should be made to return -1 on fatal errors, and 1 on non-fatal errors + * like partial decode, where it is worth displaying as much as possible + */ int mutt_copy_message(FILE *fpout, struct Context *src, struct Header *hdr, int flags, int chflags) { @@ -758,15 +773,16 @@ int mutt_copy_message(FILE *fpout, struct Context *src, struct Header *hdr, return r; } -/* appends a copy of the given message to a mailbox - * - * dest destination mailbox - * fpin where to get input - * src source mailbox - * hdr message being copied - * body structure of message being copied - * flags mutt_copy_message() flags - * chflags mutt_copy_header() flags +/** + * _mutt_append_message - appends a copy of the given message to a mailbox + * @param dest destination mailbox + * @param fpin where to get input + * @param src source mailbox + * @param hdr message being copied + * @param body structure of message being copied + * @param flags mutt_copy_message() flags + * @param chflags mutt_copy_header() flags + * @return 0 on success, -1 on error */ static int _mutt_append_message(struct Context *dest, FILE *fpin, struct Context *src, struct Header *hdr, @@ -812,12 +828,15 @@ int mutt_append_message(struct Context *dest, struct Context *src, return r; } -/* +/** + * copy_delete_attach - Copy a message, deleting marked attachments + * @return + * * 0 on success + * * -1 on failure + * * This function copies a message body, while deleting _in_the_copy_ * any attachments which are marked for deletion. * Nothing is changed in the original message -- this is left to the caller. - * - * The function will return 0 on success and -1 on failure. */ static int copy_delete_attach(struct Body *b, FILE *fpin, FILE *fpout, char *date) { @@ -864,11 +883,12 @@ static int copy_delete_attach(struct Body *b, FILE *fpin, FILE *fpout, char *dat return 0; } -/* - * This function is the equivalent of mutt_write_address_list(), - * but writes to a buffer instead of writing to a stream. - * mutt_write_address_list could be re-used if we wouldn't store - * all the decoded headers in a huge array, first. +/** + * format_address_header - Write address headers to a buffer + * + * This function is the equivalent of mutt_write_address_list(), but writes to + * a buffer instead of writing to a stream. mutt_write_address_list could be + * re-used if we wouldn't store all the decoded headers in a huge array, first. * * XXX - fix that. */ diff --git a/curs_lib.c b/curs_lib.c index 7da43d499..a20d2b076 100644 --- a/curs_lib.c +++ b/curs_lib.c @@ -102,10 +102,13 @@ void mutt_refresh(void) refresh(); } -/* Make sure that the next refresh does a full refresh. This could be - optimized by not doing it at all if DISPLAY is set as this might - indicate that a GUI based pinentry was used. Having an option to - customize this is of course the Mutt way. */ +/** + * mutt_need_hard_redraw - Force a hard refresh + * + * Make sure that the next refresh does a full refresh. This could be + * optimized by not doing it at all if DISPLAY is set as this might indicate + * that a GUI based pinentry was used. Having an option to customize this is + * of course the Mutt way. */ void mutt_need_hard_redraw(void) { keypad(stdscr, true); @@ -375,7 +378,11 @@ int mutt_yesorno(const char *msg, int def) return def; } -/* this function is called when the user presses the abort key */ +/** + * mutt_query_exit - Ask the user if they want to leave Mutt + * + * This function is called when the user presses the abort key. + */ void mutt_query_exit(void) { mutt_flushinp(); @@ -741,8 +748,10 @@ int mutt_window_mvprintw(struct MuttWindow *win, int row, int col, const char *f return rv; } -/* Assumes the cursor has already been positioned within the - * window. +/** + * mutt_window_clrtoeol - Clear to the end of the line + * + * Assumes the cursor has already been positioned within the window. */ void mutt_window_clrtoeol(struct MuttWindow *win) { @@ -769,9 +778,11 @@ void mutt_window_clearline(struct MuttWindow *win, int row) mutt_window_clrtoeol(win); } -/* Assumes the current position is inside the window. - * Otherwise it will happily return negative or values outside - * the window boundaries +/** + * mutt_window_getyx - Get the cursor position in the window + * + * Assumes the current position is inside the window. Otherwise it will + * happily return negative or values outside the window boundaries */ void mutt_window_getyx(struct MuttWindow *win, int *y, int *x) { @@ -954,7 +965,9 @@ void mutt_unget_string(char *s) } } -/* +/** + * mutt_push_macro_event - Add the character/operation to the macro buffer + * * Adds the ch/op to the macro buffer. * This should be used for macros, push, and exec commands only. */ @@ -981,9 +994,13 @@ void mutt_flush_macro_to_endcond(void) } } -/* Normally, OP_END_COND should only be in the MacroEvent buffer. - * km_error_key() (ab)uses OP_END_COND as a barrier in the unget - * buffer, and calls this function to flush. */ +/** + * mutt_flush_unget_to_endcond - Clear entries from UngetKeyEvents + * + * Normally, OP_END_COND should only be in the MacroEvent buffer. + * km_error_key() (ab)uses OP_END_COND as a barrier in the unget buffer, and + * calls this function to flush. + */ void mutt_flush_unget_to_endcond(void) { while (UngetCount > 0) @@ -1001,10 +1018,12 @@ void mutt_flushinp(void) } #if (defined(USE_SLANG_CURSES) || defined(HAVE_CURS_SET)) -/* The argument can take 3 values: - * -1: restore the value of the last call - * 0: make the cursor invisible - * 1: make the cursor visible +/** + * mutt_curs_set - Set the cursor position + * @param cursor + * * -1: restore the value of the last call + * * 0: make the cursor invisible + * * 1: make the cursor visible */ void mutt_curs_set(int cursor) { @@ -1104,8 +1123,8 @@ int mutt_multi_choice(char *prompt, char *letters) return choice; } -/* - * addwch would be provided by an up-to-date curses library +/** + * mutt_addwch - addwch would be provided by an up-to-date curses library */ int mutt_addwch(wchar_t wc) { @@ -1121,12 +1140,12 @@ int mutt_addwch(wchar_t wc) return addstr(buf); } - -/* - * This formats a string, a bit like - * snprintf (dest, destlen, "%-*.*s", min_width, max_width, s), - * except that the widths refer to the number of character cells - * when printed. +/** + * mutt_format_string - Format a string, like snprintf() + * + * This formats a string, a bit like snprintf (dest, destlen, "%-*.*s", + * min_width, max_width, s), except that the widths refer to the number of + * character cells when printed. */ void mutt_format_string(char *dest, size_t destlen, int min_width, int max_width, int justify, char m_pad_char, const char *s, size_t n, int arboreal) @@ -1228,7 +1247,9 @@ void mutt_format_string(char *dest, size_t destlen, int min_width, int max_width } } -/* +/** + * format_s_x - Format a string like snprintf() + * * This formats a string rather like * snprintf (fmt, sizeof (fmt), "%%%ss", prefix); * snprintf (dest, destlen, fmt, s); @@ -1270,9 +1291,10 @@ void mutt_format_s_tree(char *dest, size_t destlen, const char *prefix, const ch format_s_x(dest, destlen, prefix, s, 1); } -/* - * mutt_paddstr (n, s) is almost equivalent to - * mutt_format_string (bigbuf, big, n, n, FMT_LEFT, ' ', s, big, 0), addstr (bigbuf) +/** + * mutt_paddstr - Display a string on screen, padded if necessary + * @param n Final width of field + * @param s String to display */ void mutt_paddstr(int n, const char *s) { @@ -1307,8 +1329,17 @@ void mutt_paddstr(int n, const char *s) addch(' '); } -/* See how many bytes to copy from string so it's at most maxlen bytes - * long and maxwid columns wide */ +/** + * mutt_wstr_trunc - Work out how to truncate a widechar string + * @param[in] src String to measute + * @param[in] maxlen Maximum length of string in bytes + * @param[in] maxwid Maximum width in screen columns + * @param[out] width Save the truncated screen column width + * @return number of bytes to use + * + * See how many bytes to copy from string so it's at most maxlen bytes long and + * maxwid columns wide + */ size_t mutt_wstr_trunc(const char *src, size_t maxlen, size_t maxwid, size_t *width) { wchar_t wc; diff --git a/curs_main.c b/curs_main.c index e0f707ff8..904d977a0 100644 --- a/curs_main.c +++ b/curs_main.c @@ -234,7 +234,10 @@ static int ci_previous_undeleted(int msgno) return -1; } -/* Return the index of the first new message, or failing that, the first +/** + * ci_first_message - Get index of first new message + * + * Return the index of the first new message, or failing that, the first * unread message. */ static int ci_first_message(void) @@ -270,7 +273,11 @@ static int ci_first_message(void) return 0; } -/* This should be in mx.c, but it only gets used here. */ +/** + * mx_toggle_write - Toggle the mailbox's readonly flag + * + * This should be in mx.c, but it only gets used here. + */ static int mx_toggle_write(struct Context *ctx) { if (!ctx) @@ -519,7 +526,11 @@ static int main_change_folder(struct Menu *menu, int op, char *buf, size_t bufsz } -/* terminal status capability check. terminfo must have been initialized. */ +/** + * mutt_ts_capability - Check terminal capabilities + * + * terminal status capability check. terminfo must have been initialized. + */ bool mutt_ts_capability(void) { char *term = getenv("TERM"); @@ -885,7 +896,10 @@ static void index_menu_redraw(struct Menu *menu) menu->redraw = 0; } -/* This function handles the message index window as well as commands returned +/** + * mutt_index_menu - Display a list of emails + * + * This function handles the message index window as well as commands returned * from the pager (MENU_PAGER). */ int mutt_index_menu(void) diff --git a/date.c b/date.c index edc659c40..7c958a827 100644 --- a/date.c +++ b/date.c @@ -24,8 +24,12 @@ #include #include -/* returns the seconds east of UTC given `g' and its corresponding gmtime() - representation */ +/** + * compute_tz - Calculate the number of seconds east of UTC + * + * returns the seconds east of UTC given `g' and its corresponding gmtime() + * representation + */ static time_t compute_tz(time_t g, struct tm *utc) { struct tm *lt = localtime(&g); @@ -47,7 +51,10 @@ static time_t compute_tz(time_t g, struct tm *utc) return t; } -/* Returns the local timezone in seconds east of UTC for the time t, +/** + * mutt_local_tz - Calculate the local timezone in seconds east of UTC + * + * Returns the local timezone in seconds east of UTC for the time t, * or for the current time if t is zero. */ time_t mutt_local_tz(time_t t) @@ -69,8 +76,12 @@ time_t mutt_local_tz(time_t t) #define TM_YEAR_MAX \ (1970 + (((((TIME_T_MAX - 59) / 60) - 59) / 60) - 23) / 24 / 366) -/* converts struct tm to time_t, but does not take the local timezone into - account unless ``local'' is nonzero */ +/** + * mutt_mktime - Convert `struct tm` to `time_t` + * + * converts struct tm to time_t, but does not take the local timezone into + * account unless ``local'' is nonzero + */ time_t mutt_mktime(struct tm *t, int local) { time_t g; @@ -116,7 +127,11 @@ time_t mutt_mktime(struct tm *t, int local) return g; } -/* Return 1 if month is February of leap year, else 0 */ +/** + * is_leap_year_feb - Is it a leap year + * @param tm Date to be tested + * @return true if it's a leap year + */ static int is_leap_year_feb(struct tm *tm) { if (tm->tm_mon == 1) diff --git a/doc/makedoc.c b/doc/makedoc.c index e6f4e4dd3..59e1fcf18 100644 --- a/doc/makedoc.c +++ b/doc/makedoc.c @@ -765,7 +765,9 @@ static int commit_buff(char *buff, char **d, FILE *out, int docstat) ** This is used to protect indentations in tables. **/ -/* reduce CDATA to ID */ +/** + * sgml_id_fputs - reduce CDATA to ID + */ static int sgml_id_fputs(const char *s, FILE *out) { char id; diff --git a/edit.c b/edit.c index f71f58d24..5fd43fdfc 100644 --- a/edit.c +++ b/edit.c @@ -240,8 +240,10 @@ static void be_print_header(struct Envelope *env) addch('\n'); } -/* args: - * force override the $ask* vars (used for the ~h command) +/** + * be_edit_header - Edit the message headers + * @param e Message headers + * @param force override the $ask* vars (used for the ~h command) */ static void be_edit_header(struct Envelope *e, int force) { diff --git a/enter.c b/enter.c index bf8a817fe..6d7b207d9 100644 --- a/enter.c +++ b/enter.c @@ -173,7 +173,9 @@ static size_t my_mbstowcs(wchar_t **pwbuf, size_t *pwbuflen, size_t i, char *buf return i; } -/* +/** + * replace_part - Search and replace on a buffer + * * Replace part of the wchar_t buffer, from FROM to CURPOS, by BUF. */ static void replace_part(struct EnterState *state, size_t from, char *buf) diff --git a/filter.c b/filter.c index d3538141d..bd5c36d28 100644 --- a/filter.c +++ b/filter.c @@ -29,7 +29,10 @@ #include "mutt_curses.h" #include "protos.h" -/* Invokes a command on a pipe and optionally connects its stdin and stdout +/** + * mutt_create_filter_fd - Run a command on a pipe + * + * Invokes a command on a pipe and optionally connects its stdin and stdout * to the specified handles. */ pid_t mutt_create_filter_fd(const char *cmd, FILE **in, FILE **out, FILE **err, diff --git a/flags.c b/flags.c index 144158381..c3ac7a9da 100644 --- a/flags.c +++ b/flags.c @@ -329,12 +329,16 @@ void _mutt_set_flag(struct Context *ctx, struct Header *h, int flag, int bf, int h->searched = false; } +/** + * mutt_thread_set_flag - Set a flag on an entire thread + */ void mutt_tag_set_flag(int flag, int bf) { for (int j = 0; j < Context->vcount; j++) if (Context->hdrs[Context->v2r[j]]->tagged) mutt_set_flag(Context, Context->hdrs[Context->v2r[j]], flag, bf); } + int mutt_thread_set_flag(struct Header *hdr, int flag, int bf, int subthread) { struct MuttThread *start = NULL, *cur = hdr->thread; diff --git a/gen_defs b/gen_defs index ed490be7b..6f3951cc6 100755 --- a/gen_defs +++ b/gen_defs @@ -11,11 +11,11 @@ for mode in help defs; do help) echo "#ifdef HELP_C" echo "const char *HelpStrings[] = {" - expr='s;^[^ ]* *\(.*\); N_(\1),;' + expr='s;^[^ ]* *\(.*\); N_(\1),;' ;; *) echo "enum {" - expr='s;^\([^ ]*\).*; \1,;' + expr='s;^\([^ ]*\).*; \1,;' ;; esac for i in $*; do diff --git a/handler.c b/handler.c index 2fef17006..172298083 100644 --- a/handler.c +++ b/handler.c @@ -246,27 +246,26 @@ static void qp_decode_line(char *dest, char *src, size_t *l, int last) *l = d - dest; } -/* - * Decode an attachment encoded with quoted-printable. +/** + * decode_quoted - Decode an attachment encoded with quoted-printable * - * Why doesn't this overflow any buffers? First, it's guaranteed - * that the length of a line grows when you _en_-code it to - * quoted-printable. That means that we always can store the - * result in a buffer of at most the _same_ size. + * Why doesn't this overflow any buffers? First, it's guaranteed that the + * length of a line grows when you _en_-code it to quoted-printable. That + * means that we always can store the result in a buffer of at most the _same_ + * size. * - * Now, we don't special-case if the line we read with fgets() - * isn't terminated. We don't care about this, since STRING > 78, - * so corrupted input will just be corrupted a bit more. That - * implies that STRING+1 bytes are always sufficient to store the - * result of qp_decode_line. + * Now, we don't special-case if the line we read with fgets() isn't + * terminated. We don't care about this, since STRING > 78, so corrupted input + * will just be corrupted a bit more. That implies that STRING+1 bytes are + * always sufficient to store the result of qp_decode_line. * - * Finally, at soft line breaks, some part of a multibyte character - * may have been left over by convert_to_state(). This shouldn't - * be more than 6 characters, so STRING + 7 should be sufficient - * memory to store the decoded data. + * Finally, at soft line breaks, some part of a multibyte character may have + * been left over by convert_to_state(). This shouldn't be more than 6 + * characters, so STRING + 7 should be sufficient memory to store the decoded + * data. * - * Just to make sure that I didn't make some off-by-one error - * above, we just use STRING*2 for the target buffer's size. + * Just to make sure that I didn't make some off-by-one error above, we just + * use STRING*2 for the target buffer's size. */ static void decode_quoted(struct State *s, long len, int istext, iconv_t cd) { @@ -972,7 +971,9 @@ static int text_enriched_handler(struct Body *a, struct State *s) return 0; } -/* for compatibility with metamail */ +/** + * is_mmnoask - for compatibility with metamail + */ static int is_mmnoask(const char *buf) { char tmp[LONG_STRING], *p = NULL, *q = NULL; @@ -1243,7 +1244,9 @@ static int alternative_handler(struct Body *a, struct State *s) return rc; } -/* handles message/rfc822 body parts */ +/** + * message_handler - handles message/rfc822 body parts + */ static int message_handler(struct Body *a, struct State *s) { struct stat st; @@ -1289,7 +1292,10 @@ static int message_handler(struct Body *a, struct State *s) return rc; } -/* returns 1 if decoding the attachment will produce output */ +/** + * mutt_can_decode - Will decoding the attachment produce any output + * @return 1 if decoding the attachment will produce output + */ int mutt_can_decode(struct Body *a) { if (is_autoview(a)) @@ -1660,9 +1666,12 @@ void mutt_decode_attachment(struct Body *b, struct State *s) iconv_close(cd); } -/* when generating format=flowed ($text_flowed is set) from format=fixed, - * strip all trailing spaces to improve interoperability; - * if $text_flowed is unset, simply verbatim copy input +/** + * text_plain_handler - Display plain text + * + * when generating format=flowed ($text_flowed is set) from format=fixed, strip + * all trailing spaces to improve interoperability; if $text_flowed is unset, + * simply verbatim copy input */ static int text_plain_handler(struct Body *b, struct State *s) { diff --git a/hash.c b/hash.c index 76a5cc856..c219973ec 100644 --- a/hash.c +++ b/hash.c @@ -116,10 +116,14 @@ struct Hash *int_hash_create(int nelem, int flags) return table; } -/* table hash table to update - * key key to hash on - * data data to associate with `key' - * allow_dup if nonzero, duplicate keys are allowed in the table +/** + * union_hash_insert - Insert into a hash table using a union as a key + * @param table Hash table to update + * @param key Key to hash on + * @param data Data to associate with `key' + * @return + * * -1 on error + * * >=0 on success, index into the hash table */ static int union_hash_insert(struct Hash *table, union HashKey key, void *data) { @@ -286,8 +290,10 @@ void int_hash_delete(struct Hash *table, unsigned int intkey, const void *data, union_hash_delete(table, key, data, destroy); } -/* ptr pointer to the hash table to be freed - * destroy() function to call to free the ->data member (optional) +/** + * hash_destroy - Destroy a hash table + * @param ptr Pointer to the hash table to be freed + * @param destroy Function to call to free the ->data member (optional) */ void hash_destroy(struct Hash **ptr, void (*destroy)(void *)) { diff --git a/hcache/hcache.c b/hcache/hcache.c index 1d7c230c9..c0051c49d 100644 --- a/hcache/hcache.c +++ b/hcache/hcache.c @@ -633,7 +633,10 @@ static const char *hcache_per_folder(const char *path, const char *folder, hcach return hcpath; } -/* This function transforms a header into a char so that it is useable by +/** + * hcache_dump - Serialise a Header object + * + * This function transforms a header into a char so that it is useable by * db_store. */ static void *hcache_dump(header_cache_t *h, struct Header *header, int *off, diff --git a/hdrline.c b/hdrline.c index 08a7f2ad0..951024edb 100644 --- a/hdrline.c +++ b/hdrline.c @@ -112,7 +112,9 @@ static bool check_for_mailing_list(struct Address *adr, const char *pfx, char *b return false; } -/* Search for a mailing list in the list of addresses pointed to by adr. +/** + * check_for_mailing_list_addr - Check an address list for a mailing list + * * If one is found, print the address of the list into buf, then return 1. * Otherwise, simply return 0. */ @@ -337,13 +339,15 @@ static bool user_in_addr(struct Address *a) return false; } -/* Return values: - * 0: user is not in list - * 1: user is unique recipient - * 2: user is in the TO list - * 3: user is in the CC list - * 4: user is originator - * 5: sent to a subscribed mailinglist +/** + * user_is_recipient - Is the user a recipient of the message + * @return + * * 0 User is not in list + * * 1 User is unique recipient + * * 2 User is in the TO list + * * 3 User is in the CC list + * * 4 User is originator + * * 5 Sent to a subscribed mailinglist */ static int user_is_recipient(struct Header *h) { @@ -451,47 +455,52 @@ static char *apply_subject_mods(struct Envelope *env) } -/* %a = address of author - * %A = reply-to address (if present; otherwise: address of author - * %b = filename of the originating folder - * %B = the list to which the letter was sent, or else the folder name (%b). - * %c = size of message in bytes - * %C = current message number - * %d = date and time of message using $date_format and sender's timezone - * %D = date and time of message using $date_format and local timezone - * %e = current message number in thread - * %E = number of messages in current thread - * %f = entire from line - * %F = like %n, unless from self - * %g = message labels (e.g. notmuch tags) - * %i = message-id - * %I = initials of author - * %K = the list to which the letter was sent (if any; otherwise: empty) - * %l = number of lines in the message - * %L = like %F, except `lists' are displayed first - * %m = number of messages in the mailbox - * %n = name of author - * %N = score - * %O = like %L, except using address instead of name - * %P = progress indicator for builtin pager - * %q = newsgroup name (if compiled with NNTP support) - * %r = comma separated list of To: recipients - * %R = comma separated list of Cc: recipients - * %s = subject - * %S = short message status (e.g., N/O/D/!/r/-) - * %t = `to:' field (recipients) - * %T = $to_chars - * %u = user (login) name of author - * %v = first name of author, unless from self - * %W = where user is (organization) - * %x = `x-comment-to:' field (if present and compiled with NNTP support) - * %X = number of MIME attachments - * %y = `x-label:' field (if present) - * %Y = `x-label:' field (if present, tree unfolded, and != parent's x-label) - * %zs = message status flags - * %zc = message crypto flags - * %zt = message tag flags - * %Z = combined message flags +/** + * hdr_format_str - Format a string, like printf() + * + * | Expando | Description + * |:--------|:----------------------------------------------------------------- + * | \%a | address of author + * | \%A | reply-to address (if present; otherwise: address of author + * | \%b | filename of the originating folder + * | \%B | the list to which the letter was sent, or else the folder name (%b). + * | \%c | size of message in bytes + * | \%C | current message number + * | \%d | date and time of message using $date_format and sender's timezone + * | \%D | date and time of message using $date_format and local timezone + * | \%e | current message number in thread + * | \%E | number of messages in current thread + * | \%f | entire from line + * | \%F | like %n, unless from self + * | \%g | message labels (e.g. notmuch tags) + * | \%i | message-id + * | \%I | initials of author + * | \%K | the list to which the letter was sent (if any; otherwise: empty) + * | \%l | number of lines in the message + * | \%L | like %F, except `lists' are displayed first + * | \%m | number of messages in the mailbox + * | \%n | name of author + * | \%N | score + * | \%O | like %L, except using address instead of name + * | \%P | progress indicator for builtin pager + * | \%q | newsgroup name (if compiled with NNTP support) + * | \%r | comma separated list of To: recipients + * | \%R | comma separated list of Cc: recipients + * | \%s | subject + * | \%S | short message status (e.g., N/O/D/!/r/-) + * | \%t | `to:' field (recipients) + * | \%T | $to_chars + * | \%u | user (login) name of author + * | \%v | first name of author, unless from self + * | \%W | where user is (organization) + * | \%x | `x-comment-to:' field (if present and compiled with NNTP support) + * | \%X | number of MIME attachments + * | \%y | `x-label:' field (if present) + * | \%Y | `x-label:' field (if present, tree unfolded, and != parent's x-label) + * | \%zs | message status flags + * | \%zc | message crypto flags + * | \%zt | message tag flags + * | \%Z | combined message flags */ static const char *hdr_format_str(char *dest, size_t destlen, size_t col, int cols, char op, const char *src, const char *prefix, diff --git a/headers.c b/headers.c index 4b275a74d..5de0b2096 100644 --- a/headers.c +++ b/headers.c @@ -270,8 +270,8 @@ static void label_ref_inc(struct Context *ctx, char *label) elem->data = (void *) count; } -/* - * add an X-Label: field. +/** + * label_message - add an X-Label: field */ static int label_message(struct Context *ctx, struct Header *hdr, char *new) { diff --git a/history.c b/history.c index d12fce8c0..5b3d74464 100644 --- a/history.c +++ b/history.c @@ -323,7 +323,10 @@ static void save_history(enum HistoryClass hclass, const char *s) } } -/* When removing dups, we want the created "blanks" to be right below the +/** + * remove_history_dups - De-dupe the history + * + * When removing dups, we want the created "blanks" to be right below the * resulting h->last position. See the comment section above 'struct History'. */ static void remove_history_dups(enum HistoryClass hclass, const char *s) diff --git a/hook.c b/hook.c index 033d74092..90dd07bb8 100644 --- a/hook.c +++ b/hook.c @@ -280,7 +280,12 @@ static void delete_hook(struct Hook *h) FREE(&h); } -/* Deletes all hooks of type ``type'', or all defined hooks if ``type'' is 0 */ +/** + * delete_hooks - Delete matching hooks + * @param type + * * Hook type to delete, e.g. #MUTT_SENDHOOK + * * Or, 0 to delete all hooks + */ static void delete_hooks(int type) { struct Hook *h = NULL; diff --git a/imap/auth.c b/imap/auth.c index fe981d897..41b8eeca2 100644 --- a/imap/auth.c +++ b/imap/auth.c @@ -51,8 +51,12 @@ static const struct ImapAuth imap_authenticators[] = { { NULL, NULL }, }; -/* imap_authenticate: Attempt to authenticate using either user-specified - * authentication method if specified, or any. */ +/** + * imap_authenticate - Authenticate to an IMAP server + * + * Attempt to authenticate using either user-specified authentication method if + * specified, or any. + */ int imap_authenticate(struct ImapData *idata) { const struct ImapAuth *authenticator = NULL; diff --git a/imap/auth_anon.c b/imap/auth_anon.c index 375c8fe56..a47de90a2 100644 --- a/imap/auth_anon.c +++ b/imap/auth_anon.c @@ -32,7 +32,11 @@ #include "options.h" #include "protos.h" -/* this is basically a stripped-down version of the cram-md5 method. */ +/** + * imap_auth_anon - Authenticate anonymously + * + * this is basically a stripped-down version of the cram-md5 method. + */ enum ImapAuthRes imap_auth_anon(struct ImapData *idata, const char *method) { int rc; diff --git a/imap/auth_cram.c b/imap/auth_cram.c index 59620f22c..4e172a6b2 100644 --- a/imap/auth_cram.c +++ b/imap/auth_cram.c @@ -41,7 +41,9 @@ /* forward declarations */ static void hmac_md5(const char *password, char *challenge, unsigned char *response); -/* imap_auth_cram_md5: AUTH=CRAM-MD5 support. */ +/** + * imap_auth_cram_md5 - imap_auth_cram_md5: AUTH=CRAM-MD5 support + */ enum ImapAuthRes imap_auth_cram_md5(struct ImapData *idata, const char *method) { char ibuf[LONG_STRING * 2], obuf[LONG_STRING]; @@ -137,7 +139,9 @@ bail: return IMAP_AUTH_FAILURE; } -/* hmac_md5: produce CRAM-MD5 challenge response. */ +/** + * hmac_md5 - hmac_md5: produce CRAM-MD5 challenge response + */ static void hmac_md5(const char *password, char *challenge, unsigned char *response) { struct Md5Ctx ctx; diff --git a/imap/auth_gss.c b/imap/auth_gss.c index bde009b29..03c9c61ff 100644 --- a/imap/auth_gss.c +++ b/imap/auth_gss.c @@ -76,7 +76,9 @@ static void print_gss_error(OM_uint32 err_maj, OM_uint32 err_min) mutt_debug(2, "((%s:%d )(%s:%d))\n", buf_maj, err_maj, buf_min, err_min); } -/* imap_auth_gss: AUTH=GSSAPI support. */ +/** + * imap_auth_gss - GSS Authentication support + */ enum ImapAuthRes imap_auth_gss(struct ImapData *idata, const char *method) { gss_buffer_desc request_buf, send_token; diff --git a/imap/auth_login.c b/imap/auth_login.c index e906cc300..2363d6d41 100644 --- a/imap/auth_login.c +++ b/imap/auth_login.c @@ -33,7 +33,9 @@ #include "options.h" #include "protos.h" -/* imap_auth_login: Plain LOGIN support */ +/** + * imap_auth_login - Plain LOGIN support + */ enum ImapAuthRes imap_auth_login(struct ImapData *idata, const char *method) { char q_user[SHORT_STRING], q_pass[SHORT_STRING]; diff --git a/imap/auth_plain.c b/imap/auth_plain.c index a294dc605..cde8ed0b3 100644 --- a/imap/auth_plain.c +++ b/imap/auth_plain.c @@ -33,7 +33,9 @@ #include "mutt_socket.h" #include "protos.h" -/* imap_auth_plain: SASL PLAIN support */ +/** + * imap_auth_plain - SASL PLAIN support + */ enum ImapAuthRes imap_auth_plain(struct ImapData *idata, const char *method) { int rc; diff --git a/imap/auth_sasl.c b/imap/auth_sasl.c index abd80ce9b..066c8ea61 100644 --- a/imap/auth_sasl.c +++ b/imap/auth_sasl.c @@ -39,7 +39,9 @@ #include "options.h" #include "protos.h" -/* imap_auth_sasl: Default authenticator if available. */ +/** + * imap_auth_sasl - Default authenticator if available + */ enum ImapAuthRes imap_auth_sasl(struct ImapData *idata, const char *method) { sasl_conn_t *saslconn = NULL; diff --git a/imap/browse.c b/imap/browse.c index 1abf75f92..391266fd4 100644 --- a/imap/browse.c +++ b/imap/browse.c @@ -42,8 +42,8 @@ #include "options.h" #include "protos.h" -/* imap_add_folder: - * add a folder name to the browser list, formatting it as necessary. +/** + * imap_add_folder - Format and add an IMAP folder to the browser * * The folder parameter should already be 'unmunged' via * imap_unmunge_mbox_name(). @@ -164,8 +164,11 @@ static int browse_add_list_result(struct ImapData *idata, const char *cmd, return rc == IMAP_CMD_OK ? 0 : -1; } -/* imap_browse: IMAP hook into the folder browser, fills out browser_state, - * given a current folder to browse */ +/** + * imap_browse - IMAP hook into the folder browser + * + * Fill out browser_state, given a current folder to browse + */ int imap_browse(char *path, struct BrowserState *state) { struct ImapData *idata = NULL; @@ -329,7 +332,11 @@ fail: return -1; } -/* imap_mailbox_create: Prompt for a new mailbox name, and try to create it */ +/** + * imap_mailbox_create - Create a new IMAP mailbox + * + * Prompt for a new mailbox name, and try to create it + */ int imap_mailbox_create(const char *folder) { struct ImapData *idata = NULL; diff --git a/imap/command.c b/imap/command.c index 791b4d7d8..f6df30e7e 100644 --- a/imap/command.c +++ b/imap/command.c @@ -110,7 +110,11 @@ static struct ImapCommand *cmd_new(struct ImapData *idata) return cmd; } -/* queues command. If the queue is full, attempts to drain it. */ +/** + * cmd_queue - Add a IMAP command to the queue + * + * If the queue is full, attempts to drain it. + */ static int cmd_queue(struct ImapData *idata, const char *cmdstr) { struct ImapCommand *cmd = NULL; @@ -135,7 +139,9 @@ static int cmd_queue(struct ImapData *idata, const char *cmdstr) return 0; } -/* cmd_handle_fatal: when ImapData is in fatal state, do what we can */ +/** + * cmd_handle_fatal - When ImapData is in fatal state, do what we can + */ static void cmd_handle_fatal(struct ImapData *idata) { idata->status = IMAP_FATAL; @@ -188,7 +194,9 @@ static int cmd_start(struct ImapData *idata, const char *cmdstr, int flags) return (rc < 0) ? IMAP_CMD_BAD : 0; } -/* parse response line for tagged OK/NO/BAD */ +/** + * cmd_status - parse response line for tagged OK/NO/BAD + */ static int cmd_status(const char *s) { s = imap_next_word((char *) s); @@ -201,8 +209,12 @@ static int cmd_status(const char *s) return IMAP_CMD_BAD; } -/* cmd_parse_expunge: mark headers with new sequence ID and mark idata to - * be reopened at our earliest convenience */ +/** + * cmd_parse_expunge - Parse expunge command + * + * cmd_parse_expunge: mark headers with new sequence ID and mark idata to be + * reopened at our earliest convenience + */ static void cmd_parse_expunge(struct ImapData *idata, const char *s) { unsigned int exp_msn; @@ -239,10 +251,13 @@ static void cmd_parse_expunge(struct ImapData *idata, const char *s) idata->reopen |= IMAP_EXPUNGE_PENDING; } -/* cmd_parse_fetch: Load fetch response into ImapData. Currently only - * handles unanticipated FETCH responses, and only FLAGS data. We get - * these if another client has changed flags for a mailbox we've selected. - * Of course, a lot of code here duplicates code in message.c. */ +/** + * cmd_parse_fetch - Load fetch response into ImapData + * + * Currently only handles unanticipated FETCH responses, and only FLAGS data. + * We get these if another client has changed flags for a mailbox we've + * selected. Of course, a lot of code here duplicates code in message.c. + */ static void cmd_parse_fetch(struct ImapData *idata, char *s) { unsigned int msn; @@ -292,8 +307,9 @@ static void cmd_parse_fetch(struct ImapData *idata, char *s) } } -/* cmd_parse_capabilities: set capability bits according to CAPABILITY - * response */ +/** + * cmd_parse_capability - set capability bits according to CAPABILITY response + */ static void cmd_parse_capability(struct ImapData *idata, char *s) { int x; @@ -456,7 +472,9 @@ static void cmd_parse_lsub(struct ImapData *idata, char *s) FREE(&token.data); } -/* cmd_parse_myrights: set rights bits according to MYRIGHTS response */ +/** + * cmd_parse_myrights - Set rights bits according to MYRIGHTS response + */ static void cmd_parse_myrights(struct ImapData *idata, const char *s) { mutt_debug(2, "Handling MYRIGHTS\n"); @@ -521,7 +539,9 @@ static void cmd_parse_myrights(struct ImapData *idata, const char *s) } } -/* cmd_parse_search: store SEARCH response for later use */ +/** + * cmd_parse_search - store SEARCH response for later use + */ static void cmd_parse_search(struct ImapData *idata, const char *s) { unsigned int uid; @@ -538,8 +558,12 @@ static void cmd_parse_search(struct ImapData *idata, const char *s) } } -/* first cut: just do buffy update. Later we may wish to cache all - * mailbox information, even that not desired by buffy */ +/** + * cmd_parse_status - Parse status from server + * + * first cut: just do buffy update. Later we may wish to cache all mailbox + * information, even that not desired by buffy + */ static void cmd_parse_status(struct ImapData *idata, char *s) { char *mailbox = NULL; @@ -693,7 +717,9 @@ static void cmd_parse_status(struct ImapData *idata, char *s) } } -/* cmd_parse_enabled: record what the server has enabled */ +/** + * cmd_parse_enabled - Record what the server has enabled + */ static void cmd_parse_enabled(struct ImapData *idata, const char *s) { mutt_debug(2, "Handling ENABLED\n"); @@ -706,7 +732,9 @@ static void cmd_parse_enabled(struct ImapData *idata, const char *s) } } -/* cmd_handle_untagged: fallback parser for otherwise unhandled messages. */ +/** + * cmd_handle_untagged - fallback parser for otherwise unhandled messages + */ static int cmd_handle_untagged(struct ImapData *idata) { char *s = NULL; @@ -807,17 +835,22 @@ static int cmd_handle_untagged(struct ImapData *idata) return 0; } -/* imap_cmd_start: Given an IMAP command, send it to the server. - * If cmdstr is NULL, sends queued commands. */ +/** + * imap_cmd_start - Given an IMAP command, send it to the server + * + * If cmdstr is NULL, sends queued commands. + */ int imap_cmd_start(struct ImapData *idata, const char *cmdstr) { return cmd_start(idata, cmdstr, 0); } -/* imap_cmd_step: Reads server responses from an IMAP command, detects - * tagged completion response, handles untagged messages, can read - * arbitrarily large strings (using malloc, so don't make it _too_ - * large!). */ +/** + * imap_cmd_step - Reads server responses from an IMAP command + * + * detects tagged completion response, handles untagged messages, can read + * arbitrarily large strings (using malloc, so don't make it _too_ large!). + */ int imap_cmd_step(struct ImapData *idata) { size_t len = 0; @@ -920,13 +953,18 @@ int imap_cmd_step(struct ImapData *idata) return rc; } -/* imap_code: returns 1 if the command result was OK, or 0 if NO or BAD */ +/** + * imap_code - Was the command successful + * @return 1 if the command result was OK, or 0 if NO or BAD + */ int imap_code(const char *s) { return cmd_status(s) == IMAP_CMD_OK; } -/* imap_cmd_trailer: extra information after tagged command response if any */ +/** + * imap_cmd_trailer - Extra information after tagged command response if any + */ const char *imap_cmd_trailer(struct ImapData *idata) { static const char *notrailer = ""; @@ -1006,10 +1044,14 @@ int imap_exec(struct ImapData *idata, const char *cmdstr, int flags) return 0; } -/* imap_cmd_finish: Attempts to perform cleanup (eg fetch new mail if - * detected, do expunge). Called automatically by imap_cmd_step, but - * may be called at any time. Called by imap_check_mailbox just before - * the index is refreshed, for instance. */ +/** + * imap_cmd_finish - Attempt to perform cleanup + * + * Attempts to perform cleanup (eg fetch new mail if detected, do expunge). + * Called automatically by imap_cmd_step(), but may be called at any time. + * Called by imap_check_mailbox() just before the index is refreshed, for + * instance. + */ void imap_cmd_finish(struct ImapData *idata) { if (idata->status == IMAP_FATAL) @@ -1050,7 +1092,9 @@ void imap_cmd_finish(struct ImapData *idata) idata->status = false; } -/* imap_cmd_idle: Enter the IDLE state. */ +/** + * imap_cmd_idle - Enter the IDLE state + */ int imap_cmd_idle(struct ImapData *idata) { int rc; diff --git a/imap/imap.c b/imap/imap.c index b23240450..4ab2f6c05 100644 --- a/imap/imap.c +++ b/imap/imap.c @@ -73,9 +73,11 @@ static int imap_check_capabilities(struct ImapData *idata); static void imap_set_flag(struct ImapData *idata, int aclbit, int flag, const char *str, char *flags, size_t flsize); -/* imap_access: Check permissions on an IMAP mailbox. - * TODO: ACL checks. Right now we assume if it exists we can - * mess with it. */ +/** + * imap_access - Check permissions on an IMAP mailbox + * + * TODO: ACL checks. Right now we assume if it exists we can mess with it. + */ int imap_access(const char *path) { struct ImapData *idata = NULL; @@ -193,8 +195,11 @@ int imap_delete_mailbox(struct Context *ctx, struct ImapMbox *mx) return 0; } -/* imap_logout_all: close all open connections. Quick and dirty until we can - * make sure we've got all the context we need. */ +/** + * imap_logout_all - close all open connections + * + * Quick and dirty until we can make sure we've got all the context we need. + */ void imap_logout_all(void) { struct Connection *conn = NULL; @@ -218,9 +223,12 @@ void imap_logout_all(void) } } -/* imap_read_literal: read bytes bytes from server into file. Not explicitly - * buffered, relies on FILE buffering. NOTE: strips \r from \r\n. - * Apparently even literals use \r\n-terminated strings ?! */ +/** + * imap_read_literal - Read bytes bytes from server into file + * + * Not explicitly buffered, relies on FILE buffering. NOTE: strips `\r` from + * `\r\n`. Apparently even literals use `\r\n`-terminated strings ?! + */ int imap_read_literal(FILE *fp, struct ImapData *idata, long bytes, struct Progress *pbar) { char c; @@ -262,9 +270,13 @@ int imap_read_literal(FILE *fp, struct ImapData *idata, long bytes, struct Progr return 0; } -/* imap_expunge_mailbox: Purge IMAP portion of expunged messages from the - * context. Must not be done while something has a handle on any headers - * (eg inside pager or editor). That is, check IMAP_REOPEN_ALLOW. */ +/** + * imap_expunge_mailbox - Purge messages from the server + * + * Purge IMAP portion of expunged messages from the context. Must not be done + * while something has a handle on any headers (eg inside pager or editor). + * That is, check IMAP_REOPEN_ALLOW. + */ void imap_expunge_mailbox(struct ImapData *idata) { struct Header *h = NULL; @@ -323,7 +335,9 @@ void imap_expunge_mailbox(struct ImapData *idata) mutt_sort_headers(idata->ctx, 1); } -/* imap_check_capabilities: make sure we can log in to this server. */ +/** + * imap_check_capabilities - Make sure we can log in to this server + */ static int imap_check_capabilities(struct ImapData *idata) { if (imap_exec(idata, "CAPABILITY", 0) != 0) @@ -345,8 +359,12 @@ static int imap_check_capabilities(struct ImapData *idata) return 0; } -/* imap_conn_find: Find an open IMAP connection matching account, or open - * a new one if none can be found. */ +/** + * imap_conn_find - Find an open IMAP connection + * + * Find an open IMAP connection matching account, or open a new one if none can + * be found. + */ struct ImapData *imap_conn_find(const struct Account *account, int flags) { struct Connection *conn = NULL; @@ -527,8 +545,11 @@ void imap_close_connection(struct ImapData *idata) memset(idata->cmds, 0, sizeof(struct ImapCommand) * idata->cmdslots); } -/* imap_get_flags: Make a simple list out of a FLAGS response. - * return stream following FLAGS response */ +/** + * imap_get_flags - Make a simple list out of a FLAGS response + * + * return stream following FLAGS response + */ static char *imap_get_flags(struct List **hflags, char *s) { struct List *flags = NULL; @@ -841,7 +862,9 @@ static int imap_open_mailbox_append(struct Context *ctx, int flags) return 0; } -/* imap_logout: Gracefully log out of server. */ +/** + * imap_logout - Gracefully log out of server + */ void imap_logout(struct ImapData **idata) { /* we set status here to let imap_handle_untagged know we _expect_ to @@ -879,8 +902,13 @@ static void imap_set_flag(struct ImapData *idata, int aclbit, int flag, safe_strcat(flags, flsize, str); } -/* imap_has_flag: do a caseless comparison of the flag against a flag list, -* return true if found or flag list has '\*', false otherwise */ +/** + * imap_has_flag - Does the flag exist in the list + * @return boolean + * + * Do a caseless comparison of the flag against a flag list, return true if + * found or flag list has '\*'. + */ bool imap_has_flag(struct List *flag_list, const char *flag) { if (!flag_list) @@ -901,7 +929,10 @@ bool imap_has_flag(struct List *flag_list, const char *flag) return false; } -/* Note: headers must be in SORT_ORDER. See imap_exec_msgset for args. +/** + * imap_make_msg_set - Make a message set + * + * Note: headers must be in SORT_ORDER. See imap_exec_msgset for args. * Pos is an opaque pointer a la strtok. It should be 0 at first call. */ static int imap_make_msg_set(struct ImapData *idata, struct Buffer *buf, int flag, bool changed, bool invert, int *pos) @@ -1064,7 +1095,10 @@ out: return rc; } -/* returns 0 if mutt's flags match cached server flags */ +/** + * compare_flags - Compare local flags against the server + * @return 0 if mutt's flags match cached server flags + */ static bool compare_flags(struct Header *h) { struct ImapHeaderData *hd = (struct ImapHeaderData *) h->data; @@ -1083,7 +1117,9 @@ static bool compare_flags(struct Header *h) return false; } -/* Update the IMAP server to reflect the flags a single message. */ +/** + * imap_sync_message - Update server to reflect the flags of a single message + */ int imap_sync_message(struct ImapData *idata, struct Header *hdr, struct Buffer *cmd, int *err_continue) { @@ -1184,10 +1220,11 @@ static int sync_helper(struct ImapData *idata, int right, int flag, const char * return count; } -/* update the IMAP server to reflect message changes done within mutt. - * Arguments - * ctx: the current context - * expunge: 0 or 1 - do expunge? +/** + * imap_sync_mailbox - Sync all the changes to the server + * @param ctx the current context + * @param expunge 0 or 1 - do expunge? + * @return 0 on success, -1 on error */ int imap_sync_mailbox(struct Context *ctx, int expunge) { @@ -1382,7 +1419,9 @@ out: return rc; } -/* imap_close_mailbox: clean up IMAP data in Context */ +/** + * imap_close_mailbox - Clean up IMAP data in Context + */ int imap_close_mailbox(struct Context *ctx) { struct ImapData *idata = NULL; @@ -1520,7 +1559,9 @@ static int imap_check_mailbox_reopen(struct Context *ctx, int *index_hint) return rc; } -/* split path into (idata,mailbox name) */ +/** + * imap_get_mailbox - split path into (idata,mailbox name) + */ static int imap_get_mailbox(const char *path, struct ImapData **hidata, char *buf, size_t blen) { struct ImapMbox mx; @@ -1545,9 +1586,13 @@ static int imap_get_mailbox(const char *path, struct ImapData **hidata, char *bu return 0; } -/* check for new mail in any subscribed mailboxes. Given a list of mailboxes - * rather than called once for each so that it can batch the commands and - * save on round trips. Returns number of mailboxes with new mail. */ +/** + * imap_buffy_check - Check for new mail in subscribed folders + * + * Given a list of mailboxes rather than called once for each so that it can + * batch the commands and save on round trips. Returns number of mailboxes with + * new mail. + */ int imap_buffy_check(int force, int check_stats) { struct ImapData *idata = NULL; @@ -1637,7 +1682,11 @@ int imap_buffy_check(int force, int check_stats) return buffies; } -/* imap_status: returns count of messages in mailbox, or -1 on error. +/** + * imap_status - Get the status of a mailbox + * @return + * * -1 on error + * * >=0 count of messages in mailbox * if queue != 0, queue the command and expect it to have been run * on the next call (for pipelining the postponed count) */ int imap_status(char *path, int queue) @@ -1686,7 +1735,11 @@ int imap_status(char *path, int queue) return 0; } -/* return cached mailbox stats or NULL if create is 0 */ +/** + * imap_mboxcache_get - Open an hcache for a mailbox + * + * return cached mailbox stats or NULL if create is 0 + */ struct ImapStatus *imap_mboxcache_get(struct ImapData *idata, const char *mbox, int create) { struct List *cur = NULL; @@ -1761,8 +1814,12 @@ void imap_mboxcache_free(struct ImapData *idata) mutt_free_list(&idata->mboxcache); } -/* returns number of patterns in the search that should be done server-side - * (eg are full-text) */ +/** + * do_search - Perform a search of messages + * + * returns number of patterns in the search that should be done server-side + * (eg are full-text) + */ static int do_search(const struct Pattern *search, int allpats) { int rc = 0; @@ -1793,9 +1850,13 @@ static int do_search(const struct Pattern *search, int allpats) return rc; } -/* convert mutt Pattern to IMAP SEARCH command containing only elements +/** + * imap_compile_search - Convert Mutt pattern to IMAP search + * + * Convert mutt Pattern to IMAP SEARCH command containing only elements * that require full-text search (mutt already has what it needs for most - * match types, and does a better job (eg server doesn't support regexps). */ + * match types, and does a better job (eg server doesn't support regexps). + */ static int imap_compile_search(struct Context *ctx, const struct Pattern *pat, struct Buffer *buf) { @@ -1997,8 +2058,12 @@ static size_t longest_common_prefix(char *dest, const char *src, size_t start, s return pos; } -/* look for IMAP URLs to complete from defined mailboxes. Could be extended - * to complete over open connections and account/folder hooks too. */ +/** + * imap_complete_hosts - Look for completion matches for mailboxes + * + * look for IMAP URLs to complete from defined mailboxes. Could be extended to + * complete over open connections and account/folder hooks too. + */ static int imap_complete_hosts(char *dest, size_t len) { struct Buffy *mailbox = NULL; @@ -2049,8 +2114,12 @@ static int imap_complete_hosts(char *dest, size_t len) return rc; } -/* imap_complete: given a partial IMAP folder path, return a string which - * adds as much to the path as is unique */ +/** + * imap_complete - Try to complete an IMAP folder path + * + * Given a partial IMAP folder path, return a string which adds as much to the + * path as is unique + */ int imap_complete(char *dest, size_t dlen, char *path) { struct ImapData *idata = NULL; @@ -2138,12 +2207,13 @@ int imap_complete(char *dest, size_t dlen, char *path) return -1; } -/* imap_fast_trash: use server COPY command to copy deleted - * messages to the trash folder. - * Return codes: - * -1: error - * 0: success - * 1: non-fatal error - try fetch/append */ +/** + * imap_fast_trash - Use server COPY command to copy deleted messages to trash + * @return + * * -1: error + * * 0: success + * * 1: non-fatal error - try fetch/append + */ int imap_fast_trash(struct Context *ctx, char *dest) { struct ImapData *idata = NULL; diff --git a/imap/message.c b/imap/message.c index 67f6bdb89..18b3b776f 100644 --- a/imap/message.c +++ b/imap/message.c @@ -136,7 +136,9 @@ static int msg_cache_clean_cb(const char *id, struct BodyCache *bcache, void *da return 0; } -/* msg_parse_flags: read a FLAGS token into an ImapHeader */ +/** + * msg_parse_flags - read a FLAGS token into an ImapHeader + */ static char *msg_parse_flags(struct ImapHeader *h, char *s) { struct ImapHeaderData *hd = h->data; @@ -302,12 +304,15 @@ static int msg_parse_fetch(struct ImapHeader *h, char *s) return 0; } -/* msg_fetch_header: import IMAP FETCH response into an ImapHeader. - * Expects string beginning with * n FETCH. - * Returns: - * 0 on success - * -1 if the string is not a fetch response - * -2 if the string is a corrupt fetch response */ +/** + * msg_fetch_header -import IMAP FETCH response into an ImapHeader. + * @return + * * 0 Success + * * -1 String is not a fetch response + * * -2 String is a corrupt fetch response + * + * Expects string beginning with * n FETCH. + */ static int msg_fetch_header(struct Context *ctx, struct ImapHeader *h, char *buf, FILE *fp) { struct ImapData *idata = NULL; @@ -405,7 +410,10 @@ static void imap_alloc_msn_index(struct ImapData *idata, unsigned int msn_count) idata->msn_index_size = new_size; } -/* Generates a more complicated sequence set after using the header cache, +/** + * imap_generate_seqset - Generate a sequence set + * + * Generates a more complicated sequence set after using the header cache, * in case there are missing MSNs in the middle. * * There is a suggested limit of 1000 bytes for an IMAP client request. @@ -460,10 +468,12 @@ static void imap_generate_seqset(struct Buffer *b, struct ImapData *idata, } } -/* imap_read_headers: - * Changed to read many headers instead of just one. It will return the - * msn of the last message read. It will return a value other than - * msn_end if mail comes in while downloading headers (in theory). +/** + * imap_read_headers - Read headers from the server + * + * Changed to read many headers instead of just one. It will return the msn of + * the last message read. It will return a value other than msn_end if mail + * comes in while downloading headers (in theory). */ int imap_read_headers(struct ImapData *idata, unsigned int msn_begin, unsigned int msn_end) { @@ -1183,12 +1193,13 @@ fail: return -1; } -/* imap_copy_messages: use server COPY command to copy messages to another - * folder. - * Return codes: - * -1: error - * 0: success - * 1: non-fatal error - try fetch/append */ +/** + * imap_copy_messages - Server COPY messages to another folder + * @return + * * -1 Error + * * 0 Success + * * 1 Non-fatal error - try fetch/append + */ int imap_copy_messages(struct Context *ctx, struct Header *h, char *dest, int delete) { struct ImapData *idata = NULL; @@ -1383,8 +1394,11 @@ int imap_cache_clean(struct ImapData *idata) return 0; } -/* imap_add_keywords: concatenate custom IMAP tags to list, if they - * appear in the folder flags list. Why wouldn't they? */ +/** + * imap_add_keywords - concatenate custom IMAP tags to list + * + * If the tags appear in the folder flags list. Why wouldn't they? + */ void imap_add_keywords(char *s, struct Header *h, struct List *mailbox_flags, size_t slen) { struct List *keywords = NULL; @@ -1405,7 +1419,9 @@ void imap_add_keywords(char *s, struct Header *h, struct List *mailbox_flags, si } } -/* imap_free_header_data: free ImapHeader structure */ +/** + * imap_free_header_data - free ImapHeader structure + */ void imap_free_header_data(struct ImapHeaderData **data) { if (*data) @@ -1416,8 +1432,11 @@ void imap_free_header_data(struct ImapHeaderData **data) } } -/* imap_set_flags: fill out the message header according to the flags from - * the server. Expects a flags line of the form "FLAGS (flag flag ...)" */ +/** + * imap_set_flags - fill the message header according to the server flags + * + * Expects a flags line of the form "FLAGS (flag flag ...)" + */ char *imap_set_flags(struct ImapData *idata, struct Header *h, char *s) { struct Context *ctx = idata->ctx; diff --git a/imap/utf7.c b/imap/utf7.c index 4190d61de..32e973dd4 100644 --- a/imap/utf7.c +++ b/imap/utf7.c @@ -48,15 +48,14 @@ static const char B64Chars[64] = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '+', ',', }; -/* - * Convert the data (u7,u7len) from RFC 2060's UTF-7 to UTF-8. - * The result is null-terminated and returned, and also stored - * in (*u8,*u8len) if u8 or u8len is non-zero. - * If input data is invalid, return 0 and don't store anything. - * RFC 2060 obviously intends the encoding to be unique (see - * point 5 in section 5.1.3), so we reject any non-canonical - * form, such as &ACY- (instead of &-) or &AMA-&AMA- (instead - * of &AMAAwA-). +/** + * utf7_to_utf8 - Convert the data (u7,u7len) from RFC 2060's UTF-7 to UTF-8 + * + * The result is null-terminated and returned, and also stored in (*u8,*u8len) + * if u8 or u8len is non-zero. If input data is invalid, return 0 and don't + * store anything. RFC 2060 obviously intends the encoding to be unique (see + * point 5 in section 5.1.3), so we reject any non-canonical form, such as + * &ACY- (instead of &-) or &AMA-&AMA- (instead of &AMAAwA-). */ static char *utf7_to_utf8(const char *u7, size_t u7len, char **u8, size_t *u8len) { @@ -143,12 +142,12 @@ bail: return 0; } -/* - * Convert the data (u8,u8len) from UTF-8 to RFC 2060's UTF-7. - * The result is null-terminated and returned, and also stored - * in (*u7,*u7len) if u7 or u7len is non-zero. - * Unicode characters above U+FFFF are replaced by U+FFFE. - * If input data is invalid, return 0 and don't store anything. +/** + * utf8_to_utf7 - Convert the data (u8,u8len) from UTF-8 to RFC 2060's UTF-7 + * + * The result is null-terminated and returned, and also stored in (*u7,*u7len) + * if u7 or u7len is non-zero. Unicode characters above U+FFFF are replaced by + * U+FFFE. If input data is invalid, return 0 and don't store anything. */ static char *utf8_to_utf7(const char *u8, size_t u8len, char **u7, size_t *u7len) { diff --git a/imap/util.c b/imap/util.c index 86ba5abc2..9c5821f1b 100644 --- a/imap/util.c +++ b/imap/util.c @@ -96,13 +96,8 @@ int imap_expand_path(char *path, size_t len) return rc; } -/* Public function - * - * Provided an imap mbox name and a delimiter, returns the mbox parent - * name. - * - * Could be static with a prototype in imap_private.h, but could be useful - * as a public function. +/** + * imap_get_parent - Get an IMAP folder's parent */ void imap_get_parent(char *output, const char *mbox, size_t olen, char delim) { @@ -141,7 +136,9 @@ void imap_get_parent(char *output, const char *mbox, size_t olen, char delim) } } -/* Public function +/** + * imap_get_parent_path - Get the path of the parent folder + * * Provided an imap path, returns in output the parent directory if * existent. Else returns the same path. */ @@ -174,9 +171,10 @@ void imap_get_parent_path(char *output, const char *path, size_t olen) imap_qualify_path(output, olen, &mx, mbox); } -/* Public function +/** + * imap_clean_path - Cleans an IMAP path using imap_fix_path * - * Cleans an IMAP path using imap_fix_path. Does it in place. + * Does it in place. */ void imap_clean_path(char *path, size_t plen) { @@ -284,9 +282,12 @@ int imap_hcache_del(struct ImapData *idata, unsigned int uid) } #endif -/* imap_parse_path: given an IMAP mailbox name, return host, port - * and a path IMAP servers will recognize. - * mx.mbox is malloc'd, caller must free it */ +/** + * imap_parse_path - Parse an IMAP mailbox name into name,host,port + * + * Given an IMAP mailbox name, return host, port and a path IMAP servers will + * recognize. mx.mbox is malloc'd, caller must free it + */ int imap_parse_path(const char *path, struct ImapMbox *mx) { static unsigned short ImapPort = 0; @@ -391,7 +392,11 @@ int imap_parse_path(const char *path, struct ImapMbox *mx) return 0; } -/* silly helper for mailbox name string comparisons, because of INBOX */ +/** + * imap_mxcmp - Compare mailbox names, giving priority to INBOX + * + * silly helper for mailbox name string comparisons, because of INBOX + */ int imap_mxcmp(const char *mx1, const char *mx2) { char *b1 = NULL; @@ -419,8 +424,11 @@ int imap_mxcmp(const char *mx1, const char *mx2) return rc; } -/* imap_pretty_mailbox: called by mutt_pretty_mailbox to make IMAP paths - * look nice. */ +/** + * imap_pretty_mailbox - Prettify an IMAP mailbox name + * + * Called by mutt_pretty_mailbox() to make IMAP paths look nice. + */ void imap_pretty_mailbox(char *path) { struct ImapMbox home, target; @@ -476,23 +484,28 @@ void imap_pretty_mailbox(char *path) /* -- library functions -- */ -/* imap_continue: display a message and ask the user if she wants to - * go on. */ +/** + * imap_continue - display a message and ask the user if they want to go on + */ int imap_continue(const char *msg, const char *resp) { imap_error(msg, resp); return mutt_yesorno(_("Continue?"), 0); } -/* imap_error: show an error and abort */ +/** + * imap_error - show an error and abort + */ void imap_error(const char *where, const char *msg) { mutt_error("%s [%s]\n", where, msg); mutt_sleep(2); } -/* imap_new_idata: Allocate and initialise a new ImapData structure. - * Returns NULL on failure (no mem) */ +/** + * imap_new_idata - Allocate and initialise a new ImapData structure + * @return NULL on failure (no mem) + */ struct ImapData *imap_new_idata(void) { struct ImapData *idata = safe_calloc(1, sizeof(struct ImapData)); @@ -510,7 +523,9 @@ struct ImapData *imap_new_idata(void) return idata; } -/* imap_free_idata: Release and clear storage in an ImapData structure. */ +/** + * imap_free_idata - Release and clear storage in an ImapData structure + */ void imap_free_idata(struct ImapData **idata) { if (!idata) @@ -526,12 +541,13 @@ void imap_free_idata(struct ImapData **idata) FREE(idata); } -/* - * Fix up the imap path. This is necessary because the rest of mutt - * assumes a hierarchy delimiter of '/', which is not necessarily true - * in IMAP. Additionally, the filesystem converts multiple hierarchy - * delimiters into a single one, ie "///" is equal to "/". IMAP servers - * are not required to do this. +/** + * imap_fix_path - Fix up the imap path + * + * This is necessary because the rest of mutt assumes a hierarchy delimiter of + * '/', which is not necessarily true in IMAP. Additionally, the filesystem + * converts multiple hierarchy delimiters into a single one, ie "///" is equal + * to "/". IMAP servers are not required to do this. * Moreover, IMAP servers may dislike the path ending with the delimiter. */ char *imap_fix_path(struct ImapData *idata, const char *mailbox, char *path, size_t plen) @@ -594,8 +610,10 @@ void imap_cachepath(struct ImapData *idata, const char *mailbox, char *dest, siz *s = '\0'; } -/* imap_get_literal_count: write number of bytes in an IMAP literal into - * bytes, return 0 on success, -1 on failure. */ +/** + * imap_get_literal_count - write number of bytes in an IMAP literal into bytes + * @return 0 on success, -1 on failure + */ int imap_get_literal_count(const char *buf, long *bytes) { char *pc = NULL; @@ -614,8 +632,12 @@ int imap_get_literal_count(const char *buf, long *bytes) return 0; } -/* imap_get_qualifier: in a tagged response, skip tag and status for - * the qualifier message. Used by imap_copy_message for TRYCREATE */ +/** + * imap_get_qualifier - Get the qualifier from a tagged reponse + * + * In a tagged response, skip tag and status for the qualifier message. Used by + * imap_copy_message for TRYCREATE + */ char *imap_get_qualifier(char *buf) { char *s = buf; @@ -628,7 +650,9 @@ char *imap_get_qualifier(char *buf) return s; } -/* imap_next_word: return index into string where next IMAP word begins */ +/** + * imap_next_word - return index into string where next IMAP word begins + */ char *imap_next_word(char *s) { int quoted = 0; @@ -653,7 +677,9 @@ char *imap_next_word(char *s) return s; } -/* imap_parse_date: date is of the form: DD-MMM-YYYY HH:MM:SS +ZZzz */ +/** + * imap_parse_date - Parse date of the form: DD-MMM-YYYY HH:MM:SS +ZZzz + */ time_t imap_parse_date(char *s) { struct tm t; @@ -701,7 +727,9 @@ time_t imap_parse_date(char *s) return (mutt_mktime(&t, 0) + tz); } -/* format date in IMAP style: DD-MMM-YYYY HH:MM:SS +ZZzz. +/** + * imap_make_date - format date in IMAP style: DD-MMM-YYYY HH:MM:SS +ZZzz + * * Caller should provide a buffer of IMAP_DATELEN bytes */ void imap_make_date(char *buf, time_t timestamp) { @@ -715,8 +743,11 @@ void imap_make_date(char *buf, time_t timestamp) tm->tm_min, tm->tm_sec, (int) tz / 60, (int) abs((int) tz) % 60); } -/* imap_qualify_path: make an absolute IMAP folder target, given ImapMbox - * and relative path. */ +/** + * imap_qualify_path - Make an absolute IMAP folder target + * + * given ImapMbox and relative path. + */ void imap_qualify_path(char *dest, size_t len, struct ImapMbox *mx, char *path) { struct CissUrl url; @@ -728,8 +759,11 @@ void imap_qualify_path(char *dest, size_t len, struct ImapMbox *mx, char *path) } -/* imap_quote_string: quote string according to IMAP rules: - * surround string with quotes, escape " and \ with \ */ +/** + * imap_quote_string - quote string according to IMAP rules + * + * Surround string with quotes, escape " and \ with backslash + */ void imap_quote_string(char *dest, size_t dlen, const char *src) { static const char quote[] = "\"\\"; @@ -763,7 +797,9 @@ void imap_quote_string(char *dest, size_t dlen, const char *src) *pt = 0; } -/* imap_unquote_string: equally stupid unquoting routine */ +/** + * imap_unquote_string - equally stupid unquoting routine + */ void imap_unquote_string(char *s) { char *d = s; @@ -795,8 +831,8 @@ void imap_unquote_string(char *s) } -/* - * Quoting and UTF-7 conversion +/** + * imap_munge_mbox_name - Quoting and UTF-7 conversion */ void imap_munge_mbox_name(struct ImapData *idata, char *dest, size_t dlen, const char *src) { @@ -826,7 +862,9 @@ void imap_unmunge_mbox_name(struct ImapData *idata, char *s) FREE(&buf); } -/* imap_wordcasecmp: find word a in word list b */ +/** + * imap_wordcasecmp - find word a in word list b + */ int imap_wordcasecmp(const char *a, const char *b) { char tmp[SHORT_STRING]; @@ -921,7 +959,9 @@ int imap_wait_keepalive(pid_t pid) return rc; } -/* Allow/disallow re-opening a folder upon expunge. */ +/** + * imap_allow_reopen - Allow/disallow re-opening a folder upon expunge + */ void imap_allow_reopen(struct Context *ctx) { struct ImapData *idata = NULL; diff --git a/init.c b/init.c index 8d088f8bf..569da5ea7 100644 --- a/init.c +++ b/init.c @@ -235,8 +235,11 @@ int query_quadoption(int opt, const char *prompt) /* not reached */ } -/* given the variable ``s'', return the index into the rc_vars array which - matches, or -1 if the variable is not found. */ +/** + * mutt_option_index - Find the index (in rc_vars) of a variable name + * @param s Variable name to search for + * @return -1 on error, >0 on success + */ int mutt_option_index(const char *s) { for (int i = 0; MuttVars[i].option; i++) @@ -534,7 +537,9 @@ static void free_opt(struct Option *p) } } -/* clean up before quitting */ +/** + * mutt_free_opts - clean up before quitting + */ void mutt_free_opts(void) { for (int i = 0; MuttVars[i].option; i++) @@ -1356,7 +1361,9 @@ bail: return -1; } -/* always wise to do what someone else did before */ +/** + * _attachments_clean - always wise to do what someone else did before + */ static void _attachments_clean(void) { int i; @@ -3195,16 +3202,17 @@ static int parse_source(struct Buffer *tmp, struct Buffer *token, return 0; } -/* line command to execute - - token scratch buffer to be used by parser. caller should free - token->data when finished. the reason for this variable is - to avoid having to allocate and deallocate a lot of memory - if we are parsing many lines. the caller can pass in the - memory to use, which avoids having to create new space for - every call to this function. - - err where to write error messages */ +/** + * mutt_parse_rc_line - Parse a line of user config + * @param line config line to read + * @param token scratch buffer to be used by parser + * @param err where to write error messages + * + * Caller should free token->data when finished. the reason for this variable + * is to avoid having to allocate and deallocate a lot of memory if we are + * parsing many lines. the caller can pass in the memory to use, which avoids + * having to create new space for every call to this function. + */ int mutt_parse_rc_line(/* const */ char *line, struct Buffer *token, struct Buffer *err) { int i, r = 0; @@ -3284,12 +3292,14 @@ static void matches_ensure_morespace(int current) } } -/* helper function for completion. Changes the dest buffer if - necessary/possible to aid completion. - dest == completion result gets here. - src == candidate for completion. - try == user entered data for completion. - len == length of dest buffer. +/** + * candidate - helper function for completion + * @param dest Completion result gets here + * @param src Candidate for completion + * @param try User entered data for completion + * @param len Length of dest buffer + * + * Changes the dest buffer if necessary/possible to aid completion. */ static void candidate(char *dest, char *try, const char *src, int len) { @@ -3534,8 +3544,8 @@ int mutt_var_value_complete(char *buffer, size_t len, int pos) #ifdef USE_NOTMUCH -/* Fetch a list of all notmuch tags and insert them into the completion - * machinery. +/** + * complete_all_nm_tags - Pass a list of notmuch tags to the completion code */ static int complete_all_nm_tags(const char *pt) { @@ -3587,7 +3597,10 @@ done: return 0; } -/* Return the last instance of needle in the haystack, or NULL. +/** + * rstrnstr - Find last instance of a substring + * + * Return the last instance of needle in the haystack, or NULL. * Like strstr(), only backwards, and for a limited haystack length. */ static const char *rstrnstr(const char *haystack, size_t haystack_length, const char *needle) @@ -3610,7 +3623,11 @@ static const char *rstrnstr(const char *haystack, size_t haystack_length, const return NULL; } -/* Complete the nearest "tag:"-prefixed string previous to pos. */ +/** + * mutt_nm_query_complete - Complete to the nearest notmuch tag + * + * Complete the nearest "tag:"-prefixed string previous to pos. + */ bool mutt_nm_query_complete(char *buffer, size_t len, int pos, int numtabs) { char *pt = buffer; @@ -3655,7 +3672,11 @@ bool mutt_nm_query_complete(char *buffer, size_t len, int pos, int numtabs) return true; } -/* Complete the nearest "+" or "-" -prefixed string previous to pos. */ +/** + * mutt_nm_tag_complete - Complete to the nearest notmuch tag + * + * Complete the nearest "+" or "-" -prefixed string previous to pos. + */ bool mutt_nm_tag_complete(char *buffer, size_t len, int pos, int numtabs) { if (!buffer) @@ -3798,7 +3819,9 @@ int var_to_string(int idx, char *val, size_t len) return 1; } -/* Implement the -Q command line flag */ +/** + * mutt_query_variables - Implement the -Q command line flag + */ int mutt_query_variables(struct List *queries) { struct List *p = NULL; @@ -3833,7 +3856,9 @@ int mutt_query_variables(struct List *queries) return 0; } -/* dump out the value of all the variables we have */ +/** + * mutt_dump_variables - Print a list of all variables with their values + */ int mutt_dump_variables(int hide_sensitive) { char command[STRING]; diff --git a/keymap.c b/keymap.c index 92e8f08f6..5c303d14b 100644 --- a/keymap.c +++ b/keymap.c @@ -164,8 +164,10 @@ static int parse_fkey(char *s) return n; } -/* - * This function parses the string and uses the octal value as the key +/** + * parse_keycode - Parse a numeric keycode + * + * This function parses the string `` and uses the octal value as the key * to bind. */ static int parse_keycode(const char *s) @@ -234,8 +236,11 @@ static int parsekeys(const char *str, keycode_t *d, int max) return (max - len); } -/* insert a key sequence into the specified map. the map is sorted by ASCII - * value (lowest to highest) +/** + * km_bind_err - Set up a key binding + * + * Insert a key sequence into the specified map. + * The map is sorted by ASCII value (lowest to highest) */ int km_bind_err(char *s, int menu, int op, char *macro, char *descr, struct Buffer *err) { @@ -341,6 +346,7 @@ static int km_bindkey_err(char *s, int menu, int op, struct Buffer *err) { return km_bind_err(s, menu, op, NULL, NULL, err); } + static int km_bindkey(char *s, int menu, int op) { return km_bindkey_err(s, menu, op, NULL); @@ -369,9 +375,12 @@ static char *get_func(const struct Binding *bindings, int op) return NULL; } -/* Parses s for syntax and adds the whole sequence to - * either the macro or unget buffer. This function is invoked by the next - * two defines below. +/** + * generic_tokenize_push_string - Parse and queue a 'push' command + * + * Parses s for `` syntax and adds the whole sequence to either the + * macro or unget buffer. This function is invoked by the next two defines + * below. */ static void generic_tokenize_push_string(char *s, void (*generic_push)(int, int)) { @@ -460,11 +469,13 @@ static int retry_generic(int menu, keycode_t *keys, int keyslen, int lastkey) return OP_NULL; } -/* return values: - * >0 function to execute - * OP_NULL no function bound to key sequence - * -1 error occurred while reading input - * -2 a timeout or sigwinch occurred +/** + * km_dokey - Determine what a keypress should do + * @return + * * >0 Function to execute + * * OP_NULL No function bound to key sequence + * * -1 Error occurred while reading input + * * -2 A timeout or sigwinch occurred */ int km_dokey(int menu) { @@ -717,7 +728,11 @@ static const struct Extkey ExtKeys[] = { { 0, 0 }, }; -/* Look up Mutt's name for a key and find the ncurses extended name for it */ +/** + * find_ext_name - Find the curses name for a key + * + * Look up Mutt's name for a key and find the ncurses extended name for it + */ static const char *find_ext_name(const char *key) { for (int j = 0; ExtKeys[j].name; ++j) @@ -729,12 +744,15 @@ static const char *find_ext_name(const char *key) } #endif /* NCURSES_VERSION */ -/* Determine the keycodes for ncurses extended keys and fill in the KeyNames array. +/** + * init_extended_keys - Initialise map of ncurses extended keys + * + * Determine the keycodes for ncurses extended keys and fill in the KeyNames array. * - * This function must be called *after* initscr(), or tigetstr() returns -1. This - * creates a bit of a chicken-and-egg problem because km_init() is called prior to - * start_curses(). This means that the default keybindings can't include any of the - * extended keys because they won't be defined until later. + * This function must be called *after* initscr(), or tigetstr() returns -1. + * This creates a bit of a chicken-and-egg problem because km_init() is called + * prior to start_curses(). This means that the default keybindings can't + * include any of the extended keys because they won't be defined until later. */ void init_extended_keys(void) { @@ -954,7 +972,11 @@ int mutt_parse_push(struct Buffer *buf, struct Buffer *s, unsigned long data, return r; } -/* expects to see: ,,... */ +/** + * parse_keymap - Parse a user-config key binding + * + * Expects to see: ,,... + */ char *parse_keymap(int *menu, struct Buffer *s, int maxmenus, int *nummenus, struct Buffer *err) { struct Buffer buf; @@ -1068,7 +1090,11 @@ const struct Binding *km_get_table(int menu) return NULL; } -/* bind menu-name '' function-name */ +/** + * mutt_parse_bind - Parse a 'bind' command + * + * bind menu-name `` function-name + */ int mutt_parse_bind(struct Buffer *buf, struct Buffer *s, unsigned long data, struct Buffer *err) { @@ -1121,7 +1147,11 @@ int mutt_parse_bind(struct Buffer *buf, struct Buffer *s, unsigned long data, return r; } -/* macro */ +/** + * mutt_parse_macro - Parse a 'macro' command + * + * macro `` `` `` `` + */ int mutt_parse_macro(struct Buffer *buf, struct Buffer *s, unsigned long data, struct Buffer *err) { @@ -1171,7 +1201,9 @@ int mutt_parse_macro(struct Buffer *buf, struct Buffer *s, unsigned long data, return r; } -/* exec function-name */ +/** + * mutt_parse_exec - exec function-name + */ int mutt_parse_exec(struct Buffer *buf, struct Buffer *s, unsigned long data, struct Buffer *err) { @@ -1213,9 +1245,10 @@ int mutt_parse_exec(struct Buffer *buf, struct Buffer *s, unsigned long data, return 0; } -/* - * prompts the user to enter a keystroke, and displays the octal value back - * to the user. +/** + * mutt_what_key - Ask the user to press a key + * + * Displays the octal value back to the user. */ void mutt_what_key(void) { diff --git a/lib.c b/lib.c index 5c73a98e9..6c2209b1e 100644 --- a/lib.c +++ b/lib.c @@ -288,7 +288,9 @@ void mutt_str_adjust(char **p) safe_realloc(p, strlen(*p) + 1); } -/* convert all characters in the string to lowercase */ +/** + * mutt_strlower - convert all characters in the string to lowercase + */ char *mutt_strlower(char *s) { char *p = s; @@ -450,8 +452,8 @@ int safe_symlink(const char *oldpath, const char *newpath) } -/* - * This function is supposed to do nfs-safe renaming of files. +/** + * safe_rename - NFS-safe renaming of files * * Warning: We don't check whether src and target are equal. */ @@ -552,7 +554,9 @@ int safe_rename(const char *src, const char *target) } -/* Create a temporary directory next to a file name */ +/** + * mkwrapdir - Create a temporary directory next to a file name + */ static int mkwrapdir(const char *path, char *newfile, size_t nflen, char *newdir, size_t ndlen) { const char *basename = NULL; @@ -588,7 +592,9 @@ static int mkwrapdir(const char *path, char *newfile, size_t nflen, char *newdir return 0; } -/* remove a directory and everything under it */ +/** + * mutt_rmtree - remove a directory and everything under it + */ int mutt_rmtree(const char *path) { DIR *dirp = NULL; @@ -676,8 +682,11 @@ int safe_open(const char *path, int flags) return fd; } -/* when opening files for writing, make sure the file doesn't already exist - * to avoid race conditions. +/** + * safe_fopen - Call fopen() safely + * + * when opening files for writing, make sure the file doesn't already exist to + * avoid race conditions. */ FILE *safe_fopen(const char *path, const char *mode) { @@ -743,10 +752,13 @@ int mutt_rx_sanitize_string(char *dest, size_t destlen, const char *src) return 0; } -/* Read a line from ``fp'' into the dynamically allocated ``s'', - * increasing ``s'' if necessary. The ending "\n" or "\r\n" is removed. - * If a line ends with "\", this char and the linefeed is removed, - * and the next line is read too. +/** + * mutt_read_line - Read a line from a file + * + * Read a line from ``fp'' into the dynamically allocated ``s'', increasing + * ``s'' if necessary. The ending "\n" or "\r\n" is removed. If a line ends + * with "\", this char and the linefeed is removed, and the next line is read + * too. */ char *mutt_read_line(char *s, size_t *size, FILE *fp, int *line, int flags) { @@ -834,7 +846,9 @@ char *mutt_substrdup(const char *begin, const char *end) return p; } -/* prepare a file name to survive the shell's quoting rules. +/** + * mutt_quote_filename - Quote a filename to survive the shell's quoting rules + * * From the Unix programming FAQ by way of Liviu. */ size_t mutt_quote_filename(char *d, size_t l, const char *f) diff --git a/lib.h b/lib.h index 1501afb00..f015534fc 100644 --- a/lib.h +++ b/lib.h @@ -79,8 +79,11 @@ #define EMAIL_WSP " \t\r\n" -/* skip over WSP as defined by RFC5322. This is used primarily for parsing - * header fields. */ +/** + * skip_email_wsp - Skip over whitespace as defined by RFC5322 + * + * This is used primarily for parsing header fields. + */ static inline char *skip_email_wsp(const char *s) { if (s) diff --git a/main.c b/main.c index a0e752d89..ffc367680 100644 --- a/main.c +++ b/main.c @@ -180,6 +180,13 @@ static void start_curses(void) #define MUTT_NEWS (1 << 5) /* -g and -G */ #endif +/** + * main - Start NeoMutt + * @param argc Number of command line arguments + * @param argv List of command line arguments + * @param env Copy of the environment + * @return 0 on success, 1 on error + */ int main(int argc, char **argv, char **env) { char folder[_POSIX_PATH_MAX] = ""; diff --git a/mbox.c b/mbox.c index 98e92a64f..7b2567868 100644 --- a/mbox.c +++ b/mbox.c @@ -66,10 +66,11 @@ struct MUpdate LOFF_T length; }; -/* parameters: - * ctx - context to lock - * excl - exclusive lock? - * retry - should retry if unable to lock? +/** + * mbox_lock_mailbox - Lock a mailbox + * @param ctx Context to lock + * @param excl Exclusive lock? + * @param retry Should retry if unable to lock? */ static int mbox_lock_mailbox(struct Context *ctx, int excl, int retry) { @@ -244,11 +245,14 @@ static int mmdf_parse_mailbox(struct Context *ctx) return 0; } -/* Note that this function is also called when new mail is appended to the +/** + * mbox_parse_mailbox - Read a mailbox from disk + * + * 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. * - * NOTE: it is assumed that the mailbox being read has been locked before - * this routine gets called. Strange things could happen if it's not! + * NOTE: it is assumed that the mailbox being read has been locked before this + * routine gets called. Strange things could happen if it's not! */ static int mbox_parse_mailbox(struct Context *ctx) { @@ -432,7 +436,9 @@ static int mbox_parse_mailbox(struct Context *ctx) #undef PREV -/* open a mbox or mmdf style mailbox */ +/** + * mbox_open_mailbox - open a mbox or mmdf style mailbox + */ static int mbox_open_mailbox(struct Context *ctx) { int rc; @@ -549,7 +555,10 @@ static int mbox_open_new_message(struct Message *msg, struct Context *dest, stru return 0; } -/* return 1 if address lists are strictly identical */ +/** + * strict_addrcmp - Strictly compare two address list + * @return 1 if address lists are strictly identical + */ static int strict_addrcmp(const struct Address *a, const struct Address *b) { while (a && b) @@ -634,7 +643,10 @@ static int strict_cmp_bodies(const struct Body *b1, const struct Body *b2) return 1; } -/* return 1 if headers are strictly identical */ +/** + * mbox_strict_cmp_headers - Strictly compare message headers + * @return 1 if headers are strictly identical + */ int mbox_strict_cmp_headers(const struct Header *h1, const struct Header *h2) { if (h1 && h2) @@ -954,8 +966,9 @@ static int mbox_check_mailbox(struct Context *ctx, int *index_hint) /** * mbox_has_new - Does the mailbox have new mail * @param ctx Context - * @return true if the mailbox has at least 1 new messages (not old) - * false, otherwise + * @return + * * true if the mailbox has at least 1 new messages (not old) + * * false otherwise */ static bool mbox_has_new(struct Context *ctx) { @@ -965,8 +978,12 @@ static bool mbox_has_new(struct Context *ctx) return false; } -/* if mailbox has at least 1 new message, sets mtime > atime of mailbox - * so buffy check reports new mail */ +/** + * mbox_reset_atime - Reset the access time on the mailbox file + * + * if mailbox has at least 1 new message, sets mtime > atime of mailbox so + * buffy check reports new mail + */ void mbox_reset_atime(struct Context *ctx, struct stat *st) { struct utimbuf utimebuf; @@ -992,9 +1009,11 @@ void mbox_reset_atime(struct Context *ctx, struct stat *st) utime(ctx->path, &utimebuf); } -/* return values: - * 0 success - * -1 failure +/** + * mbox_sync_mailbox - Sync a mailbox to disk + * @return + * * 0 Success + * * -1 Failure */ static int mbox_sync_mailbox(struct Context *ctx, int *index_hint) { diff --git a/mbyte.c b/mbyte.c index 1f0cbbb75..9f65f4d07 100644 --- a/mbyte.c +++ b/mbyte.c @@ -185,15 +185,17 @@ static size_t utf8rtowc(wchar_t *pwc, const char *s, size_t n, mbstate_t *_ps) return (size_t) -2; } -/* - * For systems that don't have them, we provide here our own - * implementations of wcrtomb(), mbrtowc(), iswprint() and wcwidth(). - * Instead of using the locale, as these functions normally would, - * we use Mutt's Charset variable. We support 3 types of charset: - * (1) For 8-bit charsets, wchar_t uses the same encoding as char. - * (2) For UTF-8, wchar_t uses UCS. - * (3) For stateless Japanese encodings, we use UCS and convert - * via UTF-8 using iconv. +/** + * wcrtomb_iconv - Convert wide characters to multibyte characters + * + * For systems that don't have them, we provide here our own implementations of + * wcrtomb(), mbrtowc(), iswprint() and wcwidth(). Instead of using the + * locale, as these functions normally would, we use Mutt's Charset variable. + * We support 3 types of charset: + * 1. For 8-bit charsets, wchar_t uses the same encoding as char. + * 2. For UTF-8, wchar_t uses UCS. + * 3. For stateless Japanese encodings, we use UCS and convert via UTF-8 using + * iconv. * Unfortunately, we can't handle non-stateless encodings. */ static size_t wcrtomb_iconv(char *s, wchar_t wc, iconv_t cd) @@ -480,8 +482,10 @@ int iswupper(wint_t wc) return (0 <= wc && wc < 256) ? isupper(wc) : 0; } -/* - * l10n for Japanese: +/** + * wcwidth_ja - Calculate character widths for Japanese + * + * L10N for Japanese: * Symbols, Greek and Cyrillic in JIS X 0208, Japanese Kanji * Character Set, have a column width of 2. */ diff --git a/md5.c b/md5.c index a83219be4..825497bd8 100644 --- a/md5.c +++ b/md5.c @@ -47,8 +47,11 @@ 64-byte boundary. (RFC 1321, 3.1: Step 1) */ static const unsigned char fillbuf[64] = { 0x80, 0 /* , 0, 0, ... */ }; -/* Initialize structure containing state of computation. - (RFC 1321, 3.3: Step 3) */ +/** + * md5_init_ctx - Initialise the MD5 computation + * + * (RFC 1321, 3.3: Step 3) + */ void md5_init_ctx(struct Md5Ctx *ctx) { ctx->A = 0x67452301; @@ -60,16 +63,24 @@ void md5_init_ctx(struct Md5Ctx *ctx) ctx->buflen = 0; } -/* Copy the 4 byte value from v into the memory location pointed to by *cp, - If your architecture allows unaligned access this is equivalent to - * (md5_uint32 *) cp = v */ +/** + * set_uint32 - Write a 32 bit number + * + * Copy the 4 byte value from v into the memory location pointed to by *cp, If + * your architecture allows unaligned access this is equivalent to + * `*(md5_uint32*) cp = v` + */ static inline void set_uint32(char *cp, md5_uint32 v) { memcpy(cp, &v, sizeof(v)); } -/* Put result from CTX in first 16 bytes following RESBUF. The result - must be in little endian byte order. */ +/** + * md5_read_ctx - Read from the context into a buffer + * + * Put result from CTX in first 16 bytes following RESBUF. + * The result must be in little endian byte order. + */ void *md5_read_ctx(const struct Md5Ctx *ctx, void *resbuf) { char *r = resbuf; @@ -81,8 +92,12 @@ void *md5_read_ctx(const struct Md5Ctx *ctx, void *resbuf) return resbuf; } -/* Process the remaining bytes in the internal buffer and the usual - prolog according to the standard and write the result to RESBUF. */ +/** + * md5_finish_ctx - Process the remaining bytes in the buffer + * + * Process the remaining bytes in the internal buffer and the usual prologue + * according to the standard and write the result to RESBUF. + */ void *md5_finish_ctx(struct Md5Ctx *ctx, void *resbuf) { /* Take yet unprocessed bytes into account. */ @@ -106,9 +121,12 @@ void *md5_finish_ctx(struct Md5Ctx *ctx, void *resbuf) return md5_read_ctx(ctx, resbuf); } -/* Compute MD5 message digest for bytes read from STREAM. The - resulting message digest number will be written into the 16 bytes - beginning at RESBLOCK. */ +/** + * md5_stream - Compute MD5 message digest for bytes read from a file + * + * The resulting message digest number will be written into the 16 bytes + * beginning at RESBLOCK. + */ int md5_stream(FILE *stream, void *resblock) { struct Md5Ctx ctx; @@ -169,10 +187,13 @@ process_partial_block: return 0; } -/* Compute MD5 message digest for LEN bytes beginning at Buffer. The - result is always in little endian byte order, so that a byte-wise - output yields to the wanted ASCII representation of the message - digest. */ +/** + * md5_buffer - Calculate the MD5 hash of a buffer + * + * Compute MD5 message digest for LEN bytes beginning at Buffer. The result is + * always in little endian byte order, so that a byte-wise output yields to the + * wanted ASCII representation of the message digest. + */ void *md5_buffer(const char *buffer, size_t len, void *resblock) { struct Md5Ctx ctx; @@ -262,8 +283,12 @@ void md5_process_bytes(const void *buffer, size_t len, struct Md5Ctx *ctx) #define FH(b, c, d) (b ^ c ^ d) #define FI(b, c, d) (c ^ (b | ~d)) -/* Process LEN bytes of Buffer, accumulating context into CTX. - It is assumed that LEN % 64 == 0. */ +/** + * md5_process_block - Process a block with MD5 + * + * Process LEN bytes of Buffer, accumulating context into CTX. + * It is assumed that LEN % 64 == 0. + */ void md5_process_block(const void *buffer, size_t len, struct Md5Ctx *ctx) { md5_uint32 correct_words[16]; diff --git a/menu.c b/menu.c index 105897354..fa4de3b2c 100644 --- a/menu.c +++ b/menu.c @@ -582,11 +582,13 @@ void menu_prev_line(struct Menu *menu) mutt_error(_("You cannot scroll up farther.")); } -/* - * pageup: jumplen == -pagelen - * pagedown: jumplen == pagelen - * halfup: jumplen == -pagelen/2 - * halfdown: jumplen == pagelen/2 +/** + * menu_length_jump - Calculate the destination of a jump + * + * * pageup: jumplen == -pagelen + * * pagedown: jumplen == pagelen + * * halfup: jumplen == -pagelen/2 + * * halfdown: jumplen == pagelen/2 */ #define DIRECTION ((neg * 2) + 1) static void menu_length_jump(struct Menu *menu, int jumplen) diff --git a/mh.c b/mh.c index e248c2c60..2c563c9e5 100644 --- a/mh.c +++ b/mh.c @@ -453,7 +453,12 @@ static void mhs_write_one_sequence(FILE *fp, struct MhSequences *mhs, short f, c fputc('\n', fp); } -/* XXX - we don't currently remove deleted messages from sequences we don't know. Should we? */ +/** + * mh_update_sequences - Update sequence numbers + * + * XXX we don't currently remove deleted messages from sequences we don't know. + * Should we? + */ static void mh_update_sequences(struct Context *ctx) { FILE *ofp = NULL, *nfp = NULL; @@ -656,7 +661,9 @@ static void mh_update_maildir(struct Maildir *md, struct MhSequences *mhs) } } -/* maildir support */ +/** + * maildir_free_entry - Free a maildir object + */ static void maildir_free_entry(struct Maildir **md) { if (!md || !*md) @@ -765,7 +772,9 @@ static void maildir_update_mtime(struct Context *ctx) ctx->mtime = st.st_mtime; } -/* +/** + * maildir_parse_stream - Parse a Maildir message + * * Actually parse a maildir message. This may also be used to fill * out a fake header structure generated by lazy maildir parsing. */ @@ -802,9 +811,11 @@ struct Header *maildir_parse_stream(int magic, FILE *f, const char *fname, return h; } -/* - * Actually parse a maildir message. This may also be used to fill - * out a fake header structure generated by lazy maildir parsing. +/** + * maildir_parse_message - Actually parse a maildir message + * + * This may also be used to fill out a fake header structure generated by lazy + * maildir parsing. */ struct Header *maildir_parse_message(int magic, const char *fname, int is_old, struct Header *h) @@ -952,8 +963,8 @@ static int md_cmp_path(struct Maildir *a, struct Maildir *b) return strcmp(a->h->path, b->h->path); } -/* - * Merge two maildir lists according to the inode numbers. +/** + * maildir_merge_lists - Merge two maildir lists according to the inode numbers */ static struct Maildir *maildir_merge_lists(struct Maildir *left, struct Maildir *right, int (*cmp)(struct Maildir *, struct Maildir *)) @@ -1039,8 +1050,8 @@ static struct Maildir *maildir_ins_sort(struct Maildir *list, return ret; } -/* - * Sort maildir list according to inode. +/** + * maildir_sort - Sort maildir list according to inode */ static struct Maildir *maildir_sort(struct Maildir *list, size_t len, int (*cmp)(struct Maildir *, struct Maildir *)) @@ -1074,7 +1085,9 @@ static struct Maildir *maildir_sort(struct Maildir *list, size_t len, return maildir_merge_lists(left, right, cmp); } -/* Sorts mailbox into its natural order. +/** + * mh_sort_natural - Sorts mailbox into its natural order + * * Currently only defined for MH where files are numbered. */ static void mh_sort_natural(struct Context *ctx, struct Maildir **md) @@ -1105,8 +1118,8 @@ static struct Maildir *skip_duplicates(struct Maildir *p, struct Maildir **last) return p; } -/* - * This function does the second parsing pass +/** + * maildir_delayed_parsing - This function does the second parsing pass */ static void maildir_delayed_parsing(struct Context *ctx, struct Maildir **md, struct Progress *progress) @@ -1232,12 +1245,11 @@ static int mh_close_mailbox(struct Context *ctx) return 0; } -/* Read a MH/maildir style mailbox. - * - * args: - * ctx [IN/OUT] context for this mailbox - * subdir [IN] NULL for MH mailboxes, otherwise the subdir of the - * maildir mailbox to read from +/** + * mh_read_dir - Read a MH/maildir style mailbox + * @param ctx Current mailbox + * @param subdir NULL for MH mailboxes, + * otherwise the subdir of the maildir mailbox to read from */ static int mh_read_dir(struct Context *ctx, const char *subdir) { @@ -1296,7 +1308,9 @@ static int mh_read_dir(struct Context *ctx, const char *subdir) return 0; } -/* read a maildir style mailbox */ +/** + * maildir_read_dir - read a maildir style mailbox + */ static int maildir_read_dir(struct Context *ctx) { /* maildir looks sort of like MH, except that there are two subdirectories @@ -1468,11 +1482,13 @@ static int mh_close_message(struct Context *ctx, struct Message *msg) return safe_fclose(&msg->fp); } -/* +/** + * maildir_open_new_message - Open a new message in a maildir folder + * * Open a new (temporary) message in a maildir folder. * - * Note that this uses _almost_ the maildir file name format, but - * with a {cur,new} prefix. + * Note that this uses _almost_ the maildir file name format, + * but with a {cur,new} prefix. */ static int maildir_open_new_message(struct Message *msg, struct Context *dest, struct Header *hdr) @@ -1538,8 +1554,8 @@ static int maildir_open_new_message(struct Message *msg, struct Context *dest, } -/* - * Commit a message to a maildir folder. +/** + * _maildir_commit_message - Commit a message to a maildir folder * * msg->path contains the file name of a file in tmp/. We take the * flags from this file's name. @@ -1726,10 +1742,10 @@ static int mh_commit_message(struct Context *ctx, struct Message *msg) } -/* Sync a message in an MH folder. +/** + * mh_rewrite_message - Sync a message in an MH folder * - * This code is also used for attachment deletion in maildir - * folders. + * This code is also used for attachment deletion in maildir folders. */ static int mh_rewrite_message(struct Context *ctx, int msgno) { @@ -2000,13 +2016,15 @@ static void maildir_update_tables(struct Context *ctx, int *index_hint) mutt_clear_threads(ctx); } -/* This function handles arrival of new mail and reopening of - * maildir folders. The basic idea here is we check to see if either - * the new or cur subdirectories have changed, and if so, we scan them - * for the list of files. We check for newly added messages, and - * then merge the flags messages we already knew about. We don't treat - * either subdirectory differently, as mail could be copied directly into - * the cur directory from another agent. +/** + * maildir_check_mailbox - Check for new mail + * + * This function handles arrival of new mail and reopening of maildir folders. + * The basic idea here is we check to see if either the new or cur + * subdirectories have changed, and if so, we scan them for the list of files. + * We check for newly added messages, and then merge the flags messages we + * already knew about. We don't treat either subdirectory differently, as mail + * could be copied directly into the cur directory from another agent. */ static int maildir_check_mailbox(struct Context *ctx, int *index_hint) { @@ -2154,14 +2172,15 @@ static int maildir_check_mailbox(struct Context *ctx, int *index_hint) return 0; } -/* - * This function handles arrival of new mail and reopening of - * mh/maildir folders. Things are getting rather complex because we - * don't have a well-defined "mailbox order", so the tricks from - * mbox.c and mx.c won't work here. +/** + * mh_check_mailbox - Check for new mail * - * Don't change this code unless you _really_ understand what - * happens. + * This function handles arrival of new mail and reopening of mh/maildir + * folders. Things are getting rather complex because we don't have a + * well-defined "mailbox order", so the tricks from mbox.c and mx.c won't work + * here. + * + * Don't change this code unless you _really_ understand what happens. */ static int mh_check_mailbox(struct Context *ctx, int *index_hint) { @@ -2388,7 +2407,9 @@ bool maildir_update_flags(struct Context *ctx, struct Header *o, struct Header * } -/* +/** + * _maildir_open_find_message - Find a message in a maildir folder + * * These functions try to find a message in a maildir folder when it * has moved under our feet. Note that this code is rather expensive, but * then again, it's called rarely. diff --git a/mutt_idna.c b/mutt_idna.c index 27a9840f9..63183c006 100644 --- a/mutt_idna.c +++ b/mutt_idna.c @@ -289,7 +289,9 @@ int mutt_addrlist_to_local(struct Address *a) return 0; } -/* convert just for displaying purposes */ +/** + * mutt_addr_for_display - convert just for displaying purposes + */ const char *mutt_addr_for_display(struct Address *a) { char *user = NULL, *domain = NULL; @@ -312,7 +314,10 @@ const char *mutt_addr_for_display(struct Address *a) FREE(&local_mailbox); return buff; } -/* Convert an Envelope structure */ + +/** + * mutt_env_to_local - Convert an Envelope structure + */ void mutt_env_to_local(struct Envelope *e) { mutt_addrlist_to_local(e->return_path); diff --git a/mutt_lua.c b/mutt_lua.c index 46b74dac6..e477fcb16 100644 --- a/mutt_lua.c +++ b/mutt_lua.c @@ -49,6 +49,7 @@ static int _handle_panic(lua_State *l) lua_pop(l, 1); return -1; } + static int _handle_error(lua_State *l) { mutt_debug(1, "lua runtime error: %s\n", lua_tostring(l, -1)); diff --git a/mutt_notmuch.c b/mutt_notmuch.c index 0f0b8510b..0693ab3be 100644 --- a/mutt_notmuch.c +++ b/mutt_notmuch.c @@ -445,7 +445,7 @@ static bool query_window_check_timebase(const char *timebase) } /** - * query_window_reset - restores vfolder's search window to its original position + * query_window_reset - Restore vfolder's search window to its original position * * After moving a vfolder search window backward and forward, calling this function * will reset the search position to its original value, setting to 0 the user settable diff --git a/mutt_sasl.c b/mutt_sasl.c index e0310b799..ea01a8842 100644 --- a/mutt_sasl.c +++ b/mutt_sasl.c @@ -95,7 +95,11 @@ static sasl_callback_t mutt_sasl_callbacks[5]; static sasl_secret_t *secret_ptr = NULL; -/* utility function, stolen from sasl2 sample code */ +/** + * iptostring - Convert IP Address to string + * + * utility function, copied from sasl2 sample code + */ static int iptostring(const struct sockaddr *addr, socklen_t addrlen, char *out, unsigned outlen) { char hbuf[NI_MAXHOST], pbuf[NI_MAXSERV]; @@ -121,7 +125,9 @@ static int iptostring(const struct sockaddr *addr, socklen_t addrlen, char *out, return SASL_OK; } -/* mutt_sasl_cb_log: callback to log SASL messages */ +/** + * mutt_sasl_cb_log - callback to log SASL messages + */ static int mutt_sasl_cb_log(void *context, int priority, const char *message) { mutt_debug(priority, "SASL: %s\n", message); @@ -129,8 +135,11 @@ static int mutt_sasl_cb_log(void *context, int priority, const char *message) return SASL_OK; } -/* mutt_sasl_start: called before doing a SASL exchange - initialises library - * (if necessary). */ +/** + * mutt_sasl_start - Initialise SASL library + * + * Call before doing an SASL exchange - initialises library (if necessary). + */ static int mutt_sasl_start(void) { static bool sasl_init = false; @@ -163,7 +172,9 @@ static int mutt_sasl_start(void) return SASL_OK; } -/* mutt_sasl_cb_authname: callback to retrieve authname or user from Account */ +/** + * mutt_sasl_cb_authname - callback to retrieve authname or user from Account + */ static int mutt_sasl_cb_authname(void *context, int id, const char **result, unsigned *len) { struct Account *account = (struct Account *) context; @@ -258,9 +269,12 @@ static sasl_callback_t *mutt_sasl_get_callbacks(struct Account *account) return mutt_sasl_callbacks; } -/* mutt_sasl_client_new: wrapper for sasl_client_new which also sets various - * security properties. If this turns out to be fine for POP too we can - * probably stop exporting mutt_sasl_get_callbacks(). */ +/** + * mutt_sasl_client_new - wrapper for sasl_client_new + * + * which also sets various security properties. If this turns out to be fine + * for POP too we can probably stop exporting mutt_sasl_get_callbacks(). + */ int mutt_sasl_client_new(struct Connection *conn, sasl_conn_t **saslconn) { sasl_security_properties_t secprops; @@ -388,10 +402,13 @@ int mutt_sasl_interact(sasl_interact_t *interaction) return SASL_OK; } -/* mutt_sasl_conn_open: empty wrapper for underlying open function. We - * don't know in advance that a connection will use SASL, so we - * replace conn's methods with sasl methods when authentication - * is successful, using mutt_sasl_setup_conn */ +/** + * mutt_sasl_conn_open - empty wrapper for underlying open function + * + * We don't know in advance that a connection will use SASL, so we replace + * conn's methods with sasl methods when authentication is successful, using + * mutt_sasl_setup_conn + */ static int mutt_sasl_conn_open(struct Connection *conn) { struct SaslData *sasldata = NULL; @@ -405,8 +422,12 @@ static int mutt_sasl_conn_open(struct Connection *conn) return rc; } -/* mutt_sasl_conn_close: calls underlying close function and disposes of - * the sasl_conn_t object, then restores connection to pre-sasl state */ +/** + * mutt_sasl_conn_close - close SASL connection + * + * Calls underlying close function and disposes of the sasl_conn_t object, then + * restores connection to pre-sasl state + */ static int mutt_sasl_conn_close(struct Connection *conn) { struct SaslData *sasldata = NULL; @@ -551,6 +572,7 @@ static int mutt_sasl_conn_poll(struct Connection *conn) return rc; } + /* SASL can stack a protection layer on top of an existing connection. * To handle this, we store a saslconn_t in conn->sockdata, and write * wrappers which en/decode the read/write stream, then replace sockdata @@ -564,9 +586,12 @@ static int mutt_sasl_conn_poll(struct Connection *conn) * abstraction problem is that there is more in Connection than there * needs to be. Ideally it would have only (void*)data and methods. */ -/* mutt_sasl_setup_conn: replace connection methods, sockdata with - * SASL wrappers, for protection layers. Also get ssf, as a fastpath - * for the read/write methods. */ +/** + * mutt_sasl_setup_conn - Set up an SASL connection + * + * replace connection methods, sockdata with SASL wrappers, for protection + * layers. Also get ssf, as a fastpath for the read/write methods. + */ void mutt_sasl_setup_conn(struct Connection *conn, sasl_conn_t *saslconn) { struct SaslData *sasldata = safe_malloc(sizeof(struct SaslData)); diff --git a/mutt_socket.c b/mutt_socket.c index 2e10a8b2a..96960ec94 100644 --- a/mutt_socket.c +++ b/mutt_socket.c @@ -70,7 +70,9 @@ static int socket_preconnect(void) return 0; } -/* Wrappers */ +/** + * mutt_socket_open - Simple wrapper + */ int mutt_socket_open(struct Connection *conn) { int rc; @@ -137,10 +139,13 @@ int mutt_socket_write_d(struct Connection *conn, const char *buf, int len, int d return sent; } -/* poll whether reads would block. - * Returns: >0 if there is data to read, - * 0 if a read would block, - * -1 if this connection doesn't support polling */ +/** + * mutt_socket_poll - poll whether reads would block + * @return + * * >0 There is data to read, + * * 0 Read would block, + * * -1 Connection doesn't support polling + */ int mutt_socket_poll(struct Connection *conn) { if (conn->bufpos < conn->available) @@ -152,7 +157,9 @@ int mutt_socket_poll(struct Connection *conn) return -1; } -/* simple read buffering to speed things up. */ +/** + * mutt_socket_readchar - simple read buffering to speed things up + */ int mutt_socket_readchar(struct Connection *conn, char *c) { if (conn->bufpos >= conn->available) @@ -216,7 +223,9 @@ struct Connection *mutt_socket_head(void) return Connections; } -/* mutt_socket_free: remove connection from connection list and free it */ +/** + * mutt_socket_free - remove connection from connection list and free it + */ void mutt_socket_free(struct Connection *conn) { struct Connection *iter = NULL; @@ -245,7 +254,9 @@ void mutt_socket_free(struct Connection *conn) } } -/* socket_new_conn: allocate and initialise a new connection. */ +/** + * socket_new_conn - allocate and initialise a new connection + */ static struct Connection *socket_new_conn(void) { struct Connection *conn = NULL; @@ -256,11 +267,15 @@ static struct Connection *socket_new_conn(void) return conn; } -/* mutt_conn_find: find a connection off the list of connections whose - * account matches account. If start is not null, only search for - * connections after the given connection (allows higher level socket code - * to make more fine-grained searches than account info - eg in IMAP we may - * wish to find a connection which is not in IMAP_SELECTED state) */ +/** + * mutt_conn_find - Find a connection from a list + * + * find a connection off the list of connections whose account matches account. + * If start is not null, only search for connections after the given connection + * (allows higher level socket code to make more fine-grained searches than + * account info - eg in IMAP we may wish to find a connection which is not in + * IMAP_SELECTED state) + */ struct Connection *mutt_conn_find(const struct Connection *start, const struct Account *account) { struct Connection *conn = NULL; @@ -384,7 +399,9 @@ int raw_socket_poll(struct Connection *conn) return select(conn->fd + 1, &rfds, NULL, NULL, &tv); } -/* socket_connect: set up to connect to a socket fd. */ +/** + * socket_connect - set up to connect to a socket fd + */ static int socket_connect(int fd, struct sockaddr *sa) { int sa_size; diff --git a/mutt_ssl.c b/mutt_ssl.c index 5c44a0cc2..f842cc4be 100644 --- a/mutt_ssl.c +++ b/mutt_ssl.c @@ -94,9 +94,12 @@ struct SslSockData unsigned char isopen; }; -/* ssl certificate verification can behave strangely if there are expired - * certs loaded into the trusted store. This function filters out expired - * certs. +/** + * ssl_load_certificates - Load certificates and filter out the expired ones + * + * ssl certificate verification can behave strangely if there are expired certs + * loaded into the trusted store. This function filters out expired certs. + * * Previously the code used this form: * SSL_CTX_load_verify_locations (ssldata->ctx, SslCertFile, NULL); */ @@ -440,7 +443,9 @@ static bool check_certificate_expiration(X509 *peercert, bool silent) return true; } -/* port to mutt from msmtp's tls.c */ +/** + * hostname_match - Does the hostname match the certificate + */ static bool hostname_match(const char *hostname, const char *certname) { const char *cmp1 = NULL, *cmp2 = NULL; @@ -477,15 +482,17 @@ static bool hostname_match(const char *hostname, const char *certname) return true; } -/* - * OpenSSL library needs to be fed with sufficient entropy. On systems - * with /dev/urandom, this is done transparently by the library itself, - * on other systems we need to fill the entropy pool ourselves. +/** + * ssl_init - Initialist the SSL library + * + * OpenSSL library needs to be fed with sufficient entropy. On systems with + * /dev/urandom, this is done transparently by the library itself, on other + * systems we need to fill the entropy pool ourselves. * - * Even though only OpenSSL 0.9.5 and later will complain about the - * lack of entropy, we try to our best and fill the pool with older - * versions also. (That's the reason for the ugly #ifdefs and macros, - * otherwise I could have simply #ifdef'd the whole ssl_init funcion) + * Even though only OpenSSL 0.9.5 and later will complain about the lack of + * entropy, we try to our best and fill the pool with older versions also. + * (That's the reason for the ugly ifdefs and macros, otherwise I could have + * simply ifdef'd the whole ssl_init funcion) */ static int ssl_init(void) { @@ -654,7 +661,9 @@ static int check_certificate_file(X509 *peercert) return pass; } -/* port to mutt from msmtp's tls.c */ +/** + * check_host - Check the host on the certificate + */ static int check_host(X509 *x509cert, const char *hostname, char *err, size_t errlen) { int i, rc = 0; @@ -929,9 +938,13 @@ static int interactive_check_cert(X509 *cert, int idx, int len, SSL *ssl, int al return (done == 2); } -/* certificate verification callback, called for each certificate in the chain - * sent by the peer, starting from the root; returning 1 means that the given - * certificate is trusted, returning 0 immediately aborts the SSL connection */ +/** + * ssl_verify_callback - certificate verification callback + * + * called for each certificate in the chain sent by the peer, starting from the + * root; returning 1 means that the given certificate is trusted, returning 0 + * immediately aborts the SSL connection + */ static int ssl_verify_callback(int preverify_ok, X509_STORE_CTX *ctx) { char buf[STRING]; @@ -1052,8 +1065,12 @@ static int ssl_verify_callback(int preverify_ok, X509_STORE_CTX *ctx) return 1; } -/* ssl_negotiate: After SSL state has been initialized, attempt to negotiate - * SSL over the wire, including certificate checks. */ +/** + * ssl_negotiate - Attempt to negotiate SSL over the wire + * + * After SSL state has been initialized, attempt to negotiate SSL over the + * wire, including certificate checks. + */ static int ssl_negotiate(struct Connection *conn, struct SslSockData *ssldata) { int err; @@ -1213,8 +1230,11 @@ static int ssl_socket_open(struct Connection *conn) return 0; } -/* mutt_ssl_starttls: Negotiate TLS over an already opened connection. - * TODO: Merge this code better with ssl_socket_open. */ +/** + * mutt_ssl_starttls - Negotiate TLS over an already opened connection + * + * TODO: Merge this code better with ssl_socket_open. + */ int mutt_ssl_starttls(struct Connection *conn) { struct SslSockData *ssldata = NULL; diff --git a/mutt_ssl_gnutls.c b/mutt_ssl_gnutls.c index ec869ac50..9c5ec2d54 100644 --- a/mutt_ssl_gnutls.c +++ b/mutt_ssl_gnutls.c @@ -206,7 +206,11 @@ static int tls_starttls_close(struct Connection *conn) return rc; } -/* sanity-checking wrapper for gnutls_certificate_verify_peers */ +/** + * tls_verify_peers - wrapper for gnutls_certificate_verify_peers + * + * wrapper with sanity-checking + */ static gnutls_certificate_status_t tls_verify_peers(gnutls_session_t tlsstate) { int verify_ret; @@ -315,7 +319,9 @@ static int tls_check_stored_hostname(const gnutls_datum_t *cert, const char *hos return 0; } -/* this bit is based on read_ca_file() in gnutls */ +/** + * tls_compare_certificates - Compare certificates + */ static int tls_compare_certificates(const gnutls_datum_t *peercert) { gnutls_datum_t cert; @@ -1040,8 +1046,12 @@ static int tls_set_priority(tlssockdata *data) } #endif -/* tls_negotiate: After TLS state has been initialized, attempt to negotiate - * TLS over the wire, including certificate checks. */ +/** + * tls_negotiate - Negotiate TLS connection + * + * After TLS state has been initialized, attempt to negotiate TLS over the + * wire, including certificate checks. + */ static int tls_negotiate(struct Connection *conn) { tlssockdata *data = NULL; diff --git a/mutt_tunnel.c b/mutt_tunnel.c index 7437fccc4..4bdac8e51 100644 --- a/mutt_tunnel.c +++ b/mutt_tunnel.c @@ -186,7 +186,6 @@ static int tunnel_socket_poll(struct Connection *conn) return rc; } -/* -- public functions -- */ int mutt_tunnel_socket_setup(struct Connection *conn) { conn->conn_open = tunnel_socket_open; diff --git a/muttlib.c b/muttlib.c index eea0cf121..53b21948a 100644 --- a/muttlib.c +++ b/muttlib.c @@ -94,11 +94,12 @@ struct Body *mutt_new_body(void) } -/* 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 might fail, I guess. - * Renamed to mutt_adv_mktemp so I only have to change where it's - * called, and not all possible cases. +/** + * mutt_adv_mktemp - Advanced mktemp(3) + * + * 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 + * might fail, I guess. */ void mutt_adv_mktemp(char *s, size_t l) { @@ -127,7 +128,9 @@ void mutt_adv_mktemp(char *s, size_t l) } } -/* create a send-mode duplicate from a receive-mode body */ +/** + * mutt_copy_body - create a send-mode duplicate from a receive-mode body + */ int mutt_copy_body(FILE *fp, struct Body **tgt, struct Body *src) { if (!tgt || !src) @@ -422,7 +425,10 @@ void mutt_free_header(struct Header **h) FREE(h); } -/* returns true if the header contained in "s" is in list "t" */ +/** + * mutt_matches_list - Is the string in the list + * @return true if the header contained in "s" is in list "t" + */ bool mutt_matches_list(const char *s, struct List *t) { for (; t; t = t->next) @@ -433,7 +439,11 @@ bool mutt_matches_list(const char *s, struct List *t) return false; } -/* checks Ignore and UnIgnore using mutt_matches_list */ +/** + * mutt_matches_ignore - Does the string match the ignore list + * + * checks Ignore and UnIgnore using mutt_matches_list + */ int mutt_matches_ignore(const char *s) { return mutt_matches_list(s, Ignore) && !mutt_matches_list(s, UnIgnore); @@ -616,12 +626,13 @@ char *_mutt_expand_path(char *s, size_t slen, int rx) return s; } -/* 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 +/** + * mutt_gecos_name - Lookup a user's real name in /etc/passwd + * + * 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 * comma-separated list. - * Replace "&" by a capitalized version of the user's login - * name. + * Replace "&" by a capitalized version of the user's login name. */ char *mutt_gecos_name(char *dest, size_t destlen, struct passwd *pw) { @@ -713,7 +724,12 @@ void mutt_delete_parameter(const char *attribute, struct Parameter **p) } } -/* returns 1 if Mutt can't display this type of data, 0 otherwise */ +/** + * mutt_needs_mailcap - Does this type need a mailcap entry do display + * @return + * * true Mutt requires a mailcap entry to display + * * false otherwise + */ bool mutt_needs_mailcap(struct Body *m) { switch (m->type) @@ -800,7 +816,11 @@ void mutt_free_envelope(struct Envelope **p) FREE(p); } -/* move all the headers from extra not present in base into base */ +/** + * mutt_merge_envelopes - Merge the headers of two emails + * + * Move all the headers from extra not present in base into base + */ void mutt_merge_envelopes(struct Envelope *base, struct Envelope **extra) { /* copies each existing element if necessary, and sets the element @@ -953,7 +973,11 @@ void mutt_free_alias(struct Alias **p) } } -/* collapse the pathname using ~ or = when possible */ +/** + * mutt_pretty_mailbox - Shorten a mailbox path using '~' or '=' + * + * Collapse the pathname using ~ or = when possible + */ void mutt_pretty_mailbox(char *s, size_t buflen) { char *p = s, *q = s; @@ -1102,7 +1126,13 @@ void mutt_expand_fmt(char *dest, size_t destlen, const char *fmt, const char *sr } } -/* return 0 on success, -1 on abort, 1 on error */ +/** + * mutt_check_overwrite - Ask the user if overwriting is necessary + * @return + * * 0 on success + * * -1 on abort + * * 1 on error + */ int mutt_check_overwrite(const char *attname, const char *path, char *fname, size_t flen, int *append, char **directory) { @@ -1121,8 +1151,8 @@ int mutt_check_overwrite(const char *attname, const char *path, char *fname, { switch (mutt_multi_choice /* L10N: - Means "The path you specified as the destination file is a directory." - See the msgid "Save to file: " (alias.c, recvattach.c) */ + Means "The path you specified as the destination file is a directory." + See the msgid "Save to file: " (alias.c, recvattach.c) */ (_("File is a directory, save under it? [(y)es, (n)o, (a)ll]"), _("yna"))) { case 3: /* all */ @@ -1202,8 +1232,12 @@ void mutt_safe_path(char *s, size_t l, struct Address *a) *p = '_'; } -/* Note this function uses a fixed size buffer of LONG_STRING and so - * should only be used for visual modifications, such as disp_subj. */ +/** + * mutt_apply_replace - Apply replacements to a buffer + * + * Note this function uses a fixed size buffer of LONG_STRING and so + * should only be used for visual modifications, such as disp_subj. + */ char *mutt_apply_replace(char *dbuf, size_t dlen, char *sbuf, struct ReplaceList *rlist) { struct ReplaceList *l = NULL; @@ -1296,14 +1330,19 @@ char *mutt_apply_replace(char *dbuf, size_t dlen, char *sbuf, struct ReplaceList } -void mutt_FormatString(char *dest, /* output buffer */ - size_t destlen, /* output buffer len */ - size_t col, /* starting column (nonzero when called recursively) */ - int cols, /* maximum columns */ - const char *src, /* template string */ - format_t *callback, /* callback for processing */ - unsigned long data, /* callback data */ - enum FormatFlag flags) /* callback flags */ +/** + * mutt_FormatString - Expand expandos (%x) in a string + * @param dest output buffer + * @param destlen output buffer len + * @param col starting column (nonzero when called recursively) + * @param cols maximum columns + * @param src template string + * @param callback callback for processing + * @param data callback data + * @param flags callback flags + */ +void mutt_FormatString(char *dest, size_t destlen, size_t col, int cols, const char *src, + format_t *callback, unsigned long data, enum FormatFlag flags) { char prefix[SHORT_STRING], buf[LONG_STRING], *cp = NULL, *wptr = dest, ch; char ifstring[SHORT_STRING], elsestring[SHORT_STRING]; @@ -1806,9 +1845,13 @@ void mutt_FormatString(char *dest, /* output buffer */ *wptr = 0; } -/* 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 (|), - then we assume it is a command to run instead of a normal file. */ +/** + * mutt_open_read - Run a command to read from + * + * 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 (|), + * then we assume it is a command to run instead of a normal file. + */ FILE *mutt_open_read(const char *path, pid_t *thepid) { FILE *f = NULL; @@ -1842,7 +1885,13 @@ FILE *mutt_open_read(const char *path, pid_t *thepid) return f; } -/* returns 0 if OK to proceed, -1 to abort, 1 to retry */ +/** + * mutt_save_confirm - Ask the user to save + * @return + * * 0 if OK to proceed + * * -1 to abort + * * 1 to retry + */ int mutt_save_confirm(const char *s, struct stat *st) { char tmp[_POSIX_PATH_MAX]; @@ -2014,7 +2063,9 @@ void mutt_sleep(short s) sleep(s); } -/* Decrease a file's modification time by 1 second */ +/** + * mutt_decrease_mtime - Decrease a file's modification time by 1 second + */ time_t mutt_decrease_mtime(const char *f, struct stat *st) { struct utimbuf utim; @@ -2039,7 +2090,9 @@ time_t mutt_decrease_mtime(const char *f, struct stat *st) return mtime; } -/* sets mtime of 'to' to mtime of 'from' */ +/** + * mutt_set_mtime - sets mtime of 'to' to mtime of 'from' + */ void mutt_set_mtime(const char *from, const char *to) { struct utimbuf utim; @@ -2053,8 +2106,12 @@ void mutt_set_mtime(const char *from, const char *to) } } -/* set atime to current time, just as read() would do on !noatime. - * Silently ignored if unsupported. */ +/** + * mutt_touch_atime - set atime to current time + * + * This is just as read() would do on !noatime. + * Silently ignored if unsupported. + */ void mutt_touch_atime(int f) { #ifdef HAVE_FUTIMENS diff --git a/mx.c b/mx.c index 5950c2f13..e0754de9b 100644 --- a/mx.c +++ b/mx.c @@ -113,9 +113,13 @@ struct MxOps *mx_get_ops(int magic) #define mutt_is_spool(s) (mutt_strcmp(Spoolfile, s) == 0) -/* Args: - * excl if excl != 0, request an exclusive lock - * timeout should retry locking? +/** + * mx_lock_file - (try to) lock a file + * @param path Path to file + * @param fd File descriptor to file + * @param excl If set, try to lock exclusively + * @param timeout Retry after this time + * @return 0 on success, -1 on failure */ int mx_lock_file(const char *path, int fd, int excl, int timeout) { @@ -455,8 +459,8 @@ int mx_get_magic(const char *path) return magic; } -/* - * set DefaultMagic to the given value +/** + * mx_set_magic - set DefaultMagic to the given value */ int mx_set_magic(const char *s) { @@ -474,9 +478,12 @@ int mx_set_magic(const char *s) return 0; } -/* mx_access: Wrapper for access, checks permissions on a given mailbox. - * We may be interested in using ACL-style flags at some point, currently - * we use the normal access() flags. */ +/** + * mx_access - Wrapper for access, checks permissions on a given mailbox + * + * We may be interested in using ACL-style flags at some point, currently we + * use the normal access() flags. + */ int mx_access(const char *path, int flags) { #ifdef USE_IMAP @@ -530,16 +537,18 @@ static int mx_open_mailbox_append(struct Context *ctx, int flags) return ctx->mx_ops->open_append(ctx, flags); } -/* - * open a mailbox and parse it +/** + * mx_open_mailbox - Open a mailbox and parse it + * @param path Path to the mailbox + * @param flags See below + * @param pctx Reuse this Context (if supplied) * - * Args: - * flags MUTT_NOSORT do not sort mailbox - * MUTT_APPEND open mailbox for appending - * MUTT_READONLY open mailbox in read-only mode - * MUTT_QUIET only print error messages - * MUTT_PEEK revert atime where applicable - * ctx if non-null, context struct to use + * flags: + * * #MUTT_NOSORT do not sort mailbox + * * #MUTT_APPEND open mailbox for appending + * * #MUTT_READONLY open mailbox in read-only mode + * * #MUTT_QUIET only print error messages + * * #MUTT_PEEK revert atime where applicable */ struct Context *mx_open_mailbox(const char *path, int flags, struct Context *pctx) { @@ -644,7 +653,9 @@ struct Context *mx_open_mailbox(const char *path, int flags, struct Context *pct return ctx; } -/* free up memory associated with the mailbox context */ +/** + * mx_fastclose_mailbox - free up memory associated with the mailbox context + */ void mx_fastclose_mailbox(struct Context *ctx) { struct utimbuf ut; @@ -687,7 +698,9 @@ void mx_fastclose_mailbox(struct Context *ctx) memset(ctx, 0, sizeof(struct Context)); } -/* save changes to disk */ +/** + * sync_mailbox - save changes to disk + */ static int sync_mailbox(struct Context *ctx, int *index_hint) { if (!ctx->mx_ops || !ctx->mx_ops->sync) @@ -699,7 +712,9 @@ static int sync_mailbox(struct Context *ctx, int *index_hint) return ctx->mx_ops->sync(ctx, index_hint); } -/* move deleted mails to the trash folder */ +/** + * trash_append - move deleted mails to the trash folder + */ static int trash_append(struct Context *ctx) { struct Context ctx_trash; @@ -765,7 +780,9 @@ static int trash_append(struct Context *ctx) return 0; } -/* save changes and close mailbox */ +/** + * mx_close_mailbox - save changes and close mailbox + */ int mx_close_mailbox(struct Context *ctx, int *index_hint) { int i, move_messages = 0, purge = 1, read_msgs = 0; @@ -1020,7 +1037,9 @@ int mx_close_mailbox(struct Context *ctx, int *index_hint) return 0; } -/* update a Context structure's internal tables. */ +/** + * mx_update_tables - Update a Context structure's internal tables + */ void mx_update_tables(struct Context *ctx, int committing) { int i, j; @@ -1233,10 +1252,13 @@ int mx_sync_mailbox(struct Context *ctx, int *index_hint) return rc; } -/* args: - * dest destination mailbox - * hdr message being copied (required for maildir support, because +/** + * mx_open_new_message - Open a new message + * @param dest Destination mailbox + * @param hdr Message being copied (required for maildir support, because * the filename depends on the message flags) + * @param flags Flags, e.g. #MUTT_SET_DRAFT + * @return new Message */ struct Message *mx_open_new_message(struct Context *dest, struct Header *hdr, int flags) { @@ -1294,7 +1316,9 @@ struct Message *mx_open_new_message(struct Context *dest, struct Header *hdr, in return msg; } -/* check for new mail */ +/** + * mx_check_mailbox - check for new mail + */ int mx_check_mailbox(struct Context *ctx, int *index_hint) { if (!ctx || !ctx->mx_ops) @@ -1306,7 +1330,9 @@ int mx_check_mailbox(struct Context *ctx, int *index_hint) return ctx->mx_ops->check(ctx, index_hint); } -/* return a stream pointer for a message */ +/** + * mx_open_message - return a stream pointer for a message + */ struct Message *mx_open_message(struct Context *ctx, int msgno) { struct Message *msg = NULL; @@ -1325,7 +1351,9 @@ struct Message *mx_open_message(struct Context *ctx, int msgno) return msg; } -/* commit a message to a folder */ +/** + * mx_commit_message - commit a message to a folder + */ int mx_commit_message(struct Message *msg, struct Context *ctx) { if (!ctx->mx_ops || !ctx->mx_ops->commit_msg) @@ -1341,7 +1369,9 @@ int mx_commit_message(struct Message *msg, struct Context *ctx) return ctx->mx_ops->commit_msg(ctx, msg); } -/* close a pointer to a message */ +/** + * mx_close_message - close a pointer to a message + */ int mx_close_message(struct Context *ctx, struct Message **msg) { if (!ctx || !msg) @@ -1391,8 +1421,11 @@ void mx_alloc_memory(struct Context *ctx) } } -/* this routine is called to update the counts in the context structure for - * the last message header parsed. +/** + * mx_update_context - Update the Context's message counts + * + * this routine is called to update the counts in the context structure for the + * last message header parsed. */ void mx_update_context(struct Context *ctx, int new_messages) { diff --git a/ncrypt/crypt.c b/ncrypt/crypt.c index e32915e21..b2ecd78c0 100644 --- a/ncrypt/crypt.c +++ b/ncrypt/crypt.c @@ -53,7 +53,11 @@ #include "rfc822.h" #include "state.h" -/* print the current time to avoid spoofing of the signature output */ +/** + * crypt_current_time - Print the current time + * + * print the current time to avoid spoofing of the signature output + */ void crypt_current_time(struct State *s, char *app_name) { time_t t; @@ -351,13 +355,17 @@ int mutt_is_valid_multipart_pgp_encrypted(struct Body *b) return PGPENCRYPT; } -/* +/** + * mutt_is_malformed_multipart_pgp_encrypted - Check for malformed layout + * * This checks for the malformed layout caused by MS Exchange in * some cases: + * ``` * * * [BASE64-encoded] * [BASE64-encoded] + * ``` * See ticket #3742 */ int mutt_is_malformed_multipart_pgp_encrypted(struct Body *b) @@ -830,7 +838,9 @@ int crypt_get_keys(struct Header *msg, char **keylist, int oppenc_mode) return 0; } -/* +/** + * crypt_opportunistic_encrypt - Can all recipients be determined + * * Check if all recipients keys can be automatically determined. * Enable encryption if they can, otherwise disable encryption. */ @@ -875,8 +885,8 @@ static void crypt_fetch_signatures(struct Body ***signatures, struct Body *a, in } } -/* - * This routine verifies a "multipart/signed" body. +/** + * mutt_signed_handler - Verify a "multipart/signed" body. */ int mutt_signed_handler(struct Body *a, struct State *s) { @@ -997,7 +1007,10 @@ int mutt_signed_handler(struct Body *a, struct State *s) return rc; } -/* Obtain pointers to fingerprint or short or long key ID, if any. +/** + * crypt_get_fingerprint_or_id - Get the fingerprint or long key ID + * + * Obtain pointers to fingerprint or short or long key ID, if any. * See ncrypt.h for details. */ const char *crypt_get_fingerprint_or_id(char *p, const char **pphint, @@ -1078,9 +1091,10 @@ const char *crypt_get_fingerprint_or_id(char *p, const char **pphint, return pfcopy; } -/* - * Used by pgp_find_keys and find_keys to check if a crypt-hook - * value is a key id. +/** + * crypt_is_numerical_keyid - Is this a numerical keyid + * + * Check if a crypt-hook value is a key id. */ bool crypt_is_numerical_keyid(const char *s) { diff --git a/ncrypt/crypt_gpgme.c b/ncrypt/crypt_gpgme.c index 5a9769b47..a8ea029e5 100644 --- a/ncrypt/crypt_gpgme.c +++ b/ncrypt/crypt_gpgme.c @@ -131,7 +131,9 @@ static char *current_sender = NULL; * General helper functions. */ -/* accommodate for a redraw if needed */ +/** + * redraw_if_needed - accommodate for a redraw if needed + */ static void redraw_if_needed(gpgme_ctx_t ctx) { #if (GPGME_VERSION_NUMBER < 0x010800) @@ -148,14 +150,22 @@ static void redraw_if_needed(gpgme_ctx_t ctx) #endif } -/* return true when s points to a digit or letter. */ +/** + * digit_or_letter - Is the character a number or letter + * @param s Only the first character of this string is tested + * @return true when s points to a digit or letter + */ static int digit_or_letter(const unsigned char *s) { return ((*s >= '0' && *s < '9') || (*s >= 'A' && *s <= 'Z') || (*s >= 'a' && *s <= 'z')); } -/* Print the utf-8 encoded string BUF of length LEN bytes to stream - FP. Convert the character set. */ +/** + * print_utf8 - Write a UTF-8 string to a file + * + * Print the utf-8 encoded string BUF of length LEN bytes to stream FP. Convert + * the character set. + */ static void print_utf8(FILE *fp, const char *buf, size_t len) { char *tstr = NULL; @@ -176,8 +186,12 @@ static void print_utf8(FILE *fp, const char *buf, size_t len) * Key management. */ -/* Return the keyID for the key K. Note that this string is valid as - long as K is valid */ +/** + * crypt_keyid - Find the ID for the key + * + * Return the keyID for the key K. + * Note that this string is valid as long as K is valid + */ static const char *crypt_keyid(struct CryptKeyInfo *k) { const char *s = "????????"; @@ -193,7 +207,11 @@ static const char *crypt_keyid(struct CryptKeyInfo *k) return s; } -/* Return the long keyID for the key K. */ +/** + * crypt_long_keyid - Find the Long ID for the key + * + * Return the long keyID for the key K. + */ static const char *crypt_long_keyid(struct CryptKeyInfo *k) { const char *s = "????????????????"; @@ -206,7 +224,9 @@ static const char *crypt_long_keyid(struct CryptKeyInfo *k) return s; } -/* Return the short keyID for the key K. */ +/** + * crypt_short_keyid - Get the short keyID for the key K + */ static const char *crypt_short_keyid(struct CryptKeyInfo *k) { const char *s = "????????"; @@ -221,7 +241,9 @@ static const char *crypt_short_keyid(struct CryptKeyInfo *k) return s; } -/* Return the hexstring fingerprint from the key K. */ +/** + * crypt_fpr - Get the hexstring fingerprint from the key K + */ static const char *crypt_fpr(struct CryptKeyInfo *k) { const char *s = ""; @@ -254,7 +276,11 @@ static const char *crypt_fpr_or_lkeyid(struct CryptKeyInfo *k) return s; } -/* Parse FLAGS and return a statically allocated(!) string with them. */ +/** + * crypt_key_abilities - Parse key flags into a string + * + * Note: The string is statically allocated. + */ static char *crypt_key_abilities(int flags) { static char buff[3]; @@ -278,7 +304,11 @@ static char *crypt_key_abilities(int flags) return buff; } -/* Parse FLAGS and return a character describing the most important flag. */ +/** + * crypt_flags - Parse the key flags into a single character + * + * The returned character describes the most important flag. + */ static char crypt_flags(int flags) { if (flags & KEYFLAG_REVOKED) @@ -293,7 +323,9 @@ static char crypt_flags(int flags) return ' '; } -/* Return a copy of KEY. */ +/** + * crypt_copy_key - Return a copy of KEY + */ static struct CryptKeyInfo *crypt_copy_key(struct CryptKeyInfo *key) { struct CryptKeyInfo *k = NULL; @@ -309,8 +341,10 @@ static struct CryptKeyInfo *crypt_copy_key(struct CryptKeyInfo *key) return k; } -/* Release all the keys at the address of KEYLIST and set the address - to NULL. */ +/** + * crypt_free_key - Release all the keys in a list + * @param keylist List of keys + */ static void crypt_free_key(struct CryptKeyInfo **keylist) { struct CryptKeyInfo *k = NULL; @@ -328,7 +362,10 @@ static void crypt_free_key(struct CryptKeyInfo **keylist) } } -/* Return true when key K is valid. */ +/** + * crypt_key_is_valid - Is the key valid + * @return true when key K is valid + */ static bool crypt_key_is_valid(struct CryptKeyInfo *k) { if (k->flags & KEYFLAG_CANTUSE) @@ -336,7 +373,10 @@ static bool crypt_key_is_valid(struct CryptKeyInfo *k) return true; } -/* Return true when validity of KEY is sufficient. */ +/** + * crypt_id_is_strong - Is the key strong + * @return true when validity of KEY is sufficient + */ static int crypt_id_is_strong(struct CryptKeyInfo *key) { unsigned int is_strong = 0; @@ -362,14 +402,21 @@ static int crypt_id_is_strong(struct CryptKeyInfo *key) return is_strong; } -/* Return true when the KEY is valid, i.e. not marked as unusable. */ +/** + * crypt_id_is_valid - Is key ID valid + * ~return true when the KEY is valid, i.e. not marked as unusable + */ static int crypt_id_is_valid(struct CryptKeyInfo *key) { return !(key->flags & KEYFLAG_CANTUSE); } -/* Return a bit vector describing how well the addresses ADDR and - U_ADDR match and whether KEY is valid. */ +/** + * crypt_id_matches_addr - Does key ID match the address + * + * Return a bit vector describing how well the addresses ADDR and U_ADDR match + * and whether KEY is valid. + */ static int crypt_id_matches_addr(struct Address *addr, struct Address *u_addr, struct CryptKeyInfo *key) { @@ -396,8 +443,10 @@ static int crypt_id_matches_addr(struct Address *addr, struct Address *u_addr, * GPGME convenient functions. */ -/* Create a new gpgme context and return it. With FOR_SMIME set to - true, the protocol of the context is set to CMS. */ +/** + * create_gpgme_context - Create a new GPGME context + * @param for_smime If set, protocol of the context is set to CMS + */ static gpgme_ctx_t create_gpgme_context(int for_smime) { gpgme_error_t err; @@ -425,8 +474,11 @@ static gpgme_ctx_t create_gpgme_context(int for_smime) return ctx; } -/* Create a new gpgme data object. This is a wrapper to die on - error. */ +/** + * create_gpgme_data - Create a new GPGME data object + * + * This is a wrapper to die on error. + */ static gpgme_data_t create_gpgme_data(void) { gpgme_error_t err; @@ -442,9 +494,13 @@ static gpgme_data_t create_gpgme_data(void) return data; } -/* 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. */ +/** + * 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. + */ static gpgme_data_t body_to_data_object(struct Body *a, int convert) { char tempfile[_POSIX_PATH_MAX]; @@ -507,9 +563,12 @@ static gpgme_data_t body_to_data_object(struct Body *a, int convert) return data; } -/* 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. */ +/** + * 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. + */ static gpgme_data_t file_to_data_object(FILE *fp, long offset, long length) { int err = 0; @@ -525,7 +584,9 @@ static gpgme_data_t file_to_data_object(FILE *fp, long offset, long length) return data; } -/* Write a GPGME data object to the stream FP. */ +/** + * data_object_to_stream - Write a GPGME data object to a file + */ static int data_object_to_stream(gpgme_data_t data, FILE *fp) { int err; @@ -563,7 +624,9 @@ static int data_object_to_stream(gpgme_data_t data, FILE *fp) return 0; } -/* Copy a data object to a temporary file. +/** + * data_object_to_tempfile - Copy a data object to a temporary file + * * The tempfile name may be optionally passed in. * If ret_fp is passed in, the file will be rewound, left open, and returned * via that parameter. @@ -640,8 +703,11 @@ static void free_recipient_set(gpgme_key_t **p_rset) FREE(p_rset); } -/* Create a GpgmeRecipientSet from the keys in the string KEYLIST. - The keys must be space delimited. */ +/** + * create_recipient_set - Create a GpgmeRecipientSet from a string of keys + * + * The keys must be space delimited. + */ static gpgme_key_t *create_recipient_set(const char *keylist, gpgme_protocol_t protocol) { int err; @@ -708,7 +774,10 @@ static gpgme_key_t *create_recipient_set(const char *keylist, gpgme_protocol_t p return rset; } -/* Make sure that the correct signer is set. Returns 0 on success. */ +/** + * set_signer - Make sure that the correct signer is set + * @return 0 on success + */ static int set_signer(gpgme_ctx_t ctx, int for_smime) { char *signid = for_smime ? SmimeDefaultKey : PgpSignAs; @@ -767,11 +836,14 @@ static gpgme_error_t set_pka_sig_notation(gpgme_ctx_t ctx) return err; } -/* 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 */ +/** + * 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 + */ static char *encrypt_gpgme_object(gpgme_data_t plaintext, gpgme_key_t *rset, int use_smime, int combined_signed) { @@ -826,12 +898,15 @@ static char *encrypt_gpgme_object(gpgme_data_t plaintext, gpgme_key_t *rset, return outfile; } -/* 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. */ +/** + * get_micalg - Find the "micalg" parameter from the last GPGME operation + * + * 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. + */ static int get_micalg(gpgme_ctx_t ctx, int use_smime, char *buf, size_t buflen) { gpgme_sign_result_t result = NULL; @@ -877,9 +952,12 @@ static void print_time(time_t t, struct State *s) * Implementation of `sign_message'. */ -/* Sign the Message in body A either using OpenPGP or S/MIME when - USE_SMIME is passed as true. Returns the new body or NULL on - error. */ +/** + * sign_message - Sign a message + * @param a Message to sign + * @param use_smime If set, use SMIME instead of PGP + * @return the new body or NULL on error + */ static struct Body *sign_message(struct Body *a, int use_smime) { struct Body *t = NULL; @@ -1015,8 +1093,12 @@ struct Body *smime_gpgme_sign_message(struct Body *a) * Implementation of `encrypt_message'. */ -/* Encrypt the mail body A to all keys given as space separated keyids - or fingerprints in KEYLIST and return the encrypted body. */ +/** + * pgp_gpgme_encrypt_message - Encrypt a message + * + * Encrypt the mail body A to all keys given as space separated keyids + * or fingerprints in KEYLIST and return the encrypted body. + */ struct Body *pgp_gpgme_encrypt_message(struct Body *a, char *keylist, int sign) { char *outfile = NULL; @@ -1076,8 +1158,12 @@ struct Body *pgp_gpgme_encrypt_message(struct Body *a, char *keylist, int sign) * Implementation of `smime_build_smime_entity'. */ -/* Encrypt the mail body A to all keys given as space separated - fingerprints in KEYLIST and return the S/MIME encrypted body. */ +/** + * smime_gpgme_build_smime_entity - Encrypt the email body to all recipients + * + * Encrypt the mail body A to all keys given as space separated fingerprints in + * KEYLIST and return the S/MIME encrypted body. + */ struct Body *smime_gpgme_build_smime_entity(struct Body *a, char *keylist) { char *outfile = NULL; @@ -1127,8 +1213,11 @@ struct Body *smime_gpgme_build_smime_entity(struct Body *a, char *keylist) * Implementation of `verify_one'. */ -/* Display the common attributes of the signature summary SUM. - Return 1 if there is is a severe warning. +/** + * show_sig_summary - Show a signature summary + * @return 1 if there is is a severe warning + * + * Display the common attributes of the signature summary SUM. */ static int show_sig_summary(unsigned long sum, gpgme_ctx_t ctx, gpgme_key_t key, int idx, struct State *s, gpgme_signature_t sig) @@ -1303,7 +1392,9 @@ static void show_fingerprint(gpgme_key_t key, struct State *state) FREE(&buf); } -/* Show the validity of a key used for one signature. */ +/** + * show_one_sig_validity - Show the validity of a key used for one signature + */ static void show_one_sig_validity(gpgme_ctx_t ctx, int idx, struct State *s) { gpgme_verify_result_t result = NULL; @@ -1395,13 +1486,18 @@ static void print_smime_keyinfo(const char *msg, gpgme_signature_t sig, } } -/* Show information about one 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. - - Return values are: 0 for normal procession, 1 for a bad signature, - 2 for a signature with a warning or -1 for no more signature. */ +/** + * show_one_sig_status - Show information about one signature + * @return + * * 0 Normal procession + * * 1 A bad signature + * * 2 A signature with a warning + * * -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. + */ static int show_one_sig_status(gpgme_ctx_t ctx, int idx, struct State *s) { const char *fpr = NULL; @@ -1514,8 +1610,11 @@ static int show_one_sig_status(gpgme_ctx_t ctx, int idx, struct State *s) return anybad ? 1 : anywarn ? 2 : 0; } -/* Do the actual verification step. With IS_SMIME set to true we - assume S/MIME (surprise!) */ +/** + * verify_one - Do the actual verification step + * + * With IS_SMIME set to true we assume S/MIME (surprise!) + */ static int verify_one(struct Body *sigbdy, struct State *s, const char *tempfile, int is_smime) { int badsig = -1; @@ -1655,12 +1754,15 @@ int smime_gpgme_verify_one(struct Body *sigbdy, struct State *s, const char *tem * Implementation of `decrypt_part'. */ -/* Decrypt a PGP or SMIME message (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 - encrypted and signed message, for S/MIME it returns true when it is - not a encrypted but a signed message. */ +/** + * decrypt_part - Decrypt a PGP or SMIME message + * + * (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 + * encrypted and signed message, for S/MIME it returns true when it is not a + * encrypted but a signed message. + */ static struct Body *decrypt_part(struct Body *a, struct State *s, FILE *fpout, int is_smime, int *r_is_signed) { @@ -1807,8 +1909,13 @@ restart: return tattach; } -/* Decrypt a PGP/MIME message in FPIN and B and return a new body and - the stream in CUR and FPOUT. Returns 0 on success. */ +/** + * pgp_gpgme_decrypt_mime - Decrypt a PGP/MIME message + * @return 0 on success + * + * The message in FPIN and B and return a new body and the stream in CUR and + * FPOUT. + */ int pgp_gpgme_decrypt_mime(FILE *fpin, FILE **fpout, struct Body *b, struct Body **cur) { char tempfile[_POSIX_PATH_MAX]; @@ -1892,8 +1999,13 @@ bail: return rv; } -/* Decrypt a S/MIME message in FPIN and B and return a new body and - the stream in CUR and FPOUT. Returns 0 on success. */ +/** + * smime_gpgme_decrypt_mime - Decrypt a S/MIME message + * @returns 0 on success + * + * The message in FPIN and B and return a new body and + * the stream in CUR and FPOUT. + */ int smime_gpgme_decrypt_mime(FILE *fpin, FILE **fpout, struct Body *b, struct Body **cur) { char tempfile[_POSIX_PATH_MAX]; @@ -2274,17 +2386,18 @@ void pgp_gpgme_invoke_import(const char *fname) * Implementation of `application_handler'. */ -/* - Copy a clearsigned message, and strip the signature and PGP's - dash-escaping. - - 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 around in the main handler. - - (Note that we aren't worse than Outlook & Cie in this, and also - note that we can successfully handle anything produced by any - existing versions of mutt.) */ +/** + * copy_clearsigned - Copy a clearsigned message + * + * strip the signature and PGP's dash-escaping. + * + * 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 + * around in the main handler. + * + * (Note that we aren't worse than Outlook & Cie in this, and also note that we + * can successfully handle anything produced by any existing versions of mutt.) + */ static void copy_clearsigned(gpgme_data_t data, struct State *s, char *charset) { char buf[HUGE_STRING]; @@ -2341,7 +2454,9 @@ static void copy_clearsigned(gpgme_data_t data, struct State *s, char *charset) safe_fclose(&fp); } -/* Support for classic_application/pgp */ +/** + * pgp_gpgme_application_handler - Support for classic_application/pgp + */ int pgp_gpgme_application_handler(struct Body *m, struct State *s) { int needpass = -1; @@ -2584,7 +2699,9 @@ int pgp_gpgme_application_handler(struct Body *m, struct State *s) * Implementation of `encrypted_handler'. */ -/* MIME handler for pgp/mime encrypted messages. +/** + * pgp_gpgme_encrypted_handler - MIME handler for pgp/mime encrypted messages + * * This handler is passed the application/octet-stream directly. * The caller must propagate a->goodsig to its parent. */ @@ -2661,7 +2778,9 @@ int pgp_gpgme_encrypted_handler(struct Body *a, struct State *s) return rc; } -/* Support for application/smime */ +/** + * smime_gpgme_application_handler - Support for application/smime + */ int smime_gpgme_application_handler(struct Body *a, struct State *s) { char tempfile[_POSIX_PATH_MAX]; @@ -2735,19 +2854,26 @@ int smime_gpgme_application_handler(struct Body *a, struct State *s) return rc; } -/* - * Format an entry on the CRYPT key selection menu. +/** + * crypt_entry_fmt - Format an entry on the CRYPT key selection menu + * + * * \%u user id + * * \%n number + * * \%t trust/validity of the key-uid association + * * \%p protocol + * * \%[...] date of key using strftime(3) + * + * * \%k key id + * * \%a algorithm + * * \%l length + * * \%f flags + * * \%c capabilities * - * %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 - * %p protocol - * %[...] date of key using strftime(3) + * * \%K key id of the principal key + * * \%A algorithm of the principal key + * * \%L length of the principal key + * * \%F flags of the principal key + * * \%C capabilities of the principal key */ static const char *crypt_entry_fmt(char *dest, size_t destlen, size_t col, int cols, char op, const char *src, const char *prefix, @@ -2947,7 +3073,9 @@ static const char *crypt_entry_fmt(char *dest, size_t destlen, size_t col, int c return src; } -/* Used by the display function to format a line. */ +/** + * crypt_entry - Used by the display function to format a line + */ static void crypt_entry(char *s, size_t l, struct Menu *menu, int num) { struct CryptKeyInfo **key_table = (struct CryptKeyInfo **) menu->data; @@ -2960,7 +3088,9 @@ static void crypt_entry(char *s, size_t l, struct Menu *menu, int num) crypt_entry_fmt, (unsigned long) &entry, MUTT_FORMAT_ARROWCURSOR); } -/* Compare two addresses and the keyid to be used for sorting. */ +/** + * _crypt_compare_address - Compare Key addresses and IDs for sorting + */ static int _crypt_compare_address(const void *a, const void *b) { struct CryptKeyInfo **s = (struct CryptKeyInfo **) a; @@ -2979,7 +3109,9 @@ static int crypt_compare_address(const void *a, const void *b) _crypt_compare_address(a, b)); } -/* Compare two key IDs and the addresses to be used for sorting. */ +/** + * _crypt_compare_keyid - Compare Key IDs and addresses for sorting + */ static int _crypt_compare_keyid(const void *a, const void *b) { struct CryptKeyInfo **s = (struct CryptKeyInfo **) a; @@ -2998,7 +3130,9 @@ static int crypt_compare_keyid(const void *a, const void *b) _crypt_compare_keyid(a, b)); } -/* Compare 2 creation dates and the addresses. For sorting. */ +/** + * _crypt_compare_date - Compare Key creation dates and addresses for sorting + */ static int _crypt_compare_date(const void *a, const void *b) { struct CryptKeyInfo **s = (struct CryptKeyInfo **) a; @@ -3024,8 +3158,12 @@ static int crypt_compare_date(const void *a, const void *b) _crypt_compare_date(a, b)); } -/* Compare two trust values, the key length, the creation dates. the - addresses and the key IDs. For sorting. */ +/** + * _crypt_compare_trust - Compare the trust of keys for sorting + * + * Compare two trust values, the key length, the creation dates. the addresses + * and the key IDs. + */ static int _crypt_compare_trust(const void *a, const void *b) { struct CryptKeyInfo **s = (struct CryptKeyInfo **) a; @@ -3068,8 +3206,11 @@ static int crypt_compare_trust(const void *a, const void *b) _crypt_compare_trust(a, b)); } -/* Print the X.500 Distinguished Name part KEY from the array of parts - DN to FP. */ +/** + * print_dn_part - Print the X.500 Distinguished Name + * + * Print the X.500 Distinguished Name part KEY from the array of parts DN to FP. + */ static int print_dn_part(FILE *fp, struct DnArray *dn, const char *key) { int any = 0; @@ -3087,7 +3228,9 @@ static int print_dn_part(FILE *fp, struct DnArray *dn, const char *key) return any; } -/* Print all parts of a DN in a standard sequence. */ +/** + * print_dn_parts - Print all parts of a DN in a standard sequence + */ static void print_dn_parts(FILE *fp, struct DnArray *dn) { static const char *const stdpart[] = { @@ -3123,7 +3266,9 @@ static void print_dn_parts(FILE *fp, struct DnArray *dn) fputs(")", fp); } -/* Parse an RDN; this is a helper to parse_dn(). */ +/** + * parse_dn_part - Parse an RDN; this is a helper to parse_dn() + */ static const char *parse_dn_part(struct DnArray *array, const char *string) { const char *s = NULL, *s1 = NULL; @@ -3209,9 +3354,12 @@ static const char *parse_dn_part(struct DnArray *array, const char *string) return s; } -/* Parse a DN and return an array-ized one. This is not a validating - parser and it does not support any old-stylish syntax; gpgme is - expected to return only rfc2253 compatible strings. */ +/** + * parse_dn - Parse a DN and return an array-ized one + * + * This is not a validating parser and it does not support any old-stylish + * syntax; gpgme is expected to return only rfc2253 compatible strings. + */ static struct DnArray *parse_dn(const char *string) { struct DnArray *array = NULL; @@ -3268,10 +3416,13 @@ failure: return NULL; } -/* Print a nice representation of the USERID and 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. */ +/** + * parse_and_print_user_id - Print a nice representation of the userid + * + * 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. + */ static void parse_and_print_user_id(FILE *fp, const char *userid) { const char *s = NULL; @@ -3375,7 +3526,9 @@ static const char *const KeyInfoPrompts[] = { int KeyInfoPadding[KIP_END] = { 0 }; -/* Print verbose information about a key or certificate to FP. */ +/** + * print_key_info - Verbose information about a key or certificate to a file + */ static void print_key_info(gpgme_key_t key, FILE *fp) { int idx; @@ -3629,7 +3782,9 @@ static void print_key_info(gpgme_key_t key, FILE *fp) } } -/* Show detailed information about the selected key */ +/** + * verify_key - Show detailed information about the selected key + */ static void verify_key(struct CryptKeyInfo *key) { FILE *fp = NULL; @@ -3698,9 +3853,11 @@ leave: * Implementation of `findkeys'. */ -/* Convert List into a pattern string suitable to be passed to GPGME. - We need to convert spaces in an item into a '+' and '%' into - "%25". */ +/** + * list_to_pattern - Convert List to GPGME-compatible pattern + * + * We need to convert spaces in an item into a '+' and '%' into "%25". + */ static char *list_to_pattern(struct List *list) { struct List *l = NULL; @@ -3753,8 +3910,11 @@ static char *list_to_pattern(struct List *list) return pattern; } -/* Return a list of keys which are candidates for the selection. - Select by looking at the HINTS list. */ +/** + * get_candidates - Get a list of keys which are candidates for the selection + * + * Select by looking at the HINTS list. + */ static struct CryptKeyInfo *get_candidates(struct List *hints, unsigned int app, int secret) { struct CryptKeyInfo *db = NULL, *k = NULL, **kend = NULL; @@ -3901,8 +4061,11 @@ static struct CryptKeyInfo *get_candidates(struct List *hints, unsigned int app, return db; } -/* Add the string STR to the list HINTS. This list is later used to - match addresses. */ +/** + * crypt_add_string_to_hints - Add the string STR to the list HINTS + * + * This list is later used to match addresses. + */ static struct List *crypt_add_string_to_hints(struct List *hints, const char *str) { char *scratch = NULL; @@ -3921,9 +4084,12 @@ static struct List *crypt_add_string_to_hints(struct List *hints, const char *st return hints; } -/* 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. */ +/** + * crypt_select_key - Get the user to select a key + * + * 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. + */ static struct CryptKeyInfo *crypt_select_key(struct CryptKeyInfo *keys, struct Address *p, const char *s, unsigned int app, int *forced_valid) @@ -4311,11 +4477,15 @@ static struct CryptKeyInfo *crypt_getkeybystr(char *p, short abilities, return NULL; } -/* 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. */ +/** + * crypt_ask_for_key - Ask the user for a 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. + */ static struct CryptKeyInfo *crypt_ask_for_key(char *tag, char *whatfor, short abilities, unsigned int app, int *forced_valid) { @@ -4369,10 +4539,13 @@ static struct CryptKeyInfo *crypt_ask_for_key(char *tag, char *whatfor, short ab /* not reached */ } -/* This routine attempts to find the keyids of the recipients of a - message. It returns NULL if any of the keys can not be found. - If oppenc_mode is true, only keys that can be determined without - prompting will be used. */ +/** + * find_keys - Find keys of the recipients of the message + * @return NULL if any of the keys can not be found + * + * If oppenc_mode is true, only keys that can be determined without prompting + * will be used. + */ static char *find_keys(struct Address *adrlist, unsigned int app, int oppenc_mode) { struct List *crypt_hook_list = NULL, *crypt_hook = NULL; @@ -4570,8 +4743,9 @@ bail: * Implementation of `init'. */ -/* This function contains common code needed to be executed for both the pgp - * and smime support of gpgme. */ +/** + * init_common - Initialise code common to PGP and SMIME parts of GPGME + */ static void init_common(void) { /* this initialization should only run one time, but it may be called by diff --git a/ncrypt/crypt_mod.c b/ncrypt/crypt_mod.c index 43dbdc3f6..a3b867235 100644 --- a/ncrypt/crypt_mod.c +++ b/ncrypt/crypt_mod.c @@ -37,7 +37,9 @@ struct CryptModule static struct CryptModule *modules; -/* Register a new crypto module. */ +/** + * crypto_module_register - Register a new crypto module + */ void crypto_module_register(crypt_module_specs_t specs) { struct CryptModule *module_new = safe_malloc(sizeof(*module_new)); @@ -49,8 +51,12 @@ void crypto_module_register(crypt_module_specs_t specs) modules = module_new; } -/* Return the crypto module specs for IDENTIFIER. This function is - usually used via the CRYPT_MOD_CALL[_CHECK] macros. */ +/** + * crypto_module_lookup - Lookup a crypto module by name + * + * Return the crypto module specs for IDENTIFIER. + * This function is usually used via the CRYPT_MOD_CALL[_CHECK] macros. + */ crypt_module_specs_t crypto_module_lookup(int identifier) { struct CryptModule *module = modules; diff --git a/ncrypt/crypt_mod_pgp_classic.c b/ncrypt/crypt_mod_pgp_classic.c index d9e0cbcef..cd04688b4 100644 --- a/ncrypt/crypt_mod_pgp_classic.c +++ b/ncrypt/crypt_mod_pgp_classic.c @@ -51,6 +51,7 @@ static int crypt_mod_pgp_decrypt_mime(FILE *a, FILE **b, struct Body *c, struct { return pgp_decrypt_mime(a, b, c, d); } + static int crypt_mod_pgp_application_handler(struct Body *m, struct State *s) { return pgp_application_pgp_handler(m, s); diff --git a/ncrypt/crypt_mod_smime_classic.c b/ncrypt/crypt_mod_smime_classic.c index bf2389c4a..c4275d1e3 100644 --- a/ncrypt/crypt_mod_smime_classic.c +++ b/ncrypt/crypt_mod_smime_classic.c @@ -50,6 +50,7 @@ static int crypt_mod_smime_decrypt_mime(FILE *a, FILE **b, struct Body *c, struc { return smime_decrypt_mime(a, b, c, d); } + static int crypt_mod_smime_application_handler(struct Body *m, struct State *s) { return smime_application_smime_handler(m, s); diff --git a/ncrypt/cryptglue.c b/ncrypt/cryptglue.c index e335ed422..e8328e647 100644 --- a/ncrypt/cryptglue.c +++ b/ncrypt/cryptglue.c @@ -113,7 +113,11 @@ void crypt_init(void) #endif } -/* Show a message that a backend will be invoked. */ +/** + * crypt_invoke_message - Display an informative message + * + * Show a message that a backend will be invoked. + */ void crypt_invoke_message(int type) { if ((WithCrypto & APPLICATION_PGP) && (type & APPLICATION_PGP)) @@ -123,12 +127,12 @@ void crypt_invoke_message(int type) } /* + * PGP + */ - PGP - -*/ - -/* Reset a PGP passphrase */ +/** + * crypt_pgp_void_passphrase - Reset a PGP passphrase + */ void crypt_pgp_void_passphrase(void) { if (CRYPT_MOD_CALL_CHECK(PGP, void_passphrase)) @@ -143,7 +147,9 @@ int crypt_pgp_valid_passphrase(void) return 0; } -/* Decrypt a PGP/MIME message. */ +/** + * crypt_pgp_decrypt_mime - Decrypt a PGP/MIME message + */ int crypt_pgp_decrypt_mime(FILE *a, FILE **b, struct Body *c, struct Body **d) { if (CRYPT_MOD_CALL_CHECK(PGP, decrypt_mime)) @@ -152,7 +158,9 @@ int crypt_pgp_decrypt_mime(FILE *a, FILE **b, struct Body *c, struct Body **d) return -1; } -/* MIME handler for the application/pgp content-type. */ +/** + * crypt_pgp_application_pgp_handler - MIME handler for the pgp content-type + */ int crypt_pgp_application_pgp_handler(struct Body *m, struct State *s) { if (CRYPT_MOD_CALL_CHECK(PGP, application_handler)) @@ -161,7 +169,9 @@ int crypt_pgp_application_pgp_handler(struct Body *m, struct State *s) return -1; } -/* MIME handler for an PGP/MIME encrypted message. */ +/** + * crypt_pgp_encrypted_handler - MIME handler for an PGP/MIME encrypted message + */ int crypt_pgp_encrypted_handler(struct Body *a, struct State *s) { if (CRYPT_MOD_CALL_CHECK(PGP, encrypted_handler)) @@ -170,14 +180,15 @@ int crypt_pgp_encrypted_handler(struct Body *a, struct State *s) return -1; } -/* fixme: needs documentation. */ void crypt_pgp_invoke_getkeys(struct Address *addr) { if (CRYPT_MOD_CALL_CHECK(PGP, pgp_invoke_getkeys)) (CRYPT_MOD_CALL(PGP, pgp_invoke_getkeys))(addr); } -/* Check for a traditional PGP message in body B. */ +/** + * crypt_pgp_check_traditional - Check for a traditional PGP message in body B + */ int crypt_pgp_check_traditional(FILE *fp, struct Body *b, int tagged_only) { if (CRYPT_MOD_CALL_CHECK(PGP, pgp_check_traditional)) @@ -186,7 +197,6 @@ int crypt_pgp_check_traditional(FILE *fp, struct Body *b, int tagged_only) return 0; } -/* fixme: needs documentation. */ struct Body *crypt_pgp_traditional_encryptsign(struct Body *a, int flags, char *keylist) { if (CRYPT_MOD_CALL_CHECK(PGP, pgp_traditional_encryptsign)) @@ -195,7 +205,9 @@ struct Body *crypt_pgp_traditional_encryptsign(struct Body *a, int flags, char * return NULL; } -/* Generate a PGP public key attachment. */ +/** + * crypt_pgp_make_key_attachment - Generate a PGP public key attachment + */ struct Body *crypt_pgp_make_key_attachment(char *tempf) { if (CRYPT_MOD_CALL_CHECK(PGP, pgp_make_key_attachment)) @@ -204,10 +216,12 @@ struct Body *crypt_pgp_make_key_attachment(char *tempf) return NULL; } -/* This routine attempts to find the keyids of the recipients of a - message. It returns NULL if any of the keys can not be found. - If oppenc_mode is true, only keys that can be determined without - prompting will be used. */ +/** + * crypt_pgp_findkeys - Find the keyids of the recipients of the message + * + * It returns NULL if any of the keys can not be found. If oppenc_mode is + * true, only keys that can be determined without prompting will be used. + */ char *crypt_pgp_findkeys(struct Address *adrlist, int oppenc_mode) { if (CRYPT_MOD_CALL_CHECK(PGP, findkeys)) @@ -216,7 +230,9 @@ char *crypt_pgp_findkeys(struct Address *adrlist, int oppenc_mode) return NULL; } -/* Create a new body with a PGP signed message from A. */ +/** + * crypt_pgp_sign_message - Create a new body with a PGP signed message from A + */ struct Body *crypt_pgp_sign_message(struct Body *a) { if (CRYPT_MOD_CALL_CHECK(PGP, sign_message)) @@ -225,8 +241,12 @@ struct Body *crypt_pgp_sign_message(struct Body *a) return NULL; } -/* Warning: A is no longer freed in this routine, you need to free it - later. This is necessary for $fcc_attach. */ +/** + * crypt_pgp_encrypt_message - Encrypt a message + * + * Warning: A is no longer freed in this routine, you need to free it later. + * This is necessary for $fcc_attach. + */ struct Body *crypt_pgp_encrypt_message(struct Body *a, char *keylist, int sign) { if (CRYPT_MOD_CALL_CHECK(PGP, pgp_encrypt_message)) @@ -235,14 +255,15 @@ struct Body *crypt_pgp_encrypt_message(struct Body *a, char *keylist, int sign) return NULL; } -/* Invoke the PGP command to import a key. */ +/** + * crypt_pgp_invoke_import - Invoke the PGP command to import a key + */ void crypt_pgp_invoke_import(const char *fname) { if (CRYPT_MOD_CALL_CHECK(PGP, pgp_invoke_import)) (CRYPT_MOD_CALL(PGP, pgp_invoke_import))(fname); } -/* fixme: needs documentation */ int crypt_pgp_verify_one(struct Body *sigbdy, struct State *s, const char *tempf) { if (CRYPT_MOD_CALL_CHECK(PGP, verify_one)) @@ -259,7 +280,6 @@ int crypt_pgp_send_menu(struct Header *msg) return 0; } -/* fixme: needs documentation */ void crypt_pgp_extract_keys_from_attachment_list(FILE *fp, int tag, struct Body *top) { if (CRYPT_MOD_CALL_CHECK(PGP, pgp_extract_keys_from_attachment_list)) @@ -273,12 +293,12 @@ void crypt_pgp_set_sender(const char *sender) } /* + * S/MIME + */ - S/MIME - -*/ - -/* Reset an SMIME passphrase */ +/** + * crypt_smime_void_passphrase - Reset an SMIME passphrase + */ void crypt_smime_void_passphrase(void) { if (CRYPT_MOD_CALL_CHECK(SMIME, void_passphrase)) @@ -293,7 +313,9 @@ int crypt_smime_valid_passphrase(void) return 0; } -/* Decrypt am S/MIME message. */ +/** + * crypt_smime_decrypt_mime - Decrypt am S/MIME message + */ int crypt_smime_decrypt_mime(FILE *a, FILE **b, struct Body *c, struct Body **d) { if (CRYPT_MOD_CALL_CHECK(SMIME, decrypt_mime)) @@ -302,7 +324,9 @@ int crypt_smime_decrypt_mime(FILE *a, FILE **b, struct Body *c, struct Body **d) return -1; } -/* MIME handler for the application/smime content-type. */ +/** + * crypt_smime_application_smime_handler - Handler for application/smime + */ int crypt_smime_application_smime_handler(struct Body *m, struct State *s) { if (CRYPT_MOD_CALL_CHECK(SMIME, application_handler)) @@ -311,21 +335,24 @@ int crypt_smime_application_smime_handler(struct Body *m, struct State *s) return -1; } -/* MIME handler for an PGP/MIME encrypted message. */ +/** + * crypt_smime_encrypted_handler - Handler for an PGP/MIME encrypted message + */ void crypt_smime_encrypted_handler(struct Body *a, struct State *s) { if (CRYPT_MOD_CALL_CHECK(SMIME, encrypted_handler)) (CRYPT_MOD_CALL(SMIME, encrypted_handler))(a, s); } -/* fixme: Needs documentation. */ void crypt_smime_getkeys(struct Envelope *env) { if (CRYPT_MOD_CALL_CHECK(SMIME, smime_getkeys)) (CRYPT_MOD_CALL(SMIME, smime_getkeys))(env); } -/* Check that the sender matches. */ +/** + * crypt_smime_verify_sender - Check that the sender matches + */ int crypt_smime_verify_sender(struct Header *h) { if (CRYPT_MOD_CALL_CHECK(SMIME, smime_verify_sender)) @@ -334,10 +361,12 @@ int crypt_smime_verify_sender(struct Header *h) return 1; } -/* This routine attempts to find the keyids of the recipients of a - message. It returns NULL if any of the keys can not be found. - If oppenc_mode is true, only keys that can be determined without - prompting will be used. */ +/** + * crypt_smime_findkeys - Find the keyids of the recipients of the message + * + * It returns NULL if any of the keys can not be found. If oppenc_mode is + * true, only keys that can be determined without prompting will be used. + */ char *crypt_smime_findkeys(struct Address *adrlist, int oppenc_mode) { if (CRYPT_MOD_CALL_CHECK(SMIME, findkeys)) @@ -346,7 +375,6 @@ char *crypt_smime_findkeys(struct Address *adrlist, int oppenc_mode) return NULL; } -/* fixme: Needs documentation. */ struct Body *crypt_smime_sign_message(struct Body *a) { if (CRYPT_MOD_CALL_CHECK(SMIME, sign_message)) @@ -355,7 +383,6 @@ struct Body *crypt_smime_sign_message(struct Body *a) return NULL; } -/* fixme: needs documentation. */ struct Body *crypt_smime_build_smime_entity(struct Body *a, char *certlist) { if (CRYPT_MOD_CALL_CHECK(SMIME, smime_build_smime_entity)) @@ -364,14 +391,17 @@ struct Body *crypt_smime_build_smime_entity(struct Body *a, char *certlist) return NULL; } -/* Add a certificate and update index file (externally). */ +/** + * crypt_smime_invoke_import - Add a certificate and update index file + * + * This is done externally. + */ void crypt_smime_invoke_import(char *infile, char *mailbox) { if (CRYPT_MOD_CALL_CHECK(SMIME, smime_invoke_import)) (CRYPT_MOD_CALL(SMIME, smime_invoke_import))(infile, mailbox); } -/* fixme: needs documentation */ int crypt_smime_verify_one(struct Body *sigbdy, struct State *s, const char *tempf) { if (CRYPT_MOD_CALL_CHECK(SMIME, verify_one)) diff --git a/ncrypt/pgp.c b/ncrypt/pgp.c index b647d03ea..b82515d2a 100644 --- a/ncrypt/pgp.c +++ b/ncrypt/pgp.c @@ -163,7 +163,10 @@ static char *pgp_fingerprint(struct PgpKeyInfo *k) return k->fingerprint; } -/* Grab the longest key identifier available: fingerprint or else +/** + * pgp_fpr_or_lkeyid - Get the fingerprint or long keyid + * + * Grab the longest key identifier available: fingerprint or else * the long keyid. * * The longest available should be used for internally identifying @@ -181,7 +184,9 @@ char *pgp_fpr_or_lkeyid(struct PgpKeyInfo *k) * Routines for handing PGP input. */ -/* Copy PGP output messages and look for signs of a good signature */ +/** + * pgp_copy_checksig - Copy PGP output and look for signs of a good signature + */ static int pgp_copy_checksig(FILE *fpin, FILE *fpout) { int rv = -1; @@ -219,9 +224,12 @@ static int pgp_copy_checksig(FILE *fpin, FILE *fpout) return rv; } -/* Checks PGP output messages to look for the $pgp_decryption_okay message. - * This protects against messages with multipart/encrypted headers - * but which aren't actually encrypted. See ticket #3770 +/** + * pgp_check_decryption_okay - Check PGP output to look for successful outcome + * + * Checks PGP output messages to look for the $pgp_decryption_okay message. + * This protects against messages with multipart/encrypted headers but which + * aren't actually encrypted. See ticket #3770 */ static int pgp_check_decryption_okay(FILE *fpin) { @@ -256,17 +264,15 @@ static int pgp_check_decryption_okay(FILE *fpin) return rv; } -/* - * Copy a clearsigned message, and strip the signature and PGP's - * dash-escaping. +/** + * pgp_copy_clearsigned - Copy a clearsigned message, stripping the signature * - * 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 around in the main handler. + * 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 + * around in the main handler. * - * (Note that we aren't worse than Outlook &c in this, and also - * note that we can successfully handle anything produced by any - * existing versions of mutt.) + * (Note that we aren't worse than Outlook &c in this, and also note that we + * can successfully handle anything produced by any existing versions of mutt.) */ static void pgp_copy_clearsigned(FILE *fpin, struct State *s, char *charset) { @@ -316,7 +322,9 @@ static void pgp_copy_clearsigned(FILE *fpin, struct State *s, char *charset) fgetconv_close(&fc); } -/* Support for the Application/PGP Content Type. */ +/** + * pgp_application_pgp_handler - Support for the Application/PGP Content Type + */ int pgp_application_pgp_handler(struct Body *m, struct State *s) { bool could_not_decrypt = false; @@ -751,7 +759,9 @@ int pgp_verify_one(struct Body *sigbdy, struct State *s, const char *tempfile) return badsig; } -/* Extract pgp public keys from messages or attachments */ +/** + * pgp_extract_keys_from_attachment - Extract pgp keys from messages/attachments + */ static void pgp_extract_keys_from_attachment(FILE *fp, struct Body *top) { struct State s; @@ -1006,7 +1016,9 @@ bail: return rv; } -/* +/** + * pgp_encrypted_handler - Handler of PGP encrypted data + * * This handler is passed the application/octet-stream directly. * The caller must propagate a->goodsig to its parent. */ @@ -1199,10 +1211,11 @@ struct Body *pgp_sign_message(struct Body *a) return a; } -/* This routine attempts to find the keyids of the recipients of a message. - * It returns NULL if any of the keys can not be found. - * If oppenc_mode is true, only keys that can be determined without - * prompting will be used. +/** + * pgp_find_keys - Find the keyids of the recipients of a message + * + * It returns NULL if any of the keys can not be found. If oppenc_mode is + * true, only keys that can be determined without prompting will be used. */ char *pgp_find_keys(struct Address *adrlist, int oppenc_mode) { @@ -1318,8 +1331,12 @@ char *pgp_find_keys(struct Address *adrlist, int oppenc_mode) return keylist; } -/* Warning: "a" is no longer freed in this routine, you need - * to free it later. This is necessary for $fcc_attach. */ +/** + * pgp_encrypt_message - Encrypt a message + * + * Warning: "a" is no longer freed in this routine, you need to free it later. + * This is necessary for $fcc_attach. + */ struct Body *pgp_encrypt_message(struct Body *a, char *keylist, int sign) { char buf[LONG_STRING]; diff --git a/ncrypt/pgpkey.c b/ncrypt/pgpkey.c index 13a0e5a21..73a498f80 100644 --- a/ncrypt/pgpkey.c +++ b/ncrypt/pgpkey.c @@ -708,7 +708,9 @@ struct PgpKeyInfo *pgp_ask_for_key(char *tag, char *whatfor, short abilities, en /* not reached */ } -/* generate a public key attachment */ +/** + * pgp_make_key_attachment - generate a public key attachment + */ struct Body *pgp_make_key_attachment(char *tempf) { struct Body *att = NULL; diff --git a/ncrypt/smime.c b/ncrypt/smime.c index 6a70ecd9b..c302d3756 100644 --- a/ncrypt/smime.c +++ b/ncrypt/smime.c @@ -152,7 +152,11 @@ int smime_valid_passphrase(void) * The OpenSSL interface */ -/* This is almost identical to ppgp's invoking interface. */ +/** + * _mutt_fmt_smime_command - Format an SMIME command + * + * This is almost identical to pgp's invoking interface. + */ static const char *_mutt_fmt_smime_command(char *dest, size_t destlen, size_t col, int cols, char op, const char *src, const char *prefix, const char *ifstring, @@ -592,7 +596,10 @@ static struct SmimeKey *smime_get_candidates(char *search, short public) return results; } -/* Returns the first matching key record, without prompting or checking of +/** + * smime_get_key_by_hash - Find a key by its hash + * + * Returns the first matching key record, without prompting or checking of * abilities or trust. */ static struct SmimeKey *smime_get_key_by_hash(char *hash, short public) @@ -749,10 +756,12 @@ static struct SmimeKey *smime_ask_for_key(char *prompt, short abilities, short p } } -/* - This sets the '*ToUse' variables for an upcoming decryption, where - the required key is different from SmimeDefaultKey. -*/ +/** + * _smime_getkeys - Get the keys for a mailbox + * + * This sets the '*ToUse' variables for an upcoming decryption, where the + * required key is different from SmimeDefaultKey. + */ static void _smime_getkeys(char *mailbox) { struct SmimeKey *key = NULL; @@ -841,8 +850,10 @@ void smime_getkeys(struct Envelope *env) } } -/* This routine attempts to find the keyids of the recipients of a message. - * It returns NULL if any of the keys can not be found. +/** + * smime_find_keys - Find the keys of the recipients of a message + * @return NULL if any of the keys can not be found + * * If oppenc_mode is true, only keys that can be determined without * prompting will be used. */ @@ -1141,7 +1152,9 @@ static char *smime_extract_signer_certificate(char *infile) return safe_strdup(certfile); } -/* Add a certificate and update index file (externally). */ +/** + * smime_invoke_import - Add a certificate and update index file (externally) + */ void smime_invoke_import(char *infile, char *mailbox) { char tmpfname[_POSIX_PATH_MAX], *certfile = NULL, buf[STRING]; @@ -1409,7 +1422,10 @@ struct Body *smime_build_smime_entity(struct Body *a, char *certlist) return t; } -/* The openssl -md doesn't want hyphens: +/** + * openssl_md_to_smime_micalg - Change the algorithm names + * + * 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 @@ -1695,10 +1711,11 @@ int smime_verify_one(struct Body *sigbdy, struct State *s, const char *tempfile) return badsig; } -/* - This handles application/pkcs7-mime which can either be a signed - or an encrypted message. -*/ +/** + * smime_handle_entity - Handle type application/pkcs7-mime + * + * This can either be a signed or an encrypted message. + */ static struct Body *smime_handle_entity(struct Body *m, struct State *s, FILE *outFile) { int len = 0; diff --git a/newsrc.c b/newsrc.c index 331043de9..02efba35c 100644 --- a/newsrc.c +++ b/newsrc.c @@ -55,7 +55,9 @@ struct BodyCache; -/* Find NntpData for given newsgroup or add it */ +/** + * nntp_data_find - Find NntpData for given newsgroup or add it + */ static struct NntpData *nntp_data_find(struct NntpServer *nserv, const char *group) { struct NntpData *nntp_data = hash_find(nserv->groups_hash, group); @@ -82,7 +84,9 @@ static struct NntpData *nntp_data_find(struct NntpServer *nserv, const char *gro return nntp_data; } -/* Remove all temporarily cache files */ +/** + * nntp_acache_free - Remove all temporarily cache files + */ void nntp_acache_free(struct NntpData *nntp_data) { for (int i = 0; i < NNTP_ACACHE_LEN; i++) @@ -95,7 +99,9 @@ void nntp_acache_free(struct NntpData *nntp_data) } } -/* Free NntpData, used to destroy hash elements */ +/** + * nntp_data_free - Free NntpData, used to destroy hash elements + */ void nntp_data_free(void *data) { struct NntpData *nntp_data = data; @@ -109,7 +115,9 @@ void nntp_data_free(void *data) FREE(&data); } -/* Unlock and close .newsrc file */ +/** + * nntp_newsrc_close - Unlock and close .newsrc file + */ void nntp_newsrc_close(struct NntpServer *nserv) { if (!nserv->newsrc_fp) @@ -120,7 +128,9 @@ void nntp_newsrc_close(struct NntpServer *nserv) safe_fclose(&nserv->newsrc_fp); } -/* calculate number of unread articles using .newsrc data */ +/** + * nntp_group_unread_stat - Count number of unread articles using .newsrc data + */ void nntp_group_unread_stat(struct NntpData *nntp_data) { anum_t first, last; @@ -143,10 +153,14 @@ void nntp_group_unread_stat(struct NntpData *nntp_data) } } -/* Parse .newsrc file: - * 0 - not changed - * 1 - parsed - * -1 - error */ +/** + * nntp_newsrc_parse - Parse .newsrc file + * @param nserv NNTP server + * @return + * * 0 Not changed + * * 1 Parsed + * * -1 Error + */ int nntp_newsrc_parse(struct NntpServer *nserv) { char *line = NULL; @@ -279,7 +293,9 @@ int nntp_newsrc_parse(struct NntpServer *nserv) return 1; } -/* Generate array of .newsrc entries */ +/** + * nntp_newsrc_gen_entries - Generate array of .newsrc entries + */ void nntp_newsrc_gen_entries(struct Context *ctx) { struct NntpData *nntp_data = ctx->data; @@ -361,7 +377,9 @@ void nntp_newsrc_gen_entries(struct Context *ctx) } } -/* Update file with new contents */ +/** + * update_file - Update file with new contents + */ static int update_file(char *filename, char *buf) { FILE *fp = NULL; @@ -408,7 +426,9 @@ static int update_file(char *filename, char *buf) return rc; } -/* Update .newsrc file */ +/** + * nntp_newsrc_update - Update .newsrc file + */ int nntp_newsrc_update(struct NntpServer *nserv) { char *buf = NULL; @@ -484,7 +504,9 @@ int nntp_newsrc_update(struct NntpServer *nserv) return rc; } -/* Make fully qualified cache file name */ +/** + * cache_expand - Make fully qualified cache file name + */ static void cache_expand(char *dst, size_t dstlen, struct Account *acct, char *src) { char *c = NULL; @@ -511,7 +533,9 @@ static void cache_expand(char *dst, size_t dstlen, struct Account *acct, char *s mutt_expand_path(dst, dstlen); } -/* Make fully qualified url from newsgroup name */ +/** + * nntp_expand_path - Make fully qualified url from newsgroup name + */ void nntp_expand_path(char *line, size_t len, struct Account *acct) { struct CissUrl url; @@ -522,7 +546,9 @@ void nntp_expand_path(char *line, size_t len, struct Account *acct) FREE(&url.path); } -/* Parse newsgroup */ +/** + * nntp_add_group - Parse newsgroup + */ int nntp_add_group(char *line, void *data) { struct NntpServer *nserv = data; @@ -553,7 +579,9 @@ int nntp_add_group(char *line, void *data) return 0; } -/* Load list of all newsgroups from cache */ +/** + * active_get_cache - Load list of all newsgroups from cache + */ static int active_get_cache(struct NntpServer *nserv) { char buf[HUGE_STRING]; @@ -583,7 +611,9 @@ static int active_get_cache(struct NntpServer *nserv) return 0; } -/* Save list of all newsgroups to cache */ +/** + * nntp_active_save_cache - Save list of all newsgroups to cache + */ int nntp_active_save_cache(struct NntpServer *nserv) { char file[_POSIX_PATH_MAX]; @@ -626,13 +656,19 @@ int nntp_active_save_cache(struct NntpServer *nserv) } #ifdef USE_HCACHE -/* Used by mutt_hcache_open() to compose hcache file name */ +/** + * nntp_hcache_namer - Compose hcache file names + * + * Used by mutt_hcache_open() to compose hcache file name + */ static int nntp_hcache_namer(const char *path, char *dest, size_t destlen) { return snprintf(dest, destlen, "%s.hcache", path); } -/* Open newsgroup hcache */ +/** + * nntp_hcache_open - Open newsgroup hcache + */ header_cache_t *nntp_hcache_open(struct NntpData *nntp_data) { struct CissUrl url; @@ -649,7 +685,9 @@ header_cache_t *nntp_hcache_open(struct NntpData *nntp_data) return mutt_hcache_open(NewsCacheDir, file, nntp_hcache_namer); } -/* Remove stale cached headers */ +/** + * nntp_hcache_update - Remove stale cached headers + */ void nntp_hcache_update(struct NntpData *nntp_data, header_cache_t *hc) { char buf[16]; @@ -694,7 +732,9 @@ void nntp_hcache_update(struct NntpData *nntp_data, header_cache_t *hc) } #endif -/* Remove bcache file */ +/** + * nntp_bcache_delete - Remove bcache file + */ static int nntp_bcache_delete(const char *id, struct BodyCache *bcache, void *data) { struct NntpData *nntp_data = data; @@ -711,13 +751,17 @@ static int nntp_bcache_delete(const char *id, struct BodyCache *bcache, void *da return 0; } -/* Remove stale cached messages */ +/** + * nntp_bcache_update - Remove stale cached messages + */ void nntp_bcache_update(struct NntpData *nntp_data) { mutt_bcache_list(nntp_data->bcache, nntp_bcache_delete, nntp_data); } -/* Remove hcache and bcache of newsgroup */ +/** + * nntp_delete_group_cache - Remove hcache and bcache of newsgroup + */ void nntp_delete_group_cache(struct NntpData *nntp_data) { if (!nntp_data || !nntp_data->nserv || !nntp_data->nserv->cacheable) @@ -743,7 +787,11 @@ void nntp_delete_group_cache(struct NntpData *nntp_data) } } -/* Remove hcache and bcache of all unexistent and unsubscribed newsgroups */ +/** + * nntp_clear_cache - Clear the NNTP cache + * + * Remove hcache and bcache of all unexistent and unsubscribed newsgroups + */ void nntp_clear_cache(struct NntpServer *nserv) { char file[_POSIX_PATH_MAX]; @@ -807,15 +855,18 @@ void nntp_clear_cache(struct NntpServer *nserv) } closedir(dp); } - return; } -/* %a = account url +/** + * nntp_format_str - Format a string, like printf() + * + * %a = account url * %p = port * %P = port if specified * %s = news server name * %S = url schema - * %u = username */ + * %u = username + */ const char *nntp_format_str(char *dest, size_t destlen, size_t col, int cols, char op, const char *src, const char *fmt, const char *ifstring, const char *elsestring, @@ -872,10 +923,14 @@ const char *nntp_format_str(char *dest, size_t destlen, size_t col, int cols, return src; } -/* Automatically loads a newsrc into memory, if necessary. - * Checks the size/mtime of a newsrc file, if it doesn't match, load - * again. Hmm, if a system has broken mtimes, this might mean the file - * is reloaded every time, which we'd have to fix. */ +/** + * nntp_select_server - Open a connection to an NNTP server + * + * Automatically loads a newsrc into memory, if necessary. Checks the + * size/mtime of a newsrc file, if it doesn't match, load again. Hmm, if a + * system has broken mtimes, this might mean the file is reloaded every time, + * which we'd have to fix. + */ struct NntpServer *nntp_select_server(char *server, int leave_lock) { char file[_POSIX_PATH_MAX]; @@ -1070,10 +1125,14 @@ struct NntpServer *nntp_select_server(char *server, int leave_lock) return nserv; } -/* Full status flags are not supported by nntp, but we can fake some of them: +/** + * nntp_article_status - Get status of articles from .newsrc + * + * Full status flags are not supported by nntp, but we can fake some of them: * Read = a read message number is in the .newsrc * New = not read and not cached - * Old = not read but cached */ + * Old = not read but cached + */ void nntp_article_status(struct Context *ctx, struct Header *hdr, char *group, anum_t anum) { struct NntpData *nntp_data = ctx->data; @@ -1105,7 +1164,9 @@ void nntp_article_status(struct Context *ctx, struct Header *hdr, char *group, a hdr->old = true; } -/* Subscribe newsgroup */ +/** + * mutt_newsgroup_subscribe - Subscribe newsgroup + */ struct NntpData *mutt_newsgroup_subscribe(struct NntpServer *nserv, char *group) { struct NntpData *nntp_data = NULL; @@ -1125,7 +1186,9 @@ struct NntpData *mutt_newsgroup_subscribe(struct NntpServer *nserv, char *group) return nntp_data; } -/* Unsubscribe newsgroup */ +/** + * mutt_newsgroup_unsubscribe - Unsubscribe newsgroup + */ struct NntpData *mutt_newsgroup_unsubscribe(struct NntpServer *nserv, char *group) { struct NntpData *nntp_data = NULL; @@ -1146,7 +1209,9 @@ struct NntpData *mutt_newsgroup_unsubscribe(struct NntpServer *nserv, char *grou return nntp_data; } -/* Catchup newsgroup */ +/** + * mutt_newsgroup_catchup - Catchup newsgroup + */ struct NntpData *mutt_newsgroup_catchup(struct NntpServer *nserv, char *group) { struct NntpData *nntp_data = NULL; @@ -1174,7 +1239,9 @@ struct NntpData *mutt_newsgroup_catchup(struct NntpServer *nserv, char *group) return nntp_data; } -/* Uncatchup newsgroup */ +/** + * mutt_newsgroup_uncatchup - Uncatchup newsgroup + */ struct NntpData *mutt_newsgroup_uncatchup(struct NntpServer *nserv, char *group) { struct NntpData *nntp_data = NULL; @@ -1208,7 +1275,9 @@ struct NntpData *mutt_newsgroup_uncatchup(struct NntpServer *nserv, char *group) return nntp_data; } -/* Get first newsgroup with new messages */ +/** + * nntp_buffy - Get first newsgroup with new messages + */ void nntp_buffy(char *buf, size_t len) { for (unsigned int i = 0; i < CurrentNewsSrv->groups_num; i++) diff --git a/nntp.c b/nntp.c index 4d6a021a1..dfecfd1e0 100644 --- a/nntp.c +++ b/nntp.c @@ -67,10 +67,13 @@ static int nntp_connect_error(struct NntpServer *nserv) return -1; } -/* Get capabilities: - * -1 - error, connection is closed - * 0 - mode is reader, capabilities setted up - * 1 - need to switch to reader mode */ +/** + * nntp_capabilities - Get capabilities + * @return + * * -1 Error, connection is closed + * * 0 Mode is reader, capabilities setted up + * * 1 Need to switch to reader mode + */ static int nntp_capabilities(struct NntpServer *nserv) { struct Connection *conn = nserv->conn; @@ -175,7 +178,9 @@ char *OverviewFmt = "Subject:\0" "Lines:\0" "\0"; -/* Detect supported commands */ +/** + * nntp_attempt_features - Detect supported commands + */ static int nntp_attempt_features(struct NntpServer *nserv) { struct Connection *conn = nserv->conn; @@ -299,7 +304,9 @@ static int nntp_attempt_features(struct NntpServer *nserv) return 0; } -/* Get login, password and authenticate */ +/** + * nntp_auth - Get login, password and authenticate + */ static int nntp_auth(struct NntpServer *nserv) { struct Connection *conn = nserv->conn; @@ -588,7 +595,9 @@ static int nntp_auth(struct NntpServer *nserv) return -1; } -/* Connect to server, authenticate and get capabilities */ +/** + * nntp_open_connection - Connect to server, authenticate and get capabilities + */ int nntp_open_connection(struct NntpServer *nserv) { struct Connection *conn = nserv->conn; @@ -741,7 +750,9 @@ int nntp_open_connection(struct NntpServer *nserv) return 0; } -/* Send data from buffer and receive answer to same buffer */ +/** + * nntp_query - Send data from buffer and receive answer to same buffer + */ static int nntp_query(struct NntpData *nntp_data, char *line, size_t linelen) { struct NntpServer *nserv = nntp_data->nserv; @@ -801,12 +812,17 @@ static int nntp_query(struct NntpData *nntp_data, char *line, size_t linelen) return 0; } -/* This function calls funct(*line, *data) for each received line, +/** + * nntp_fetch_lines - Read lines, calling a callback function for each + * @return + * * 0 Success + * * 1 Bad response (answer in query buffer) + * * -1 Connection lost + * * -2 Error in funct(*line, *data) + * + * This function calls funct(*line, *data) for each received line, * funct(NULL, *data) if rewind(*data) needs, exits when fail or done: - * 0 - success - * 1 - bad response (answer in query buffer) - * -1 - connection lost - * -2 - error in funct(*line, *data) */ + */ static int nntp_fetch_lines(struct NntpData *nntp_data, char *query, size_t qlen, char *msg, int (*funct)(char *, void *), void *data) { @@ -881,7 +897,9 @@ static int nntp_fetch_lines(struct NntpData *nntp_data, char *query, size_t qlen return rc; } -/* Parse newsgroup description */ +/** + * fetch_description - Parse newsgroup description + */ static int fetch_description(char *line, void *data) { struct NntpServer *nserv = data; @@ -948,7 +966,11 @@ static int get_description(struct NntpData *nntp_data, char *wildmat, char *msg) return rc; } -/* Update read flag and set article number if empty */ +/** + * nntp_parse_xref - Parse cross-reference + * + * Update read flag and set article number if empty + */ static void nntp_parse_xref(struct Context *ctx, struct Header *hdr) { struct NntpData *nntp_data = ctx->data; @@ -984,7 +1006,9 @@ static void nntp_parse_xref(struct Context *ctx, struct Header *hdr) FREE(&buf); } -/* Write line to temporarily file */ +/** + * fetch_tempfile - Write line to temporarily file + */ static int fetch_tempfile(char *line, void *data) { FILE *fp = data; @@ -1012,7 +1036,9 @@ struct FetchCtx #endif }; -/* Parse article number */ +/** + * fetch_numbers - Parse article number + */ static int fetch_numbers(char *line, void *data) { struct FetchCtx *fc = data; @@ -1028,7 +1054,9 @@ static int fetch_numbers(char *line, void *data) return 0; } -/* Parse overview line */ +/** + * parse_overview_line - Parse overview line + */ static int parse_overview_line(char *line, void *data) { struct FetchCtx *fc = data; @@ -1179,7 +1207,9 @@ static int parse_overview_line(char *line, void *data) return 0; } -/* Fetch headers */ +/** + * nntp_fetch_headers - Fetch headers + */ static int nntp_fetch_headers(struct Context *ctx, void *hc, anum_t first, anum_t last, int restore) { @@ -1411,7 +1441,9 @@ static int nntp_fetch_headers(struct Context *ctx, void *hc, anum_t first, return 0; } -/* Open newsgroup */ +/** + * nntp_open_mailbox - Open newsgroup + */ static int nntp_open_mailbox(struct Context *ctx) { struct NntpServer *nserv = NULL; @@ -1546,7 +1578,9 @@ static int nntp_open_mailbox(struct Context *ctx) return 0; } -/* Fetch message */ +/** + * nntp_open_message - Fetch message + */ static int nntp_open_message(struct Context *ctx, struct Message *msg, int msgno) { struct NntpData *nntp_data = ctx->data; @@ -1668,13 +1702,17 @@ static int nntp_open_message(struct Context *ctx, struct Message *msg, int msgno return 0; } -/* Close message */ +/** + * nntp_close_message - Close message + */ static int nntp_close_message(struct Context *ctx, struct Message *msg) { return safe_fclose(&msg->fp); } -/* Post article */ +/** + * nntp_post - Post article + */ int nntp_post(const char *msg) { struct NntpData *nntp_data, nntp_tmp; @@ -1746,10 +1784,13 @@ int nntp_post(const char *msg) return 0; } -/* Check newsgroup for new articles: - * 1 - new articles found - * 0 - no change - * -1 - lost connection */ +/** + * nntp_group_poll - Check newsgroup for new articles + * @return + * * 1 New articles found + * * 0 No change + * * -1 Lost connection + */ static int nntp_group_poll(struct NntpData *nntp_data, int update_stat) { char buf[LONG_STRING] = ""; @@ -1788,11 +1829,16 @@ static int nntp_group_poll(struct NntpData *nntp_data, int update_stat) return 1; } -/* Check current newsgroup for new articles, leave newsrc locked: - * MUTT_REOPENED - articles have been renumbered or removed from server - * MUTT_NEW_MAIL - new articles found - * 0 - no change - * -1 - lost connection */ +/** + * check_mailbox - Check current newsgroup for new articles + * @return + * * #MUTT_REOPENED Articles have been renumbered or removed from server + * * #MUTT_NEW_MAIL New articles found + * * 0 No change + * * -1 Lost connection + * + * Leave newsrc locked + */ static int check_mailbox(struct Context *ctx) { struct NntpData *nntp_data = ctx->data; @@ -2002,11 +2048,14 @@ static int check_mailbox(struct Context *ctx) return ret; } -/* Check current newsgroup for new articles: - * MUTT_REOPENED - articles have been renumbered or removed from server - * MUTT_NEW_MAIL - new articles found - * 0 - no change - * -1 - lost connection */ +/** + * nntp_check_mailbox - Check current newsgroup for new articles + * @return + * * #MUTT_REOPENED Articles have been renumbered or removed from server + * * #MUTT_NEW_MAIL New articles found + * * 0 No change + * * -1 Lost connection + */ static int nntp_check_mailbox(struct Context *ctx, int *index_hint) { int ret = check_mailbox(ctx); @@ -2019,7 +2068,9 @@ static int nntp_check_mailbox(struct Context *ctx, int *index_hint) return ret; } -/* Save changes to .newsrc and cache */ +/** + * nntp_sync_mailbox - Save changes to .newsrc and cache + */ static int nntp_sync_mailbox(struct Context *ctx, int *index_hint) { struct NntpData *nntp_data = ctx->data; @@ -2077,7 +2128,9 @@ static int nntp_sync_mailbox(struct Context *ctx, int *index_hint) return 0; } -/* Free up memory associated with the newsgroup context */ +/** + * nntp_close_mailbox - Free up memory associated with the newsgroup context + */ static int nntp_close_mailbox(struct Context *ctx) { struct NntpData *nntp_data = ctx->data, *nntp_tmp = NULL; @@ -2097,7 +2150,9 @@ static int nntp_close_mailbox(struct Context *ctx) return 0; } -/* Get date and time from server */ +/** + * nntp_date - Get date and time from server + */ static int nntp_date(struct NntpServer *nserv, time_t *now) { if (nserv->hasDATE) @@ -2130,7 +2185,9 @@ static int nntp_date(struct NntpServer *nserv, time_t *now) return 0; } -/* Fetch list of all newsgroups from server */ +/** + * nntp_active_fetch - Fetch list of all newsgroups from server + */ int nntp_active_fetch(struct NntpServer *nserv, unsigned int new) { struct NntpData nntp_data; @@ -2191,10 +2248,13 @@ int nntp_active_fetch(struct NntpServer *nserv, unsigned int new) return 0; } -/* Check for new groups and new articles in subscribed groups: - * 1 - new groups found - * 0 - no new groups - * -1 - error */ +/** + * nntp_check_new_groups - Check for new groups/articles in subscribed groups + * @return + * * 1 New groups found + * * 0 No new groups + * * -1 Error + */ int nntp_check_new_groups(struct NntpServer *nserv) { struct NntpData nntp_data; @@ -2300,10 +2360,13 @@ int nntp_check_new_groups(struct NntpServer *nserv) return rc; } -/* Fetch article by Message-ID: - * 0 - success - * 1 - no such article - * -1 - error */ +/** + * nntp_check_msgid - Fetch article by Message-ID + * @return + * * 0 Success + * * 1 No such article + * * -1 Error + */ int nntp_check_msgid(struct Context *ctx, const char *msgid) { struct NntpData *nntp_data = ctx->data; @@ -2381,7 +2444,9 @@ struct ChildCtx anum_t *child; }; -/* Parse XPAT line */ +/** + * fetch_children - Parse XPAT line + */ static int fetch_children(char *line, void *data) { struct ChildCtx *cc = data; @@ -2401,7 +2466,9 @@ static int fetch_children(char *line, void *data) return 0; } -/* Fetch children of article with the Message-ID */ +/** + * nntp_check_children - Fetch children of article with the Message-ID + */ int nntp_check_children(struct Context *ctx, const char *msgid) { struct NntpData *nntp_data = ctx->data; diff --git a/pager.c b/pager.c index 2ac24f2a5..334602c6e 100644 --- a/pager.c +++ b/pager.c @@ -1112,7 +1112,11 @@ static int grok_ansi(unsigned char *buf, int pos, struct AnsiAttr *a) return pos; } -/* trim tail of buf so that it contains complete multibyte characters */ +/** + * trim_incomplete_mbyte - Remove an incomplete character + * + * trim tail of buf so that it contains complete multibyte characters + */ static int trim_incomplete_mbyte(unsigned char *buf, size_t len) { mbstate_t mbstate; @@ -1999,11 +2003,15 @@ static void pager_menu_redraw(struct Menu *pager_menu) pager_menu->redraw = 0; } -/* 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 be distinguished by whether or not ``hdr'' is NULL. The ``hdr'' arg - is there so that we can do operations on the current message without the - need to pop back out to the main-menu. */ +/** + * mutt_pager - Display a file, or help, in a window + * + * 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 + * be distinguished by whether or not ``hdr'' is NULL. The ``hdr'' arg is + * there so that we can do operations on the current message without the need + * to pop back out to the main-menu. + */ int mutt_pager(const char *banner, const char *fname, int flags, struct Pager *extra) { static char searchbuf[STRING] = ""; diff --git a/parse.c b/parse.c index 9bd1023c6..f2b9f454f 100644 --- a/parse.c +++ b/parse.c @@ -53,7 +53,10 @@ struct Address; struct Context; -/* Reads an arbitrarily long header field, and looks ahead for continuation +/** + * mutt_read_rfc822_line - Read a header line from a file + * + * Reads an arbitrarily long header field, and looks ahead for continuation * lines. ``line'' must point to a dynamically allocated string; it is * increased if more space is required to fit the whole line. */ @@ -418,11 +421,10 @@ static void parse_content_disposition(const char *s, struct Body *ct) } } -/* args: - * fp stream to read from - * - * digest 1 if reading subparts of a multipart/digest, 0 - * otherwise +/** + * mutt_read_mime_header - Parse a MIME header + * @param fp stream to read from + * @param digest 1 if reading subparts of a multipart/digest, 0 otherwise */ struct Body *mutt_read_mime_header(FILE *fp, int digest) { @@ -543,13 +545,10 @@ void mutt_parse_part(FILE *fp, struct Body *b) } } -/* parse a Message/RFC822 body - * - * args: - * fp stream to read from - * - * parent structure which contains info about the message/rfc822 - * body part +/** + * mutt_parse_message_rfc822 - parse a Message/RFC822 body + * @param fp stream to read from + * @param parent info about the message/rfc822 body part * * NOTE: this assumes that `parent->length' has been set! */ @@ -575,17 +574,13 @@ struct Body *mutt_parse_message_rfc822(FILE *fp, struct Body *parent) return msg; } -/* parse a multipart structure - * - * args: - * fp stream to read from - * - * boundary body separator - * - * end_off length of the multipart body (used when the final - * boundary is missing to avoid reading too far) - * - * digest 1 if reading a multipart/digest, 0 otherwise +/** + * mutt_parse_multipart - parse a multipart structure + * @param fp stream to read from + * @param boundary body separator + * @param end_off length of the multipart body (used when the final + * boundary is missing to avoid reading too far) + * @param digest 1 if reading a multipart/digest, 0 otherwise */ struct Body *mutt_parse_multipart(FILE *fp, const char *boundary, LOFF_T end_off, int digest) { @@ -759,7 +754,8 @@ static const struct Tz { "wst", 8, 0, false }, /* Western Australia */ }; -/* parses a date string in RFC822 format: +/** + * mutt_parse_date - parses a date string in RFC822 format * * Date: [ weekday , ] day-of-month month year hour:minute:second timezone * @@ -908,7 +904,10 @@ time_t mutt_parse_date(const char *s, struct Header *h) return (mutt_mktime(&tm, 0) + tz_offset); } -/* extract the first substring that looks like a message-id. +/** + * mutt_extract_message_id - Find a message-id + * + * extract the first substring that looks like a message-id. * call back with NULL for more (like strtok). */ char *mutt_extract_message_id(const char *s, const char **saveptr) @@ -1564,7 +1563,9 @@ struct Address *mutt_parse_adrlist(struct Address *p, const char *s) return p; } -/* Compares mime types to the ok and except lists */ +/** + * count_body_parts_check - Compares mime types to the ok and except lists + */ static bool count_body_parts_check(struct List **checklist, struct Body *b, bool dflt) { struct List *type = NULL; diff --git a/pattern.c b/pattern.c index 6e9045799..ee0dccef8 100644 --- a/pattern.c +++ b/pattern.c @@ -127,10 +127,14 @@ static bool eat_regexp(struct Pattern *pat, struct Buffer *s, struct Buffer *err return true; } -/* Ny years - Nm months - Nw weeks - Nd days */ +/** + * get_offset - Calculate a symbolic offset + * + * Ny years + * Nm months + * Nw weeks + * Nd days + */ static const char *get_offset(struct tm *tm, const char *s, int sign) { char *ps = NULL; @@ -883,7 +887,11 @@ static char LastSearchExpn[LONG_STRING] = { 0 }; /* expanded version of LastSearch */ -/* if no uppercase letters are given, do a case-insensitive search */ +/** + * mutt_which_case - Smart-case searching + * + * if no uppercase letters are given, do a case-insensitive search + */ int mutt_which_case(const char *s) { wchar_t w; @@ -1400,8 +1408,8 @@ static bool match_reference(struct Pattern *pat, struct List *refs) return false; } -/* - * Matches subscribed mailing lists +/** + * mutt_is_list_recipient - Matches subscribed mailing lists */ int mutt_is_list_recipient(int alladdr, struct Address *a1, struct Address *a2) { @@ -1414,8 +1422,9 @@ int mutt_is_list_recipient(int alladdr, struct Address *a1, struct Address *a2) return alladdr; } -/* - * Matches known mailing lists +/** + * mutt_is_list_cc - Matches known mailing lists + * * The function name may seem a little bit misleading: It checks all * recipients in To and Cc for known mailing lists, subscribed or not. */ @@ -1491,15 +1500,22 @@ static int match_threadchildren(struct Pattern *pat, enum PatternExecFlag flags, } -/* Sets a value in the PatternCache cache entry. - * Normalizes the "true" value to 2. */ +/** + * set_pattern_cache_value - Sets a value in the PatternCache cache entry + * + * Normalizes the "true" value to 2. + */ static void set_pattern_cache_value(int *cache_entry, int value) { *cache_entry = value ? 2 : 1; } -/* Returns 1 if the cache value is set and has a true value. - * 0 otherwise (even if unset!) */ +/** + * get_pattern_cache_value - Get pattern cache value + * @return + * * 1 if the cache value is set and has a true value. + * * 0 otherwise (even if unset!) + */ static int get_pattern_cache_value(int cache_entry) { return cache_entry == 2; @@ -1511,10 +1527,13 @@ static int is_pattern_cache_set(int cache_entry) } -/* +/** + * mutt_pattern_exec - Match a pattern against an email header + * * flags: MUTT_MATCH_FULL_ADDRESS - match both personal and machine address * cache: For repeated matches against the same Header, passing in non-NULL will - * store some of the cacheable pattern matches in this structure. */ + * store some of the cacheable pattern matches in this structure. + */ int mutt_pattern_exec(struct Pattern *pat, enum PatternExecFlag flags, struct Context *ctx, struct Header *h, struct PatternCache *cache) { @@ -1742,7 +1761,9 @@ static void quote_simple(char *tmp, size_t len, const char *p) tmp[i] = 0; } -/* convert a simple search into a real request */ +/** + * mutt_check_simple - convert a simple search into a real request + */ void mutt_check_simple(char *s, size_t len, const char *simple) { char tmp[LONG_STRING]; diff --git a/pgppubring.c b/pgppubring.c index afc797fe2..bf0c42d0b 100644 --- a/pgppubring.c +++ b/pgppubring.c @@ -195,7 +195,9 @@ static bool pgpring_string_matches_hint(const char *s, const char *hints[], int return false; } -/* The actual key ring parser */ +/** + * pgp_make_pgp2_fingerprint - The actual key ring parser + */ static void pgp_make_pgp2_fingerprint(unsigned char *buff, unsigned char *digest) { struct Md5Ctx ctx; diff --git a/pop.c b/pop.c index a5c6f58c9..aca2fc0ac 100644 --- a/pop.c +++ b/pop.c @@ -56,7 +56,9 @@ #define HC_FEXT "hcache" /* extension for hcache as POP lacks paths */ #endif -/* write line to file */ +/** + * fetch_message - write line to file + */ static int fetch_message(char *line, void *file) { FILE *f = (FILE *) file; @@ -154,7 +156,9 @@ static int pop_read_header(struct PopData *pop_data, struct Header *h) return ret; } -/* parse UIDL */ +/** + * fetch_uidl - parse UIDL + */ static int fetch_uidl(char *line, void *data) { int i, index; @@ -413,7 +417,9 @@ static int pop_fetch_headers(struct Context *ctx) return (new_count - old_count); } -/* open POP mailbox - fetch only headers */ +/** + * pop_open_mailbox - open POP mailbox, fetch only headers + */ static int pop_open_mailbox(struct Context *ctx) { int ret; @@ -484,7 +490,9 @@ static int pop_open_mailbox(struct Context *ctx) } } -/* delete all cached messages */ +/** + * pop_clear_cache - delete all cached messages + */ static void pop_clear_cache(struct PopData *pop_data) { if (!pop_data->clear_cache) @@ -502,7 +510,9 @@ static void pop_clear_cache(struct PopData *pop_data) } } -/* close POP mailbox */ +/** + * pop_close_mailbox - close POP mailbox + */ static int pop_close_mailbox(struct Context *ctx) { struct PopData *pop_data = (struct PopData *) ctx->data; @@ -528,7 +538,9 @@ static int pop_close_mailbox(struct Context *ctx) return 0; } -/* fetch message from POP server */ +/** + * pop_fetch_message - fetch message from POP server + */ static int pop_fetch_message(struct Context *ctx, struct Message *msg, int msgno) { int ret; @@ -681,7 +693,9 @@ static int pop_close_message(struct Context *ctx, struct Message *msg) return safe_fclose(&msg->fp); } -/* update POP mailbox - delete messages from server */ +/** + * pop_sync_mailbox - update POP mailbox, delete messages from server + */ static int pop_sync_mailbox(struct Context *ctx, int *index_hint) { int i, j, ret = 0; @@ -759,7 +773,9 @@ static int pop_sync_mailbox(struct Context *ctx, int *index_hint) } } -/* Check for new messages and fetch headers */ +/** + * pop_check_mailbox - Check for new messages and fetch headers + */ static int pop_check_mailbox(struct Context *ctx, int *index_hint) { int ret; @@ -791,7 +807,9 @@ static int pop_check_mailbox(struct Context *ctx, int *index_hint) return 0; } -/* Fetch messages and save them in $spoolfile */ +/** + * pop_fetch_mail - Fetch messages and save them in $spoolfile + */ void pop_fetch_mail(void) { char buffer[LONG_STRING]; diff --git a/pop_auth.c b/pop_auth.c index dadc0c0fe..84eef8acf 100644 --- a/pop_auth.c +++ b/pop_auth.c @@ -41,7 +41,9 @@ #endif #ifdef USE_SASL -/* SASL authenticator */ +/** + * pop_auth_sasl - POP SASL authenticator + */ static enum PopAuthRes pop_auth_sasl(struct PopData *pop_data, const char *method) { sasl_conn_t *saslconn = NULL; @@ -191,7 +193,9 @@ bail: } #endif -/* Get the server timestamp for APOP authentication */ +/** + * pop_apop_timestamp - Get the server timestamp for APOP authentication + */ void pop_apop_timestamp(struct PopData *pop_data, char *buf) { char *p1 = NULL, *p2 = NULL; @@ -205,7 +209,9 @@ void pop_apop_timestamp(struct PopData *pop_data, char *buf) } } -/* APOP authenticator */ +/** + * pop_auth_apop - APOP authenticator + */ static enum PopAuthRes pop_auth_apop(struct PopData *pop_data, const char *method) { struct Md5Ctx ctx; @@ -252,7 +258,9 @@ static enum PopAuthRes pop_auth_apop(struct PopData *pop_data, const char *metho return POP_A_FAILURE; } -/* USER authenticator */ +/** + * pop_auth_user - USER authenticator + */ static enum PopAuthRes pop_auth_user(struct PopData *pop_data, const char *method) { char buf[LONG_STRING]; @@ -319,12 +327,13 @@ static const struct PopAuth pop_authenticators[] = { { NULL, NULL }, }; -/* - * Authentication - * 0 - successful, - * -1 - connection lost, - * -2 - login failed, - * -3 - authentication canceled. +/** + * pop_authenticate - Authenticate with a POP server + * @return + * * 0 Successful + * * -1 Connection lost + * * -2 Login failed + * * -3 Authentication cancelled */ int pop_authenticate(struct PopData *pop_data) { diff --git a/pop_lib.c b/pop_lib.c index 57790d452..fb3c92ef8 100644 --- a/pop_lib.c +++ b/pop_lib.c @@ -502,15 +502,14 @@ int pop_query_d(struct PopData *pop_data, char *buf, size_t buflen, char *msg) /** * pop_fetch_data - Read Headers with callback function - * + * @return + * * 0 Successful + * * -1 Connection lost + * * -2 Invalid command or execution error + * * -3 Error in funct(*line, *data) * * This function calls funct(*line, *data) for each received line, * funct(NULL, *data) if rewind(*data) needs, exits when fail or done. - * Returned codes: - * 0 - successful, - * -1 - connection lost, - * -2 - invalid command or execution error, - * -3 - error in funct(*line, *data) */ int pop_fetch_data(struct PopData *pop_data, char *query, struct Progress *progressbar, int (*funct)(char *, void *), void *data) diff --git a/postpone.c b/postpone.c index cdf631a7a..13511a762 100644 --- a/postpone.c +++ b/postpone.c @@ -69,9 +69,12 @@ static short PostCount = 0; static struct Context *PostContext = NULL; static short UpdateNumPostponed = 0; -/* Return the number of postponed messages. - * if force is 0, use a cached value if it is costly to get a fresh - * count (IMAP) - else check. +/** + * mutt_num_postponed - Return the number of postponed messages + * @param force + * * 0 Use a cached value if costly to get a fresh count (IMAP) + * * 1 Force check + * @return Number of postponed messages */ int mutt_num_postponed(int force) { @@ -558,14 +561,16 @@ int mutt_parse_crypt_hdr(const char *p, int set_empty_signas, int crypt_app) } -/* args: - * fp If not NULL, file containing the template - * ctx If fp is NULL, the context containing the header with the template - * newhdr The template is read into this Header - * hdr The message to recall/resend - * resend Set if resending (as opposed to recalling a postponed msg). - * Resent messages enable header weeding, and also - * discard any existing Message-ID and Mail-Followup-To. +/** + * mutt_prepare_template - Prepare a message template + * @param fp If not NULL, file containing the template + * @param ctx If fp is NULL, the context containing the header with the template + * @param newhdr The template is read into this Header + * @param hdr The message to recall/resend + * @param resend Set if resending (as opposed to recalling a postponed msg). + * Resent messages enable header weeding, and also + * discard any existing Message-ID and Mail-Followup-To. + * @return 0 on success, -1 on error */ int mutt_prepare_template(FILE *fp, struct Context *ctx, struct Header *newhdr, struct Header *hdr, short resend) diff --git a/query.c b/query.c index 6a56d6469..b12904196 100644 --- a/query.c +++ b/query.c @@ -499,6 +499,7 @@ static void query_menu(char *buf, size_t buflen, struct Query *results, int retb mutt_menu_destroy(&menu); } } + int mutt_query_complete(char *buf, size_t buflen) { struct Query *results = NULL; diff --git a/recvattach.c b/recvattach.c index 0a57424e8..978b2882e 100644 --- a/recvattach.c +++ b/recvattach.c @@ -156,21 +156,26 @@ struct AttachPtr **mutt_gen_attach_list(struct Body *m, int parent_type, return idx; } -/* %c = character set: convert? - * %C = character set - * %D = deleted flag - * %d = description - * %e = MIME content-transfer-encoding - * %F = filename for content-disposition header - * %f = filename - * %I = content-disposition, either I (inline) or A (attachment) - * %t = tagged flag - * %T = tree chars - * %m = major MIME type - * %M = MIME subtype - * %n = attachment number - * %s = size - * %u = unlink +/** + * mutt_attach_fmt - Format string for attachment menu + * + * | Expando | Description + * |:--------|:-------------------------------------------------------- + * | \%c | character set: convert? + * | \%C | character set + * | \%D | deleted flag + * | \%d | description + * | \%e | MIME content-transfer-encoding + * | \%F | filename for content-disposition header + * | \%f | filename + * | \%I | content-disposition, either I (inline) or A (attachment) + * | \%t | tagged flag + * | \%T | tree chars + * | \%m | major MIME type + * | \%M | MIME subtype + * | \%n | attachment number + * | \%s | size + * | \%u | unlink */ const char *mutt_attach_fmt(char *dest, size_t destlen, size_t col, int cols, char op, const char *src, const char *prefix, diff --git a/recvcmd.c b/recvcmd.c index 094f09d90..8b690772e 100644 --- a/recvcmd.c +++ b/recvcmd.c @@ -41,8 +41,11 @@ #include "rfc822.h" #include "state.h" -/* some helper functions to verify that we are exclusively operating - * on message/rfc822 attachments +/** + * check_msg - Are we working with an RFC822 message + * + * some helper functions to verify that we are exclusively operating on + * message/rfc822 attachments */ static bool check_msg(struct Body *b, bool err) { @@ -74,7 +77,9 @@ static bool check_all_msg(struct AttachPtr **idx, short idxlen, struct Body *cur } -/* can we decode all tagged attachments? */ +/** + * check_can_decode - can we decode all tagged attachments? + */ static short check_can_decode(struct AttachPtr **idx, short idxlen, struct Body *cur) { if (cur) @@ -97,8 +102,8 @@ static short count_tagged(struct AttachPtr **idx, short idxlen) return count; } -/* count the number of tagged children below a multipart or message - * attachment. +/** + * count_tagged_children - tagged children below a multipart/message attachment */ static short count_tagged_children(struct AttachPtr **idx, short idxlen, short i) { @@ -114,10 +119,8 @@ static short count_tagged_children(struct AttachPtr **idx, short idxlen, short i /** - ** - ** The bounce function, from the attachment menu - ** - **/ + * mutt_attach_bounce - Bounce function, from the attachment menu + */ void mutt_attach_bounce(FILE *fp, struct Header *hdr, struct AttachPtr **idx, short idxlen, struct Body *cur) { @@ -237,11 +240,8 @@ void mutt_attach_bounce(FILE *fp, struct Header *hdr, struct AttachPtr **idx, /** - ** - ** resend-message, from the attachment menu - ** - ** - **/ + * mutt_attach_resend - resend-message, from the attachment menu + */ void mutt_attach_resend(FILE *fp, struct Header *hdr, struct AttachPtr **idx, short idxlen, struct Body *cur) { @@ -260,12 +260,12 @@ void mutt_attach_resend(FILE *fp, struct Header *hdr, struct AttachPtr **idx, /** - ** ** forward-message, from the attachment menu - ** **/ -/* try to find a common parent message for the tagged attachments. */ +/** + * find_common_parent - find a common parent message for the tagged attachments + */ static struct Header *find_common_parent(struct AttachPtr **idx, short idxlen, short nattach) { short i; @@ -288,12 +288,13 @@ static struct Header *find_common_parent(struct AttachPtr **idx, short idxlen, s return NULL; } -/* - * check whether attachment #i is a parent of the attachment - * pointed to by cur +/** + * is_parent - Check whether one attachment is the parent of another * - * Note: This and the calling procedure could be optimized quite a - * bit. For now, it's not worth the effort. + * check whether attachment i is a parent of the attachment pointed to by cur + * + * Note: This and the calling procedure could be optimized quite a bit. + * For now, it's not worth the effort. */ static bool is_parent(short i, struct AttachPtr **idx, short idxlen, struct Body *cur) { @@ -353,8 +354,11 @@ static void include_header(int quote, FILE *ifp, struct Header *hdr, FILE *ofp, mutt_copy_header(ifp, hdr, ofp, chflags, quote ? prefix : NULL); } -/* Attach all the body parts which can't be decoded. - * This code is shared by forwarding and replying. */ +/** + * copy_problematic_attachments - Attach the body parts which can't be decoded + * + * This code is shared by forwarding and replying. + */ static struct Body **copy_problematic_attachments(FILE *fp, struct Body **last, struct AttachPtr **idx, short idxlen, short force) @@ -371,8 +375,9 @@ static struct Body **copy_problematic_attachments(FILE *fp, struct Body **last, return last; } -/* - * forward one or several MIME bodies +/** + * attach_forward_bodies - forward one or several MIME bodies + * * (non-message types) */ static void attach_forward_bodies(FILE *fp, struct Header *hdr, @@ -534,15 +539,15 @@ bail: } -/* - * Forward one or several message-type attachments. This - * is different from the previous function - * since we want to mimic the index menu's behavior. +/** + * attach_forward_msgs - Forward one or several message-type attachments + * + * This is different from the previous function since we want to mimic the + * index menu's behavior. * - * Code reuse from ci_send_message is not possible here - - * ci_send_message relies on a context structure to find messages, - * while, on the attachment menu, messages are referenced through - * the attachment index. + * Code reuse from ci_send_message is not possible here - ci_send_message + * relies on a context structure to find messages, while, on the attachment + * menu, messages are referenced through the attachment index. */ static void attach_forward_msgs(FILE *fp, struct Header *hdr, struct AttachPtr **idx, short idxlen, struct Body *cur, int flags) @@ -665,13 +670,11 @@ void mutt_attach_forward(FILE *fp, struct Header *hdr, struct AttachPtr **idx, /** - ** ** the various reply functions, from the attachment menu - ** - ** **/ -/* Create the envelope defaults for a reply. +/** + * attach_reply_envelope_defaults - Create the envelope defaults for a reply * * This function can be invoked in two ways. * @@ -681,7 +684,7 @@ void mutt_attach_forward(FILE *fp, struct Header *hdr, struct AttachPtr **idx, * Or, parent is non-NULL. In this case, cur is the common parent of all the * tagged attachments. * - * Note that this code is horribly similar to envelope_defaults () from send.c. + * Note that this code is horribly similar to envelope_defaults() from send.c. */ static int attach_reply_envelope_defaults(struct Envelope *env, struct AttachPtr **idx, short idxlen, struct Header *parent, int flags) @@ -766,7 +769,9 @@ static int attach_reply_envelope_defaults(struct Envelope *env, struct AttachPtr } -/* This is _very_ similar to send.c's include_reply(). */ +/** + * attach_include_reply - This is _very_ similar to send.c's include_reply() + */ static void attach_include_reply(FILE *fp, FILE *tmpfp, struct Header *cur, int flags) { int cmflags = MUTT_CM_PREFIX | MUTT_CM_DECODE | MUTT_CM_CHARCONV; diff --git a/remailer.c b/remailer.c index 1de348843..d81136bd3 100644 --- a/remailer.c +++ b/remailer.c @@ -125,7 +125,9 @@ static void mix_free_remailer(struct Remailer **r) FREE(r); } -/* parse the type2.list as given by mixmaster -T */ +/** + * mix_type2_list - parse the type2.list as given by mixmaster -T + */ static struct Remailer **mix_type2_list(size_t *l) { FILE *fp = NULL; @@ -348,13 +350,13 @@ static const char *mix_format_caps(struct Remailer *r) return capbuff; } -/* - * Format an entry for the remailer menu. +/** + * mix_entry_fmt - Format an entry for the remailer menu * - * %n number - * %c capabilities - * %s short name - * %a address + * * %n number + * * %c capabilities + * * %s short name + * * %a address */ static const char *mix_entry_fmt(char *dest, size_t destlen, size_t col, int cols, char op, const char *src, const char *prefix, @@ -664,7 +666,9 @@ void mix_make_chain(struct List **chainp) FREE(&chain); } -/* some safety checks before piping the message to mixmaster */ +/** + * mix_check_message - Safety-check the message before passing it to mixmaster + */ int mix_check_message(struct Header *msg) { const char *fqdn = NULL; diff --git a/resize.c b/resize.c index bda469802..20a65fe4f 100644 --- a/resize.c +++ b/resize.c @@ -36,7 +36,9 @@ #endif #endif -/* this routine should be called after receiving SIGWINCH */ +/** + * mutt_resize_screen - Called after receiving SIGWINCH + */ void mutt_resize_screen(void) { char *cp = NULL; diff --git a/rfc1524.c b/rfc1524.c index 117218d77..6c4cf0d54 100644 --- a/rfc1524.c +++ b/rfc1524.c @@ -44,7 +44,10 @@ #include "options.h" #include "protos.h" -/* The command semantics include the following: +/** + * rfc1524_expand_command - Expand expandos in a command + * + * The command semantics include the following: * %s is the filename that contains the mail body data * %t is the content type, like text/plain * %{parameter} is replaced by the parameter value from the content-type field @@ -369,11 +372,12 @@ void rfc1524_free_entry(struct Rfc1524MailcapEntry **entry) FREE(entry); } -/* - * rfc1524_mailcap_lookup attempts to find the given type in the - * list of mailcap files. On success, this returns the entry information - * in *entry, and returns 1. On failure (not found), returns 0. - * If entry == NULL just return 1 if the given type is found. +/** + * rfc1524_mailcap_lookup - Find given type in the list of mailcap files + * + * On success, this returns the entry information in *entry, and returns 1. On + * failure (not found), returns 0. If entry == NULL just return 1 if the given + * type is found. */ int rfc1524_mailcap_lookup(struct Body *a, char *type, struct Rfc1524MailcapEntry *entry, int opt) diff --git a/rfc2047.c b/rfc2047.c index b24453743..0710ccc0b 100644 --- a/rfc2047.c +++ b/rfc2047.c @@ -362,11 +362,13 @@ static size_t encode_block(char *s, char *d, size_t dlen, const char *fromcode, return (*encoder)(s, d, dlen, tocode); } -/* - * Discover how much of the data (d, dlen) can be converted into - * a single encoded word. Return how much data can be converted, - * and set the length *wlen of the encoded word and *encoder. - * We start in column col, which limits the length of the word. +/** + * choose_block - Calculate how much data can be converted + * + * Discover how much of the data (d, dlen) can be converted into a single + * encoded word. Return how much data can be converted, and set the length + * *wlen of the encoded word and *encoder. We start in column col, which + * limits the length of the word. */ static size_t choose_block(char *d, size_t dlen, int col, const char *fromcode, const char *tocode, encoder_t *encoder, size_t *wlen) @@ -727,11 +729,13 @@ error_out_0: return rv; } -/* - * Find the start and end of the first encoded word in the string. - * We use the grammar in section 2 of RFC 2047, but the "encoding" - * must be B or Q. Also, we don't require the encoded word to be - * separated by linear-white-space (section 5(1)). +/** + * find_encoded_word - Find limits of first encoded word in a string + * + * Find the start and end of the first encoded word in the string. We use the + * grammar in section 2 of RFC 2047, but the "encoding" must be B or Q. Also, + * we don't require the encoded word to be separated by linear-white-space + * (section 5(1)). */ static const char *find_encoded_word(const char *s, const char **x) { @@ -760,7 +764,9 @@ static const char *find_encoded_word(const char *s, const char **x) return 0; } -/* return length of linear-white-space */ +/** + * lwslen - return length of linear-white-space + */ static size_t lwslen(const char *s, size_t n) { const char *p = s; @@ -780,7 +786,9 @@ static size_t lwslen(const char *s, size_t n) return len; } -/* return length of linear-white-space : reverse */ +/** + * lwsrlen - return length of linear-white-space : reverse + */ static size_t lwsrlen(const char *s, size_t n) { const char *p = s + n - 1; @@ -801,7 +809,10 @@ static size_t lwsrlen(const char *s, size_t n) return len; } -/* try to decode anything that looks like a valid RFC2047 encoded +/** + * rfc2047_decode - Decode any RFC2047-encoded header fields + * + * try to decode anything that looks like a valid RFC2047 encoded * header field, ignoring RFC822 parsing rules */ void rfc2047_decode(char **pd) diff --git a/rfc2231.c b/rfc2231.c index 91c350283..7588b8d43 100644 --- a/rfc2231.c +++ b/rfc2231.c @@ -119,7 +119,8 @@ static struct Rfc2231Parameter *rfc2231_new_parameter(void) return safe_calloc(1, sizeof(struct Rfc2231Parameter)); } -/* insert parameter into an ordered list. +/** + * rfc2231_list_insert - insert parameter into an ordered list * * Primary sorting key: attribute * Secondary sorting key: index @@ -154,7 +155,9 @@ static void rfc2231_free_parameter(struct Rfc2231Parameter **p) } } -/* process continuation parameters */ +/** + * rfc2231_join_continuations - process continuation parameters + */ static void rfc2231_join_continuations(struct Parameter **head, struct Rfc2231Parameter *par) { struct Rfc2231Parameter *q = NULL; diff --git a/rfc3676.c b/rfc3676.c index 66f5b07a0..8e4146e6b 100644 --- a/rfc3676.c +++ b/rfc3676.c @@ -68,10 +68,13 @@ static int get_quote_level(const char *line) return quoted; } -/* Determines whether to add spacing between/after each quote level: - * >>>foo +/** + * space_quotes - Should we add spaces between quote levels + * + * Determines whether to add spacing between/after each quote level: + * ` >>>foo` * becomes - * > > > foo + * ` > > > foo` */ static int space_quotes(struct State *s) { @@ -84,10 +87,13 @@ static int space_quotes(struct State *s) return option(OPTREFLOWSPACEQUOTES); } -/* Determines whether to add a trailing space to quotes: - * >>> foo +/** + * add_quote_suffix - Should we add a trailing space to quotes + * + * Determines whether to add a trailing space to quotes: + * ` >>> foo` * as opposed to - * >>>foo + * ` >>>foo` */ static bool add_quote_suffix(struct State *s, int ql) { @@ -149,9 +155,12 @@ static void flush_par(struct State *s, struct FlowedState *fst) fst->spaces = 0; } -/* Calculate the paragraph width based upon the current quote level. The start - * of a quoted line will be ">>> ", so we need to subtract the space required - * for the prefix from the terminal width. */ +/** + * quote_width - Calculate the paragraph width based upon the quote level + * + * The start of a quoted line will be ">>> ", so we need to subtract the space + * required for the prefix from the terminal width. + */ static int quote_width(struct State *s, int ql) { int width = mutt_window_wrap_cols(MuttIndexWindow, ReflowWrap); @@ -324,19 +333,20 @@ int rfc3676_handler(struct Body *a, struct State *s) return 0; } -/* - * This routine does RfC3676 space stuffing since it's a MUST. +/** + * rfc3676_space_stuff - Perform required RFC3676 space stuffing + * * Space stuffing means that we have to add leading spaces to * certain lines: * - lines starting with a space * - lines starting with 'From ' - * This routine is only called once right after editing the - * initial message so it's up to the user to take care of stuffing - * when editing the message several times before actually sending it + * This routine is only called once right after editing the initial message so + * it's up to the user to take care of stuffing when editing the message + * several times before actually sending it * - * This is more or less a hack as it replaces the message's content with - * a freshly created copy in a tempfile and modifies the file's mtime - * so we don't trigger code paths watching for mtime changes + * This is more or less a hack as it replaces the message's content with a + * freshly created copy in a tempfile and modifies the file's mtime so we don't + * trigger code paths watching for mtime changes */ void rfc3676_space_stuff(struct Header *hdr) { diff --git a/rfc822.c b/rfc822.c index 3c3071e36..9b58c9954 100644 --- a/rfc822.c +++ b/rfc822.c @@ -673,7 +673,11 @@ done: *pbuf = 0; } -/* note: it is assumed that `buf' is nul terminated! */ +/** + * rfc822_write_address - Write an address to a buffer + * + * Note: it is assumed that `buf' is nul terminated! + */ int rfc822_write_address(char *buf, size_t buflen, struct Address *addr, int display) { char *pbuf = buf; @@ -729,7 +733,11 @@ done: return pbuf - buf; } -/* this should be rfc822_cpy_adr */ +/** + * rfc822_cpy_adr_real - Copy the real address + * + * this should be rfc822_cpy_adr + */ struct Address *rfc822_cpy_adr_real(struct Address *addr) { struct Address *p = rfc822_new_address(); @@ -742,7 +750,11 @@ struct Address *rfc822_cpy_adr_real(struct Address *addr) return p; } -/* this should be rfc822_cpy_adrlist */ +/** + * rfc822_cpy_adr - Copy a list of addresses + * + * this should be rfc822_cpy_adrlist + */ struct Address *rfc822_cpy_adr(struct Address *addr, int prune) { struct Address *top = NULL, *last = NULL; @@ -764,7 +776,11 @@ struct Address *rfc822_cpy_adr(struct Address *addr, int prune) return top; } -/* append list 'b' to list 'a' and return the last element in the new list */ +/** + * rfc822_append - Append one list of addresses on another + * + * append list 'b' to list 'a' and return the last element in the new list + */ struct Address *rfc822_append(struct Address **a, struct Address *b, int prune) { struct Address *tmp = *a; @@ -782,7 +798,11 @@ struct Address *rfc822_append(struct Address **a, struct Address *b, int prune) return tmp; } -/* incomplete. Only used to thwart the APOP MD5 attack (#2846). */ +/** + * rfc822_valid_msgid - Is the message id valid + * + * incomplete. Only used to thwart the APOP MD5 attack (#2846). + */ bool rfc822_valid_msgid(const char *msgid) { /* msg-id = "<" addr-spec ">" diff --git a/safe_asprintf.c b/safe_asprintf.c index 86ef8de2c..7dd59a9ec 100644 --- a/safe_asprintf.c +++ b/safe_asprintf.c @@ -29,6 +29,9 @@ * version using it. */ +/** + * safe_asprintf - Wrapper for vasprintf() + */ #ifdef HAVE_VASPRINTF int safe_asprintf(char **strp, const char *fmt, ...) { diff --git a/send.c b/send.c index b1e29577a..43ebe1849 100644 --- a/send.c +++ b/send.c @@ -86,7 +86,12 @@ static void append_signature(FILE *f) } } -/* compare two e-mail addresses and return 1 if they are equivalent */ +/** + * addrcmp - compare two e-mail addresses + * @param a Address 1 + * @param b Address 2 + * @return true if they are equivalent + */ static bool addrcmp(struct Address *a, struct Address *b) { if (!a->mailbox || !b->mailbox) @@ -96,7 +101,9 @@ static bool addrcmp(struct Address *a, struct Address *b) return true; } -/* search an e-mail address in a list */ +/** + * addrsrc - search an e-mail address in a list + */ static int addrsrc(struct Address *a, struct Address *lst) { for (; lst; lst = lst->next) @@ -107,7 +114,11 @@ static int addrsrc(struct Address *a, struct Address *lst) return 0; } -/* removes addresses from "b" which are contained in "a" */ +/** + * mutt_remove_xrefs - Remove cross-references + * + * Remove addresses from "b" which are contained in "a" + */ struct Address *mutt_remove_xrefs(struct Address *a, struct Address *b) { struct Address *top = NULL, *p = NULL, *prev = NULL; @@ -146,8 +157,11 @@ struct Address *mutt_remove_xrefs(struct Address *a, struct Address *b) return top; } -/* remove any address which matches the current user. if `leave_only' is - * nonzero, don't remove the user's address if it is the only one in the list +/** + * remove_user - Remove any address which matches the current user + * @param a List of addresses + * @param leave_only If set, don't remove the user's address if it it the only + * one in the list */ static struct Address *remove_user(struct Address *a, int leave_only) { @@ -862,11 +876,17 @@ static int envelope_defaults(struct Envelope *env, struct Context *ctx, return 0; } -static int generate_body(FILE *tempfp, /* stream for outgoing message */ - struct Header *msg, /* header for outgoing message */ - int flags, /* compose mode */ - struct Context *ctx, /* current mailbox */ - struct Header *cur) /* current message */ +/** + * generate_body - Create a new email body + * @param tempfp stream for outgoing message + * @param msg header for outgoing message + * @param flags compose mode + * @param ctx current mailbox + * @param cur current message + * @return 0 on success, -1 on error + */ +static int generate_body(FILE *tempfp, struct Header *msg, int flags, + struct Context *ctx, struct Header *cur) { int i; struct Header *h = NULL; @@ -1035,9 +1055,13 @@ void mutt_set_followup_to(struct Envelope *e) } -/* look through the recipients of the message we are replying to, and if - we find an address that matches $alternates, we use that as the default - from field */ +/** + * set_reverse_name - Try to set the 'from' field from the recipients + * + * look through the recipients of the message we are replying to, and if we + * find an address that matches $alternates, we use that as the default from + * field + */ static struct Address *set_reverse_name(struct Envelope *env) { struct Address *tmp = NULL; @@ -1161,7 +1185,9 @@ static int send_message(struct Header *msg) return i; } -/* rfc2047 encode the content-descriptions */ +/** + * mutt_encode_descriptions - rfc2047 encode the content-descriptions + */ void mutt_encode_descriptions(struct Body *b, short recurse) { struct Body *t = NULL; @@ -1177,7 +1203,9 @@ void mutt_encode_descriptions(struct Body *b, short recurse) } } -/* rfc2047 decode them in case of an error */ +/** + * decode_descriptions - rfc2047 decode them in case of an error + */ static void decode_descriptions(struct Body *b) { struct Body *t = NULL; diff --git a/sendlib.c b/sendlib.c index 320dd1bdb..28235ee2c 100644 --- a/sendlib.c +++ b/sendlib.c @@ -803,16 +803,18 @@ static size_t convert_file_to(FILE *file, const char *fromcode, int ncodes, return ret; } -/* - * 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 *fromcode and *tocode to dynamically allocated - * strings, set Content *info, and return the number of characters - * converted inexactly. If no conversion was possible, return -1. +/** + * convert_file_from_to - Convert a file between encodings + * + * 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 + * *fromcode and *tocode to dynamically allocated strings, set Content *info, + * and return the number of characters converted inexactly. If no conversion + * was possible, return -1. * * Both fromcodes and tocodes may be colon-separated lists of charsets. - * However, if fromcode is zero then fromcodes is assumed to be the - * name of a single charset even if it contains a colon. + * However, if fromcode is zero then fromcodes is assumed to be the name of a + * single charset even if it contains a colon. */ static size_t convert_file_from_to(FILE *file, const char *fromcodes, const char *tocodes, char **fromcode, char **tocode, struct Content *info) @@ -882,8 +884,9 @@ static size_t convert_file_from_to(FILE *file, const char *fromcodes, const char return ret; } -/* - * Analyze the contents of a file to determine which MIME encoding to use. +/** + * mutt_get_content_info - Analyze file to determine MIME encoding to use + * * Also set the body charset, sometimes, or not. */ struct Content *mutt_get_content_info(const char *fname, struct Body *b) @@ -1224,7 +1227,9 @@ cleanup: a->hdr->content = NULL; } -/* determine which Content-Transfer-Encoding to use */ +/** + * set_encoding - determine which Content-Transfer-Encoding to use + */ static void set_encoding(struct Body *b, struct Content *info) { char send_charset[SHORT_STRING]; @@ -1271,7 +1276,9 @@ void mutt_stamp_attachment(struct Body *a) a->stamp = time(NULL); } -/* Get a body's character set */ +/** + * mutt_get_body_charset - Get a body's character set + */ char *mutt_get_body_charset(char *d, size_t dlen, struct Body *b) { char *p = NULL; @@ -1291,7 +1298,11 @@ char *mutt_get_body_charset(char *d, size_t dlen, struct Body *b) } -/* Assumes called from send mode where Body->filename points to actual file */ +/** + * mutt_update_encoding - Update the encoding type + * + * Assumes called from send mode where Body->filename points to actual file + */ void mutt_update_encoding(struct Body *a) { struct Content *info = NULL; @@ -1460,7 +1471,10 @@ static int get_toplevel_encoding(struct Body *a) return e; } -/* check for duplicate boundary. return 1 if duplicate */ +/** + * check_boundary - check for duplicate boundary + * @return true if duplicate found + */ static bool check_boundary(const char *boundary, struct Body *b) { char *p = NULL; @@ -1497,7 +1511,9 @@ struct Body *mutt_make_multipart(struct Body *b) return new; } -/* remove the multipart body if it exists */ +/** + * mutt_remove_multipart - remove the multipart body if it exists + */ struct Body *mutt_remove_multipart(struct Body *b) { struct Body *t = NULL; @@ -1526,8 +1542,12 @@ char *mutt_make_date(char *s, size_t len) return s; } -/* wrapper around mutt_write_address() so we can handle very large - recipient lists without needing a huge temporary buffer in memory */ +/** + * mutt_write_address_list - wrapper around mutt_write_address() + * + * So we can handle very large recipient lists without needing a huge temporary + * buffer in memory + */ void mutt_write_address_list(struct Address *adr, FILE *fp, int linelen, int display) { struct Address *tmp = NULL; @@ -1572,7 +1592,10 @@ void mutt_write_address_list(struct Address *adr, FILE *fp, int linelen, int dis /* arbitrary number of elements to grow the array by */ #define REF_INC 16 -/* need to write the list in reverse because they are stored in reverse order +/** + * mutt_write_references - Add the message refrerences to a list + * + * need to write the list in reverse because they are stored in reverse order * when parsed to speed up threading */ void mutt_write_references(struct List *r, FILE *f, int trim) @@ -1619,7 +1642,9 @@ static const char *find_word(const char *src) return p; } -/* like wcwidth(), but gets const char* not wchar_t* */ +/** + * my_width - like wcwidth(), but gets const char* not wchar_t* + */ static int my_width(const char *str, int col, int flags) { wchar_t wc; @@ -1884,8 +1909,12 @@ static int write_one_header(FILE *fp, int pfxw, int max, int wraplen, const char return 0; } -/* split several headers into individual ones and call write_one_header - * for each one */ +/** + * mutt_write_one_header - Write one header line to a file + * + * split several headers into individual ones and call write_one_header + * for each one + */ int mutt_write_one_header(FILE *fp, const char *tag, const char *value, const char *pfx, int wraplen, int flags) { @@ -2226,14 +2255,16 @@ static void alarm_handler(int sig) SigAlrm = 1; } -/* invoke sendmail in a subshell - path (in) path to program to execute - args (in) arguments to pass to program - msg (in) temp file containing message to send - tempfile (out) if sendmail is put in the background, this points - to the temporary file containing the stdout of the - child process. If it is NULL, stderr and stdout - are not redirected. */ +/** + * send_msg - invoke sendmail in a subshell + * @param[in] path Path to program to execute + * @param[in] args Arguments to pass to program + * @param[in] msg Temp file containing message to send + * @param[out] tempfile If sendmail is put in the background, this points + * to the temporary file containing the stdout of the + * child process. If it is NULL, stderr and stdout + * are not redirected. + */ static int send_msg(const char *path, char **args, const char *msg, char **tempfile) { sigset_t set; @@ -2416,10 +2447,17 @@ static char **add_option(char **args, size_t *argslen, size_t *argsmax, char *s) return args; } -int mutt_invoke_sendmail(struct Address *from, /* the sender */ - struct Address *to, struct Address *cc, struct Address *bcc, /* recips */ - const char *msg, /* file containing message */ - int eightbit) /* message contains 8bit chars */ +/** + * mutt_invoke_sendmail - Run sendmail + * @param from The sender + * @param to Recipients + * @param cc Recipients + * @param bcc Recipients + * @param msg File containing message + * @param eightbit Message contains 8bit chars + */ +int mutt_invoke_sendmail(struct Address *from, struct Address *to, struct Address *cc, + struct Address *bcc, const char *msg, int eightbit) { char *ps = NULL, *path = NULL, *s = NULL, *childout = NULL; char **args = NULL; @@ -2585,7 +2623,11 @@ int mutt_invoke_sendmail(struct Address *from, /* the sender */ return i; } -/* For postponing (!final) do the necessary encodings only */ +/** + * mutt_prepare_envelope - Prepare an email header + * + * For postponing (!final) do the necessary encodings only + */ void mutt_prepare_envelope(struct Envelope *env, int final) { char buffer[LONG_STRING]; @@ -2769,7 +2811,11 @@ int mutt_bounce_message(FILE *fp, struct Header *h, struct Address *to) } -/* given a list of addresses, return a list of unique addresses */ +/** + * mutt_remove_duplicates - Remove duplicate addresses + * + * given a list of addresses, return a list of unique addresses + */ struct Address *mutt_remove_duplicates(struct Address *addr) { struct Address *top = addr; @@ -2826,7 +2872,9 @@ static void set_noconv_flags(struct Body *b, short flag) } } -/* Handle a Fcc with multiple, comma separated entries. */ +/** + * mutt_write_multiple_fcc - Handle FCC with multiple, comma separated entries + */ int mutt_write_multiple_fcc(const char *path, struct Header *hdr, const char *msgid, int post, char *fcc, char **finalpath) { diff --git a/sha1.c b/sha1.c index e9e402a8e..a0bfd1a04 100644 --- a/sha1.c +++ b/sha1.c @@ -58,7 +58,11 @@ w = rol(w, 30); -/* Hash a single 512-bit block. This is the core of the algorithm. */ +/** + * sha1_transform - Hash a single 512-bit block + * + * This is the core of the algorithm. + */ void sha1_transform(uint32_t state[5], const unsigned char buffer[64]) { uint32_t a, b, c, d, e; @@ -178,7 +182,9 @@ void sha1_transform(uint32_t state[5], const unsigned char buffer[64]) } -/* sha1_init - Initialize new context */ +/** + * sha1_init - Initialize new context + */ void sha1_init(struct Sha1Ctx *context) { /* SHA1 initialization constants */ @@ -191,7 +197,9 @@ void sha1_init(struct Sha1Ctx *context) } -/* Run your data through this. */ +/** + * sha1_update - Run your data through this + */ void sha1_update(struct Sha1Ctx *context, const unsigned char *data, uint32_t len) { uint32_t i; @@ -218,7 +226,9 @@ void sha1_update(struct Sha1Ctx *context, const unsigned char *data, uint32_t le } -/* Add padding and return the message digest. */ +/** + * sha1_final - Add padding and return the message digest + */ void sha1_final(unsigned char digest[20], struct Sha1Ctx *context) { unsigned i; diff --git a/signal.c b/signal.c index 4468276ab..c4278306f 100644 --- a/signal.c +++ b/signal.c @@ -37,7 +37,9 @@ static struct sigaction SysOldInt; static struct sigaction SysOldQuit; static int IsEndwin = 0; -/* Attempt to catch "ordinary" signals and shut down gracefully. */ +/** + * exit_handler - Attempt to catch "ordinary" signals and shut down gracefully + */ static void exit_handler(int sig) { curs_set(1); @@ -169,7 +171,11 @@ void mutt_signal_init(void) #endif } -/* signals which are important to block while doing critical ops */ +/** + * mutt_block_signals - Block signals during critical ops + * + * signals which are important to block while doing critical ops + */ void mutt_block_signals(void) { if (!option(OPTSIGNALSBLOCKED)) @@ -187,7 +193,9 @@ void mutt_block_signals(void) } } -/* restore the previous signal mask */ +/** + * mutt_unblock_signals - restore the previous signal mask + */ void mutt_unblock_signals(void) { if (option(OPTSIGNALSBLOCKED)) diff --git a/smtp.c b/smtp.c index 428946858..69c65e623 100644 --- a/smtp.c +++ b/smtp.c @@ -247,7 +247,9 @@ static int smtp_data(struct Connection *conn, const char *msgfile) } -/* Returns true if a contains at least one 8-bit character, false if none do. +/** + * address_uses_unicode - Do any addresses use Unicode + * @return true if any of the string of addresses use 8-bit characters */ static bool address_uses_unicode(const char *a) { @@ -265,8 +267,9 @@ static bool address_uses_unicode(const char *a) } -/* Returns 1 if any address in a contains at least one 8-bit - * character, 0 if none do. +/** + * addresses_use_unicode - Do any of a list of addresses use Unicode + * @return true if any use 8-bit characters */ static bool addresses_use_unicode(const struct Address *a) { @@ -572,6 +575,7 @@ error: return -1; } #endif /* USE_SASL */ + static int smtp_open(struct Connection *conn) { int rc; diff --git a/status.c b/status.c index 8374640f1..5d229c4cd 100644 --- a/status.c +++ b/status.c @@ -49,25 +49,31 @@ static char *get_sort_str(char *buf, size_t buflen, int method) static void _menu_status_line(char *buf, size_t buflen, size_t col, int cols, struct Menu *menu, const char *p); -/* %b = number of incoming folders with unread messages [option] - * %d = number of deleted messages [option] - * %f = full mailbox path - * %F = number of flagged messages [option] - * %h = hostname - * %l = length of mailbox (in bytes) [option] - * %m = total number of messages [option] - * %M = number of messages shown (virtual message count when limiting) [option] - * %n = number of new messages [option] - * %o = number of old unread messages [option] - * %p = number of postponed messages [option] - * %P = percent of way through index - * %r = readonly/wontwrite/changed flag - * %s = current sorting method ($sort) - * %S = current aux sorting method ($sort_aux) - * %t = # of tagged messages [option] - * %u = number of unread messages [option] - * %v = Mutt version - * %V = currently active limit pattern [option] */ +/** + * status_format_str - Format a string for the status bar + * + * | Expando | Description + * |:--------|:---------------------------------------------------------------- + * | \%b | number of incoming folders with unread messages [option] + * | \%d | number of deleted messages [option] + * | \%f | full mailbox path + * | \%F | number of flagged messages [option] + * | \%h | hostname + * | \%l | length of mailbox (in bytes) [option] + * | \%m | total number of messages [option] + * | \%M | number of messages shown (virtual message count when limiting) [option] + * | \%n | number of new messages [option] + * | \%o | number of old unread messages [option] + * | \%p | number of postponed messages [option] + * | \%P | percent of way through index + * | \%r | readonly/wontwrite/changed flag + * | \%s | current sorting method ($sort) + * | \%S | current aux sorting method ($sort_aux) + * | \%t | # of tagged messages [option] + * | \%u | number of unread messages [option] + * | \%v | Mutt version + * | \%V | currently active limit pattern [option] + */ static const char *status_format_str(char *buf, size_t buflen, size_t col, int cols, char op, const char *src, const char *prefix, const char *ifstring, const char *elsestring, diff --git a/thread.c b/thread.c index 7b7e770a4..92f6aaed2 100644 --- a/thread.c +++ b/thread.c @@ -42,7 +42,9 @@ #define VISIBLE(hdr, ctx) \ (hdr->virtual >= 0 || (hdr->collapsed && (!ctx->pattern || hdr->limited))) -/* determine whether a is a descendant of b */ +/** + * is_descendant - Is one thread a descendant of another + */ static int is_descendant(struct MuttThread *a, struct MuttThread *b) { while (a) @@ -54,7 +56,9 @@ static int is_descendant(struct MuttThread *a, struct MuttThread *b) return 0; } -/* Determines whether to display a message's subject. */ +/** + * need_display_subject - Determines whether to display a message's subject + */ static int need_display_subject(struct Context *ctx, struct Header *hdr) { struct MuttThread *tmp = NULL, *tree = hdr->thread; @@ -130,7 +134,10 @@ static void linearize_tree(struct Context *ctx) } } -/* this calculates whether a node is the root of a subtree that has visible +/** + * calculate_visibility - Are tree nodes visible + * + * 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 * depth anyway, and whether any of its later siblings are roots of visible * subtrees. while it's at it, it frees the old thread display, so we can @@ -237,13 +244,16 @@ static void calculate_visibility(struct Context *ctx, int *max_depth) } } -/* 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 are the macros MUTT_TREE_* defined in mutt.h. +/** + * mutt_draw_tree - Draw a tree of threaded emails + * + * 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 + * are the macros MUTT_TREE_* defined in mutt.h. * * ncurses should automatically use the default ASCII characters instead of - * graphics chars on terminals which don't support them (see the man page - * for curs_addch). + * graphics chars on terminals which don't support them (see the man page for + * curs_addch). */ void mutt_draw_tree(struct Context *ctx) { @@ -356,10 +366,14 @@ void mutt_draw_tree(struct Context *ctx) FREE(&arrow); } -/* since we may be trying to attach as a pseudo-thread a MuttThread that +/** + * make_subject_list - Create a list of all subjects in a thread + * + * since we may be trying to attach as a pseudo-thread a MuttThread that * has no message, we have to make a list of all the subjects of its * most immediate existing descendants. we also note the earliest - * date on any of the parents and put it in *dateptr. */ + * date on any of the parents and put it in *dateptr. + */ static struct List *make_subject_list(struct MuttThread *cur, time_t *dateptr) { struct MuttThread *start = cur; @@ -420,9 +434,11 @@ static struct List *make_subject_list(struct MuttThread *cur, time_t *dateptr) return subjects; } -/* find the best possible match for a parent message based upon subject. - * if there are multiple matches, the one which was sent the latest, but - * before the current message, is used. +/** + * find_subject - Find the best possible match for a parent based on subject + * + * If there are multiple matches, the one which was sent the latest, but before + * the current message, is used. */ static struct MuttThread *find_subject(struct Context *ctx, struct MuttThread *cur) { @@ -461,9 +477,13 @@ static struct MuttThread *find_subject(struct Context *ctx, struct MuttThread *c return last; } -/* remove cur and its descendants from their current location. - * also make sure ancestors of cur no longer are sorted by the - * fact that cur is their descendant. */ +/** + * unlink_message - Break the message out of the thread + * + * Remove cur and its descendants from their current location. Also make sure + * ancestors of cur no longer are sorted by the fact that cur is their + * descendant. + */ static void unlink_message(struct MuttThread **old, struct MuttThread *cur) { struct MuttThread *tmp = NULL; @@ -483,7 +503,11 @@ static void unlink_message(struct MuttThread **old, struct MuttThread *cur) } } -/* add cur as a prior sibling of *new, with parent newparent */ +/** + * insert_message - Insert a message into a thread + * + * add cur as a prior sibling of *new, with parent newparent + */ static void insert_message(struct MuttThread **new, struct MuttThread *newparent, struct MuttThread *cur) { @@ -513,7 +537,11 @@ static struct Hash *make_subj_hash(struct Context *ctx) return hash; } -/* thread by subject things that didn't get threaded by message-id */ +/** + * pseudo_threads - Thread messages by subject + * + * Thread by subject things that didn't get threaded by message-id + */ static void pseudo_threads(struct Context *ctx) { struct MuttThread *tree = ctx->tree, *top = tree; @@ -1035,8 +1063,12 @@ static struct Header *find_virtual(struct MuttThread *cur, int reverse) } } -/* dir => true when moving forward, false when moving in reverse - * subthreads => false when moving to next thread, true when moving to next subthread +/** + * _mutt_aside_thread - Find the next/previous (sub)thread + * @param hdr Search from this message + * @param dir Direction to search: 'true' forwards, 'false' backwards + * @param subthreads Search subthreads: 'true' subthread, 'false' not + * @return index into the virtual email table */ int _mutt_aside_thread(struct Header *hdr, short dir, short subthreads) { @@ -1323,9 +1355,12 @@ int _mutt_traverse_thread(struct Context *ctx, struct Header *cur, int flag) } -/* 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. */ +/** + * mutt_messages_in_thread - Count the messages in a thread + * + * 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. + */ int mutt_messages_in_thread(struct Context *ctx, struct Header *hdr, int flag) { struct MuttThread *threads[2]; diff --git a/url.c b/url.c index dc2caf779..fff4cd572 100644 --- a/url.c +++ b/url.c @@ -98,9 +98,12 @@ enum UrlScheme url_check_scheme(const char *s) return (enum UrlScheme) i; } -/* ciss_parse_userhost: fill in components of ciss with info from src. Note - * these are pointers into src, which is altered with '\0's. Port of 0 - * means no port given. */ +/** + * ciss_parse_userhost - fill in components of ciss with info from src + * + * Note: These are pointers into src, which is altered with '\0's. + * Port of 0 means no port given. + */ static int ciss_parse_userhost(struct CissUrl *ciss, char *src) { char *t = NULL, *p = NULL; @@ -166,8 +169,12 @@ static int ciss_parse_userhost(struct CissUrl *ciss, char *src) -1; } -/* url_parse_ciss: Fill in CissUrl. char* elements are pointers into src, - * which is modified by this call (duplicate it first if you need to). */ +/** + * url_parse_ciss - Fill in CissUrl. + * + * char* elements are pointers into src, which is modified by this call + * (duplicate it first if you need to). + */ int url_parse_ciss(struct CissUrl *ciss, char *src) { char *tmp = NULL; @@ -201,7 +208,9 @@ static void url_pct_encode(char *dst, size_t l, const char *src) *dst = 0; } -/* url_ciss_tostring: output the URL string for a given CISS object. */ +/** + * url_ciss_tostring - output the URL string for a given CISS object + */ int url_ciss_tostring(struct CissUrl *ciss, char *dest, size_t len, int flags) { long l;