From: Richard Russon Date: Sat, 15 Jul 2017 09:08:59 +0000 (+0100) Subject: doxygen: fix all comments X-Git-Tag: neomutt-20170907~66^2~4 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=bd26fef73bd9264d22c6265c1c806d04bf38521f;p=neomutt doxygen: fix all comments --- diff --git a/attach.c b/attach.c index e10f0739b..4be58622e 100644 --- a/attach.c +++ b/attach.c @@ -209,14 +209,17 @@ bailout: return rc; } -/* +/** + * mutt_edit_attachment - Edit an attachment + * @param a Email containing attachment + * @return 1 if editor found, 0 if not + * * Currently, this only works for send mode, as it assumes that the * Body->filename actually contains the information. I'm not sure * we want to deal with editing attachments we've already received, * so this should be ok. * - * Returns 1 if editor found, 0 if not (useful to tell calling menu to - * redraw) + * Returning 0 is useful to tell the calling menu to redraw */ int mutt_edit_attachment(struct Body *a) { diff --git a/bcache.h b/bcache.h index cb1ef605a..8b4e3c1d7 100644 --- a/bcache.h +++ b/bcache.h @@ -24,36 +24,75 @@ struct Account; struct BodyCache; -/* - * Parameters: - * - 'account' is the current mailbox' account (required) - * - 'mailbox' is the path to the mailbox of the account (optional): - * the driver using it is responsible for ensuring that hierarchies - * are separated by '/' (if it knows of such a concepts like - * mailboxes or hierarchies) - * Returns NULL on failure. +/** + * mutt_bcache_open - Open an Email-Body Cache + * @param account current mailbox' account (required) + * @param mailbox path to the mailbox of the account (optional) + * @return NULL on failure + * + * The driver using it is responsible for ensuring that hierarchies are + * separated by '/' (if it knows of such a concepts like mailboxes or + * hierarchies) */ struct BodyCache *mutt_bcache_open(struct Account *account, const char *mailbox); -/* free all memory of bcache and finally FREE() it, too */ +/** + * mutt_bcache_close - Close an Email-Body Cache + * @param bcache Body cache + * + * Free all memory of bcache and finally FREE() it, too. + */ void mutt_bcache_close(struct BodyCache **bcache); -/* - * Parameters: - * - 'bcache' is the pointer returned by mutt_bcache_open() (required) - * - 'id' is a per-mailbox unique identifier for the message (required) - * These return NULL/-1 on failure and FILE pointer/0 on success. +/** + * mutt_bcache_get - Open a file in the Body Cache + * @param bcache Body Cache from mutt_bcache_open() + * @param id Per-mailbox unique identifier for the message + * @return FILE* on success, NULL on failure */ - FILE *mutt_bcache_get(struct BodyCache *bcache, const char *id); -/* tmp: the returned FILE* is in a temporary location. - * if set, use mutt_bcache_commit to put it into place */ + +/** + * mutt_bcache_put - Create a file in the Body Cache + * @param bcache Body Cache from mutt_bcache_open() + * @param id Per-mailbox unique identifier for the message + * @param tmp Returned FILE* is in a temporary location. + * If set, use mutt_bcache_commit to put it into place + * @return FILE* on success, NULL on failure + */ FILE *mutt_bcache_put(struct BodyCache *bcache, const char *id, int tmp); + +/** + * mutt_bcache_commit - Move a temporary file into the Body Cache + * @param bcache Body Cache from mutt_bcache_open() + * @param id Per-mailbox unique identifier for the message + * @return 0 on success, -1 on failure + */ int mutt_bcache_commit(struct BodyCache *bcache, const char *id); + +/** + * mutt_bcache_del - Delete a file from the Body Cache + * @param bcache Body Cache from mutt_bcache_open() + * @param id Per-mailbox unique identifier for the message + * @return 0 on success, -1 on failure + */ int mutt_bcache_del(struct BodyCache *bcache, const char *id); + +/** + * mutt_bcache_exists - Check if a file exists in the Body Cache + * @param bcache Body Cache from mutt_bcache_open() + * @param id Per-mailbox unique identifier for the message + * @return 0 on success, -1 on failure + */ int mutt_bcache_exists(struct BodyCache *bcache, const char *id); -/* +/** + * mutt_bcache_list - Find matching entries in the Body Cache + * @param bcache Body Cache from mutt_bcache_open() + * @param want_id Callback function called for each match + * @param data Data to pass to the callback function + * @return -1 on failure, count (>=0) of matching items + * * This more or less "examines" the cache and calls a function with * each id it finds if given. * @@ -64,9 +103,6 @@ int mutt_bcache_exists(struct BodyCache *bcache, const char *id); * listing is aborted and continued otherwise. The callback is optional * so that this function can be used to count the items in the cache * (see below for return value). - * - * This returns -1 on failure and the count (>=0) of items processed - * otherwise. */ int mutt_bcache_list(struct BodyCache *bcache, int (*want_id)(const char *id, struct BodyCache *bcache, void *data), diff --git a/buffer.h b/buffer.h index 1d088047d..2d3384e5d 100644 --- a/buffer.h +++ b/buffer.h @@ -27,13 +27,13 @@ struct Buffer }; /* flags for mutt_extract_token() */ -#define MUTT_TOKEN_EQUAL (1 << 0) /* treat '=' as a special */ -#define MUTT_TOKEN_CONDENSE (1 << 1) /* ^(char) to control chars (macros) */ -#define MUTT_TOKEN_SPACE (1 << 2) /* don't treat whitespace as a term */ -#define MUTT_TOKEN_QUOTE (1 << 3) /* don't interpret quotes */ -#define MUTT_TOKEN_PATTERN (1 << 4) /* !)|~ are terms (for patterns) */ -#define MUTT_TOKEN_COMMENT (1 << 5) /* don't reap comments */ -#define MUTT_TOKEN_SEMICOLON (1 << 6) /* don't treat ; as special */ +#define MUTT_TOKEN_EQUAL (1 << 0) /**< treat '=' as a special */ +#define MUTT_TOKEN_CONDENSE (1 << 1) /**< ^(char) to control chars (macros) */ +#define MUTT_TOKEN_SPACE (1 << 2) /**< don't treat whitespace as a term */ +#define MUTT_TOKEN_QUOTE (1 << 3) /**< don't interpret quotes */ +#define MUTT_TOKEN_PATTERN (1 << 4) /**< !)|~ are terms (for patterns) */ +#define MUTT_TOKEN_COMMENT (1 << 5) /**< don't reap comments */ +#define MUTT_TOKEN_SEMICOLON (1 << 6) /**< don't treat ; as special */ struct Buffer *mutt_buffer_new(void); struct Buffer *mutt_buffer_init(struct Buffer *b); diff --git a/buffy.c b/buffy.c index 04eecddcb..a0d196ea9 100644 --- a/buffy.c +++ b/buffy.c @@ -163,10 +163,15 @@ static void buffy_free(struct Buffy **mailbox) FREE(mailbox); } -/* Checks the specified maildir subdir (cur or new) for new mail or mail counts. - * check_new: if true, check for new mail. - * check_stats: if true, count total, new, and flagged messages. - * Returns 1 if the dir has new mail. +/** + * buffy_maildir_check_dir - Check for new mail / mail counts + * @param mailbox Mailbox to check + * @param dir_name Path to mailbox + * @param check_new if true, check for new mail + * @param check_stats if true, count total, new, and flagged messages + * @return 1 if the dir has new mail + * + * Checks the specified maildir subdir (cur or new) for new mail or mail counts. */ static int buffy_maildir_check_dir(struct Buffy *mailbox, const char *dir_name, int check_new, int check_stats) @@ -244,9 +249,11 @@ static int buffy_maildir_check_dir(struct Buffy *mailbox, const char *dir_name, return rc; } -/* Checks new mail for a maildir mailbox. - * check_stats: if true, also count total, new, and flagged messages. - * Returns 1 if the mailbox has new mail. +/** + * buffy_maildir_check - Check for new mail in a maildir mailbox + * @param mailbox Mailbox to check + * @param check_stats if true, also count total, new, and flagged messages + * @return 1 if the mailbox has new mail */ static int buffy_maildir_check(struct Buffy *mailbox, int check_stats) { @@ -269,9 +276,12 @@ static int buffy_maildir_check(struct Buffy *mailbox, int check_stats) return rc; } -/* Checks new mail for an mbox mailbox - * check_stats: if true, also count total, new, and flagged messages. - * Returns 1 if the mailbox has new mail. +/** + * buffy_mbox_check - Check for new mail for an mbox mailbox + * @param mailbox Mailbox to check + * @param sb stat(2) information about the mailbox + * @param check_stats if true, also count total, new, and flagged messages + * @return 1 if the mailbox has new mail */ static int buffy_mbox_check(struct Buffy *mailbox, struct stat *sb, int check_stats) { diff --git a/complete.c b/complete.c index 022a501ba..73791e180 100644 --- a/complete.c +++ b/complete.c @@ -33,10 +33,14 @@ #include "nntp.h" #endif -/* given a partial pathname, this routine fills in as much of the rest of the - * path as is unique. +/** + * mutt_complete - Attempt to complete a partial pathname + * @param s Buffer containing pathname + * @param slen Buffer length + * @return 0 if ok, -1 if no matches * - * return 0 if ok, -1 if no matches + * Given a partial pathname, fill in as much of the rest of the path as is + * unique. */ int mutt_complete(char *s, size_t slen) { diff --git a/compose.c b/compose.c index 4b5287fe0..ad186e9e8 100644 --- a/compose.c +++ b/compose.c @@ -575,12 +575,13 @@ static void compose_menu_redraw(struct Menu *menu) } -/* - * cum_attachs_size: Cumulative Attachments Size +/** + * cum_attachs_size - Cumulative Attachments Size + * @param menu Menu listing attachments + * @return Number of bytes in attachments * - * Returns the total number of bytes used by the attachments in the - * attachment list _after_ content-transfer-encodings have been - * applied. + * Returns the total number of bytes used by the attachments in the attachment + * list _after_ content-transfer-encodings have been applied. */ static unsigned long cum_attachs_size(struct Menu *menu) { diff --git a/copy.h b/copy.h index 4b24babdc..2cb794e2a 100644 --- a/copy.h +++ b/copy.h @@ -24,45 +24,43 @@ struct Body; struct Header; struct Context; -/* flags to _mutt_copy_message */ -#define MUTT_CM_NOHEADER (1 << 0) /* don't copy the message header */ -#define MUTT_CM_PREFIX (1 << 1) /* quote the message */ -#define MUTT_CM_DECODE (1 << 2) /* decode the message body into text/plain */ -#define MUTT_CM_DISPLAY (1 << 3) /* output is displayed to the user */ -#define MUTT_CM_UPDATE (1 << 4) /* update structs on sync */ -#define MUTT_CM_WEED (1 << 5) /* weed message/rfc822 attachment headers */ -#define MUTT_CM_CHARCONV (1 << 6) /* perform character set conversions */ -#define MUTT_CM_PRINTING (1 << 7) /* printing the message - display light */ -#define MUTT_CM_REPLYING (1 << 8) /* replying the message */ - -#define MUTT_CM_DECODE_PGP (1 << 9) /* used for decoding PGP messages */ -#define MUTT_CM_DECODE_SMIME (1 << 10) /* used for decoding S/MIME messages */ +/**< flags to _mutt_copy_message */ +#define MUTT_CM_NOHEADER (1 << 0) /**< don't copy the message header */ +#define MUTT_CM_PREFIX (1 << 1) /**< quote the message */ +#define MUTT_CM_DECODE (1 << 2) /**< decode the message body into text/plain */ +#define MUTT_CM_DISPLAY (1 << 3) /**< output is displayed to the user */ +#define MUTT_CM_UPDATE (1 << 4) /**< update structs on sync */ +#define MUTT_CM_WEED (1 << 5) /**< weed message/rfc822 attachment headers */ +#define MUTT_CM_CHARCONV (1 << 6) /**< perform character set conversions */ +#define MUTT_CM_PRINTING (1 << 7) /**< printing the message - display light */ +#define MUTT_CM_REPLYING (1 << 8) /**< replying the message */ +#define MUTT_CM_DECODE_PGP (1 << 9) /**< used for decoding PGP messages */ +#define MUTT_CM_DECODE_SMIME (1 << 10) /**< used for decoding S/MIME messages */ #define MUTT_CM_DECODE_CRYPT (MUTT_CM_DECODE_PGP | MUTT_CM_DECODE_SMIME) - -#define MUTT_CM_VERIFY (1 << 11) /* do signature verification */ +#define MUTT_CM_VERIFY (1 << 11) /**< do signature verification */ /* flags for mutt_copy_header() */ -#define CH_UPDATE (1 << 0) /* update the status and x-status fields? */ -#define CH_WEED (1 << 1) /* weed the headers? */ -#define CH_DECODE (1 << 2) /* do RFC1522 decoding? */ -#define CH_XMIT (1 << 3) /* transmitting this message? */ -#define CH_FROM (1 << 4) /* retain the "From " message separator? */ -#define CH_PREFIX (1 << 5) /* use Prefix string? */ -#define CH_NOSTATUS (1 << 6) /* suppress the status and x-status fields */ -#define CH_REORDER (1 << 7) /* Re-order output of headers */ -#define CH_NONEWLINE (1 << 8) /* don't output terminating newline */ -#define CH_MIME (1 << 9) /* ignore MIME fields */ -#define CH_UPDATE_LEN (1 << 10) /* update Lines: and Content-Length: */ -#define CH_TXTPLAIN (1 << 11) /* generate text/plain MIME headers */ -#define CH_NOLEN (1 << 12) /* don't write Content-Length: and Lines: */ -#define CH_WEED_DELIVERED (1 << 13) /* weed eventual Delivered-To headers */ -#define CH_FORCE_FROM (1 << 14) /* give CH_FROM precedence over CH_WEED? */ -#define CH_NOQFROM (1 << 15) /* ignore ">From " line */ -#define CH_UPDATE_IRT (1 << 16) /* update In-Reply-To: */ -#define CH_UPDATE_REFS (1 << 17) /* update References: */ -#define CH_DISPLAY (1 << 18) /* display result to user */ -#define CH_UPDATE_LABEL (1 << 19) /* update X-Label: from hdr->env->x_label? */ -#define CH_VIRTUAL (1 << 20) /* write virtual header lines too */ +#define CH_UPDATE (1 << 0) /**< update the status and x-status fields? */ +#define CH_WEED (1 << 1) /**< weed the headers? */ +#define CH_DECODE (1 << 2) /**< do RFC1522 decoding? */ +#define CH_XMIT (1 << 3) /**< transmitting this message? */ +#define CH_FROM (1 << 4) /**< retain the "From " message separator? */ +#define CH_PREFIX (1 << 5) /**< use Prefix string? */ +#define CH_NOSTATUS (1 << 6) /**< suppress the status and x-status fields */ +#define CH_REORDER (1 << 7) /**< Re-order output of headers */ +#define CH_NONEWLINE (1 << 8) /**< don't output terminating newline */ +#define CH_MIME (1 << 9) /**< ignore MIME fields */ +#define CH_UPDATE_LEN (1 << 10) /**< update Lines: and Content-Length: */ +#define CH_TXTPLAIN (1 << 11) /**< generate text/plain MIME headers */ +#define CH_NOLEN (1 << 12) /**< don't write Content-Length: and Lines: */ +#define CH_WEED_DELIVERED (1 << 13) /**< weed eventual Delivered-To headers */ +#define CH_FORCE_FROM (1 << 14) /**< give CH_FROM precedence over CH_WEED? */ +#define CH_NOQFROM (1 << 15) /**< ignore ">From " line */ +#define CH_UPDATE_IRT (1 << 16) /**< update In-Reply-To: */ +#define CH_UPDATE_REFS (1 << 17) /**< update References: */ +#define CH_DISPLAY (1 << 18) /**< display result to user */ +#define CH_UPDATE_LABEL (1 << 19) /**< update X-Label: from hdr->env->x_label? */ +#define CH_VIRTUAL (1 << 20) /**< write virtual header lines too */ int mutt_copy_hdr(FILE *in, FILE *out, LOFF_T off_start, LOFF_T off_end, int flags, const char *prefix); diff --git a/curs_lib.c b/curs_lib.c index bdc82c71f..92d9167df 100644 --- a/curs_lib.c +++ b/curs_lib.c @@ -1349,12 +1349,14 @@ out: return l; } -/* - * returns the number of bytes the first (multibyte) character - * of input consumes: - * < 0 ... conversion error - * = 0 ... end of input - * > 0 ... length (bytes) +/** + * mutt_charlen - Count the bytes in a (multibyte) character + * @param[in] s String to be examined + * @param[out] width Number of screen columns the character would use + * @return Number of bytes in the first (multibyte) character of input consumes + * * < 0 ... conversion error + * * = 0 ... end of input + * * > 0 ... length (bytes) */ int mutt_charlen(const char *s, int *width) { @@ -1373,9 +1375,10 @@ int mutt_charlen(const char *s, int *width) return (k == (size_t)(-1) || k == (size_t)(-2)) ? -1 : k; } -/* - * mutt_strwidth is like mutt_strlen except that it returns the width - * referring to the number of character cells. +/** + * mutt_strwidth - Measure a string's width in screen cells + * @param s String to be measured + * @return Number of screen cells string would use */ int mutt_strwidth(const char *s) { diff --git a/editmsg.c b/editmsg.c index 018401fdf..6d5cc1f8d 100644 --- a/editmsg.c +++ b/editmsg.c @@ -37,12 +37,14 @@ #include "options.h" #include "protos.h" -/* - * return value: - * - * 1 message not modified - * 0 message edited successfully - * -1 error +/** + * edit_one_message - Edit an email + * @param ctx Context + * @param cur Header of email + * @return + * * 1 Message not modified + * * 0 Message edited successfully + * * -1 Error */ static int edit_one_message(struct Context *ctx, struct Header *cur) { diff --git a/enter.c b/enter.c index 4aa053207..f930067af 100644 --- a/enter.c +++ b/enter.c @@ -201,8 +201,10 @@ static void replace_part(struct EnterState *state, size_t from, char *buf) state->lastchar = state->curpos + savelen; } -/* - * Return 1 if the character is not typically part of a pathname +/** + * is_shell_char - Is character not typically part of a pathname + * @param ch Character to examine + * @return 1 if the character is not typically part of a pathname */ static inline int is_shell_char(wchar_t ch) { @@ -210,14 +212,18 @@ static inline int is_shell_char(wchar_t ch) return wcschr(shell_chars, ch) != NULL; } -/* This function is for very basic input, currently used only by the +/** + * mutt_enter_string - Ask the user for a string + * @param buf Buffer to store the string + * @param buflen Buffer length + * @param col Initial cursor position + * @param flags Flags such as MUTT_FILE + * @return 0 if input was given, -1 if abort + * + * This function is for very basic input, currently used only by the * built-in editor. It does not handle screen redrawing on resizes * well, because there is no active menu for the built-in editor. * Most callers should prefer mutt_get_field() instead. - * - * Returns: - * 0 if input was given - * -1 if abort. */ int mutt_enter_string(char *buf, size_t buflen, int col, int flags) { @@ -239,11 +245,20 @@ int mutt_enter_string(char *buf, size_t buflen, int col, int flags) return rv; } -/* - * Returns: - * 1 need to redraw the screen and call me again - * 0 if input was given - * -1 if abort. +/** + * _mutt_enter_string - Ask the user for a string + * @param[in] buf Buffer to store the string + * @param[in] buflen Buffer length + * @param[in] col Initial cursor position + * @param[in] flags Flags such as MUTT_FILE + * @param[in] multiple Allow multiple matches + * @param[out] files List of files selected + * @param[out] numfiles Number of files selected + * @param[out] state Current state (if function is called repeatedly) + * @return + * * 1 need to redraw the screen and call me again + * * 0 if input was given + * * -1 if abort. */ int _mutt_enter_string(char *buf, size_t buflen, int col, int flags, int multiple, char ***files, int *numfiles, struct EnterState *state) diff --git a/format_flags.h b/format_flags.h index 9166ea48f..bde621237 100644 --- a/format_flags.h +++ b/format_flags.h @@ -26,7 +26,7 @@ enum FormatFlag MUTT_FORMAT_FORCESUBJ = (1 << 0), /**< print the subject even if unchanged */ MUTT_FORMAT_TREE = (1 << 1), /**< draw the thread tree */ MUTT_FORMAT_MAKEPRINT = (1 << 2), /**< make sure that all chars are printable */ - MUTT_FORMAT_OPTIONAL = (1 << 3), + MUTT_FORMAT_OPTIONAL = (1 << 3), /**< allow optional field processing */ MUTT_FORMAT_STAT_FILE = (1 << 4), /**< used by mutt_attach_fmt */ MUTT_FORMAT_ARROWCURSOR = (1 << 5), /**< reserve space for arrow_cursor */ MUTT_FORMAT_INDEX = (1 << 6), /**< this is a main index entry */ diff --git a/handler.c b/handler.c index c78b55581..6848e2b2f 100644 --- a/handler.c +++ b/handler.c @@ -1004,11 +1004,12 @@ static int is_mmnoask(const char *buf) return 0; } -/* - * Returns: - * 1 if the body part should be filtered by a mailcap entry prior to viewing inline. - * - * 0 otherwise +/** + * is_autoview - Should email body be filtered by mailcap + * @param b Email body + * @return + * * 1 body part should be filtered by a mailcap entry prior to viewing inline. + * * 0 otherwise */ static int is_autoview(struct Body *b) { diff --git a/hash.h b/hash.h index e0d963b74..6cef52ec8 100644 --- a/hash.h +++ b/hash.h @@ -43,9 +43,9 @@ struct Hash }; /* flags for hash_create() */ -#define MUTT_HASH_STRCASECMP (1 << 0) /* use strcasecmp() to compare keys */ -#define MUTT_HASH_STRDUP_KEYS (1 << 1) /* make a copy of the keys */ -#define MUTT_HASH_ALLOW_DUPS (1 << 2) /* allow duplicate keys to be inserted */ +#define MUTT_HASH_STRCASECMP (1 << 0) /**< use strcasecmp() to compare keys */ +#define MUTT_HASH_STRDUP_KEYS (1 << 1) /**< make a copy of the keys */ +#define MUTT_HASH_ALLOW_DUPS (1 << 2) /**< allow duplicate keys to be inserted */ struct Hash *hash_create(int nelem, int flags); struct Hash *int_hash_create(int nelem, int flags); diff --git a/hdrline.c b/hdrline.c index 7db047e97..4bf0d41bc 100644 --- a/hdrline.c +++ b/hdrline.c @@ -80,9 +80,16 @@ bool mutt_is_subscribed_list(struct Address *addr) return false; } -/* Search for a mailing list in the list of addresses pointed to by adr. - * If one is found, print pfx and the name of the list into buf, then - * return 1. Otherwise, simply return 0. +/** + * check_for_mailing_list - Search list of addresses for a mailing list + * @param adr List of addreses to search + * @param pfx Prefix string + * @param buf Buffer to store results + * @param buflen Buffer length + * @return 1 Mailing list found, 0 No list found + * + * Search for a mailing list in the list of addresses pointed to by adr. + * If one is found, print pfx and the name of the list into buf. */ static bool check_for_mailing_list(struct Address *adr, const char *pfx, char *buf, int buflen) { @@ -131,9 +138,14 @@ static bool first_mailing_list(char *buf, size_t buflen, struct Address *a) } /** - * Takes the color to embed, the buffer to manipulate and the buffer length as - * arguments. - * Returns the number of chars written. + * add_index_color - Insert a color marker into a string + * @param buf Buffer to store marker + * @param buflen Buffer length + * @param flags Flags, e.g. MUTT_FORMAT_INDEX + * @param color Color, e.g. MT_COLOR_MESSAGE + * @return Number of characters written + * + * The colors are stored as "magic" strings embedded in the text. */ static size_t add_index_color(char *buf, size_t buflen, enum FormatFlag flags, char color) { diff --git a/imap/command.c b/imap/command.c index d0e562b79..91924a922 100644 --- a/imap/command.c +++ b/imap/command.c @@ -74,8 +74,11 @@ static bool cmd_queue_full(struct ImapData *idata) return false; } -/* sets up a new command control block and adds it to the queue. - * Returns NULL if the pipeline is full. */ +/** + * cmd_new - Create and queue a new command control block + * @param idata IMAP data + * @return NULL if the pipeline is full + */ static struct ImapCommand *cmd_new(struct ImapData *idata) { struct ImapCommand *cmd = NULL; @@ -941,14 +944,23 @@ const char *imap_cmd_trailer(struct ImapData *idata) return s; } -/* imap_exec: execute a command, and wait for the response from the server. +/** + * imap_exec - Execute a command and wait for the response from the server + * @param idata IMAP data + * @param cmdstr Command to execute + * @param flags Flags (see below) + * @return + * * 0 on success + * * -1 on Failure + * * -2 on OK Failure + * * Also, handle untagged responses. + * * Flags: - * IMAP_CMD_FAIL_OK: the calling procedure can handle failure. This is used - * for checking for a mailbox on append and login - * IMAP_CMD_PASS: command contains a password. Suppress logging. - * IMAP_CMD_QUEUE: only queue command, do not execute. - * Return 0 on success, -1 on Failure, -2 on OK Failure + * * IMAP_CMD_FAIL_OK: the calling procedure can handle failure. + * This is used for checking for a mailbox on append and login + * * IMAP_CMD_PASS: command contains a password. Suppress logging. + * * IMAP_CMD_QUEUE: only queue command, do not execute. */ int imap_exec(struct ImapData *idata, const char *cmdstr, int flags) { diff --git a/imap/imap.c b/imap/imap.c index 670e3d549..9862a2273 100644 --- a/imap/imap.c +++ b/imap/imap.c @@ -981,16 +981,20 @@ static int imap_make_msg_set(struct ImapData *idata, struct Buffer *buf, return count; } -/* Prepares commands for all messages matching conditions (must be flushed - * with imap_exec) - * Params: - * idata: ImapData containing context containing header set - * pre, post: commands are of the form "%s %s %s %s", tag, - * pre, message set, post - * flag: enum of flag type on which to filter - * changed: include only changed messages in message set - * invert: invert sense of flag, eg MUTT_READ matches unread messages - * Returns: number of matched messages, or -1 on failure */ +/** + * imap_exec_msgset - Prepare commands for all messages matching conditions + * @param idata ImapData containing context containing header set + * @param pre prefix commands + * @param post postfix commands + * @param flag flag type on which to filter, e.g. MUTT_REPLIED + * @param changed include only changed messages in message set + * @param invert invert sense of flag, eg MUTT_READ matches unread messages + * @return number of matched messages, or -1 on failure + * + * pre/post: commands are of the form "%s %s %s %s", tag, pre, message set, post + * Prepares commands for all messages matching conditions + * (must be flushed with imap_exec) + */ int imap_exec_msgset(struct ImapData *idata, const char *pre, const char *post, int flag, int changed, int invert) { @@ -1434,13 +1438,15 @@ int imap_close_mailbox(struct Context *ctx) return 0; } -/* use the NOOP or IDLE command to poll for new mail - * - * return values: - * MUTT_REOPENED mailbox has been externally modified - * MUTT_NEW_MAIL new mail has arrived! - * 0 no change - * -1 error +/** + * imap_check_mailbox - use the NOOP or IDLE command to poll for new mail + * @param ctx Context + * @param force Don't wait + * @return + * * MUTT_REOPENED mailbox has been externally modified + * * MUTT_NEW_MAIL new mail has arrived! + * * 0 no change + * * -1 error */ int imap_check_mailbox(struct Context *ctx, int force) { @@ -1965,8 +1971,16 @@ fail: return -1; } -/* trim dest to the length of the longest prefix it shares with src, - * returning the length of the trimmed string */ +/** + * longest_common_prefix - Find longest prefix common to two strings + * @param dest Destination buffer + * @param src Source buffer + * @param start Starting offset into string + * @param dlen Destination buffer length + * @return Length of the common string + * + * Trim dest to the length of the longest prefix it shares with src. + */ static size_t longest_common_prefix(char *dest, const char *src, size_t start, size_t dlen) { size_t pos = start; diff --git a/imap/imap_private.h b/imap/imap_private.h index 056713e93..4d8e2a8ce 100644 --- a/imap/imap_private.h +++ b/imap/imap_private.h @@ -113,17 +113,17 @@ enum ImapCaps IMAP4 = 0, IMAP4REV1, STATUS, - ACL, /* RFC 2086: IMAP4 ACL extension */ - NAMESPACE, /* RFC 2342: IMAP4 Namespace */ - ACRAM_MD5, /* RFC 2195: CRAM-MD5 authentication */ - AGSSAPI, /* RFC 1731: GSSAPI authentication */ - AUTH_ANON, /* AUTH=ANONYMOUS */ - STARTTLS, /* RFC 2595: STARTTLS */ - LOGINDISABLED, /* LOGINDISABLED */ - IDLE, /* RFC 2177: IDLE */ - SASL_IR, /* SASL initial response draft */ - ENABLE, /* RFC 5161 */ - X_GM_EXT1, /* https://developers.google.com/gmail/imap/imap-extensions */ + ACL, /**< RFC 2086: IMAP4 ACL extension */ + NAMESPACE, /**< RFC 2342: IMAP4 Namespace */ + ACRAM_MD5, /**< RFC 2195: CRAM-MD5 authentication */ + AGSSAPI, /**< RFC 1731: GSSAPI authentication */ + AUTH_ANON, /**< AUTH=ANONYMOUS */ + STARTTLS, /**< RFC 2595: STARTTLS */ + LOGINDISABLED, /**< LOGINDISABLED */ + IDLE, /**< RFC 2177: IDLE */ + SASL_IR, /**< SASL initial response draft */ + ENABLE, /**< RFC 5161 */ + X_GM_EXT1, /**< https://developers.google.com/gmail/imap/imap-extensions */ CAPMAX }; diff --git a/imap/message.c b/imap/message.c index af117c658..918db30d7 100644 --- a/imap/message.c +++ b/imap/message.c @@ -215,12 +215,14 @@ static char *msg_parse_flags(struct ImapHeader *h, char *s) return s; } -/* msg_parse_fetch: handle headers returned from header fetch. - * Returns: - * 0 on success - * -1 if the string is corrupted - * -2 if the fetch contains a body or header lines - * that still need to be parsed. +/** + * msg_parse_fetch - handle headers returned from header fetch + * @param h IMAP Header + * @param s Command string + * @return + * * 0 Success + * * -1 String is corrupted + * * -2 Fetch contains a body or header lines that still need to be parsed */ static int msg_parse_fetch(struct ImapHeader *h, char *s) { diff --git a/imap/util.c b/imap/util.c index 5922d168e..9d38b5a75 100644 --- a/imap/util.c +++ b/imap/util.c @@ -54,15 +54,21 @@ #include "hcache/hcache.h" #endif -/* -- public functions -- */ - -/* imap_expand_path: IMAP implementation of mutt_expand_path. Rewrite - * an IMAP path in canonical and absolute form. - * Inputs: a buffer containing an IMAP path, and the number of bytes in - * that buffer. - * Outputs: The buffer is rewritten in place with the canonical IMAP path. - * Returns 0 on success, or -1 if imap_parse_path chokes or url_ciss_tostring - * fails, which it might if there isn't enough room in the buffer. */ +/** + * imap_expand_path - Canonicalise an IMAP path + * @param path Buffer containing path + * @param len Buffer length + * @return + * * 0 on success + * * -1 on error + * + * IMAP implementation of mutt_expand_path. Rewrite an IMAP path in canonical + * and absolute form. The buffer is rewritten in place with the canonical IMAP + * path. + * + * Function can fail if imap_parse_path() or url_ciss_tostring() fail, + * of if the buffer isn't large enough. + */ int imap_expand_path(char *path, size_t len) { struct ImapMbox mx; diff --git a/init.c b/init.c index cc8a05585..b851e26ee 100644 --- a/init.c +++ b/init.c @@ -2990,13 +2990,14 @@ static int parse_set(struct Buffer *tmp, struct Buffer *s, unsigned long data, * and avoid cyclic sourcing */ static struct List *MuttrcStack; -/* Use POSIX functions to convert a path to absolute, relatively to another path - * Args: - * - path: instance containing the relative path to the file we want the absolute - * path of. Should be at least of PATH_MAX length, will contain the full result. - * - reference: path to a file which directory will be set as reference for setting - * up the absolute path. - * Returns: true (1) on success, false (0) otherwise. +/** + * to_absolute_path - Convert relative filepath to an absolute path + * @param path Relative path + * @param reference Absolute path that \a path is relative to + * @return true on success, false otherwise + * + * Use POSIX functions to convert a path to absolute, relatively to another path + * @note \a path should be at least of PATH_MAX length */ static int to_absolute_path(char *path, const char *reference) { @@ -3033,8 +3034,12 @@ static int to_absolute_path(char *path, const char *reference) #define MAXERRS 128 -/* reads the specified initialization file. - * Returns negative if mutt should pause to let the user know... */ +/** + * source_rc - Read an initialization file + * @param rcfile_path Path to initialization file + * @param err Buffer for error messages + * @return <0 if mutt should pause to let the user know + */ static int source_rc(const char *rcfile_path, struct Buffer *err) { FILE *f = NULL; diff --git a/init.h b/init.h index b09addc3b..cbed325b1 100644 --- a/init.h +++ b/init.h @@ -45,22 +45,22 @@ struct Buffer; #ifndef _MAKEDOC /* flags to parse_set() */ -#define MUTT_SET_INV (1 << 0) /* default is to invert all vars */ -#define MUTT_SET_UNSET (1 << 1) /* default is to unset all vars */ -#define MUTT_SET_RESET (1 << 2) /* default is to reset all vars to default */ +#define MUTT_SET_INV (1 << 0) /**< default is to invert all vars */ +#define MUTT_SET_UNSET (1 << 1) /**< default is to unset all vars */ +#define MUTT_SET_RESET (1 << 2) /**< default is to reset all vars to default */ /* forced redraw/resort types + other flags */ #define R_NONE 0 -#define R_INDEX (1 << 0) /* redraw the index menu (MENU_MAIN) */ -#define R_PAGER (1 << 1) /* redraw the pager menu */ -#define R_PAGER_FLOW (1 << 2) /* reflow line_info and redraw the pager menu */ -#define R_RESORT (1 << 3) /* resort the mailbox */ -#define R_RESORT_SUB (1 << 4) /* resort subthreads */ -#define R_RESORT_INIT (1 << 5) /* resort from scratch */ -#define R_TREE (1 << 6) /* redraw the thread tree */ -#define R_REFLOW (1 << 7) /* reflow window layout and full redraw */ -#define R_SIDEBAR (1 << 8) /* redraw the sidebar */ -#define R_MENU (1 << 9) /* redraw all menus */ +#define R_INDEX (1 << 0) /**< redraw the index menu (MENU_MAIN) */ +#define R_PAGER (1 << 1) /**< redraw the pager menu */ +#define R_PAGER_FLOW (1 << 2) /**< reflow line_info and redraw the pager menu */ +#define R_RESORT (1 << 3) /**< resort the mailbox */ +#define R_RESORT_SUB (1 << 4) /**< resort subthreads */ +#define R_RESORT_INIT (1 << 5) /**< resort from scratch */ +#define R_TREE (1 << 6) /**< redraw the thread tree */ +#define R_REFLOW (1 << 7) /**< reflow window layout and full redraw */ +#define R_SIDEBAR (1 << 8) /**< redraw the sidebar */ +#define R_MENU (1 << 9) /**< redraw all menus */ #define R_BOTH (R_INDEX | R_PAGER) #define R_RESORT_BOTH (R_RESORT | R_RESORT_SUB) diff --git a/lib.c b/lib.c index a90279df8..95f72da00 100644 --- a/lib.c +++ b/lib.c @@ -930,10 +930,18 @@ void mutt_remove_trailing_ws(char *s) *p = 0; } -/* +/** + * mutt_concatn_path - Concatenate directory and filename + * @param dst Buffer for result + * @param dstlen Buffer length + * @param dir Directory + * @param dirlen Directory length + * @param fname Filename + * @param fnamelen Filename length + * @return NULL on error, pointer to \a dst on success + * * Write the concatenated pathname (dir + "/" + fname) into dst. * The slash is omitted when dir or fname is of 0 length. - * Returns NULL on error or a pointer to dst otherwise. */ char *mutt_concatn_path(char *dst, size_t dstlen, const char *dir, size_t dirlen, const char *fname, size_t fnamelen) diff --git a/lib.h b/lib.h index 8515f75fe..8e424bdfd 100644 --- a/lib.h +++ b/lib.h @@ -120,8 +120,8 @@ void mutt_debug(int level, const char *fmt, ...); #define S_BKG 126 /* Flags for mutt_read_line() */ -#define MUTT_CONT (1 << 0) /* \-continuation */ -#define MUTT_EOL (1 << 1) /* don't strip \n/\r\n */ +#define MUTT_CONT (1 << 0) /**< \-continuation */ +#define MUTT_EOL (1 << 1) /**< don't strip `\n` / `\r\n` */ /* The actual library functions. */ diff --git a/mailbox.h b/mailbox.h index dab8d4539..828d4e2bc 100644 --- a/mailbox.h +++ b/mailbox.h @@ -26,28 +26,28 @@ struct Header; struct Context; /* flags for mutt_open_mailbox() */ -#define MUTT_NOSORT (1 << 0) /* do not sort the mailbox after opening it */ -#define MUTT_APPEND (1 << 1) /* open mailbox for appending messages */ -#define MUTT_READONLY (1 << 2) /* open in read-only mode */ -#define MUTT_QUIET (1 << 3) /* do not print any messages */ -#define MUTT_NEWFOLDER (1 << 4) /* create a new folder - same as MUTT_APPEND, but uses +#define MUTT_NOSORT (1 << 0) /**< do not sort the mailbox after opening it */ +#define MUTT_APPEND (1 << 1) /**< open mailbox for appending messages */ +#define MUTT_READONLY (1 << 2) /**< open in read-only mode */ +#define MUTT_QUIET (1 << 3) /**< do not print any messages */ +#define MUTT_NEWFOLDER (1 << 4) /**< create a new folder - same as MUTT_APPEND, but uses * safe_fopen() with mode "w" for mbox-style folders. * This will truncate an existing file. */ -#define MUTT_PEEK (1 << 5) /* revert atime back after taking a look (if applicable) */ -#define MUTT_APPENDNEW (1 << 6) /* set in mx_open_mailbox_append if the mailbox doesn't +#define MUTT_PEEK (1 << 5) /**< revert atime back after taking a look (if applicable) */ +#define MUTT_APPENDNEW (1 << 6) /**< set in mx_open_mailbox_append if the mailbox doesn't * exist. used by maildir/mh to create the mailbox. */ /* mx_open_new_message() */ -#define MUTT_ADD_FROM (1 << 0) /* add a From_ line */ -#define MUTT_SET_DRAFT (1 << 1) /* set the message draft flag */ +#define MUTT_ADD_FROM (1 << 0) /**< add a From_ line */ +#define MUTT_SET_DRAFT (1 << 1) /**< set the message draft flag */ /* return values from mx_check_mailbox() */ enum MxCheckReturns { - MUTT_NEW_MAIL = 1, /* new mail received in mailbox */ - MUTT_LOCKED, /* couldn't lock the mailbox */ - MUTT_REOPENED, /* mailbox was reopened */ - MUTT_FLAGS /* nondestructive flags change (IMAP) */ + MUTT_NEW_MAIL = 1, /**< new mail received in mailbox */ + MUTT_LOCKED, /**< couldn't lock the mailbox */ + MUTT_REOPENED, /**< mailbox was reopened */ + MUTT_FLAGS /**< nondestructive flags change (IMAP) */ }; struct Message diff --git a/mbox.c b/mbox.c index 8bdfd833c..621551700 100644 --- a/mbox.c +++ b/mbox.c @@ -828,14 +828,16 @@ static int reopen_mailbox(struct Context *ctx, int *index_hint) return ((ctx->changed || msg_mod) ? MUTT_REOPENED : MUTT_NEW_MAIL); } -/* check to see if the mailbox has changed on disk. - * - * return values: - * MUTT_REOPENED mailbox has been reopened - * MUTT_NEW_MAIL new mail has arrived! - * MUTT_LOCKED couldn't lock the file - * 0 no change - * -1 error +/** + * mbox_check_mailbox - Has mailbox changed on disk + * @param[in] ctx Context + * @param[out] index_hint Keep track of current index selection + * @return + * * #MUTT_REOPENED Mailbox has been reopened + * * #MUTT_NEW_MAIL New mail has arrived + * * #MUTT_LOCKED Couldn't lock the file + * * 0 No change + * * -1 Error */ static int mbox_check_mailbox(struct Context *ctx, int *index_hint) { @@ -942,9 +944,11 @@ static int mbox_check_mailbox(struct Context *ctx, int *index_hint) return -1; } -/* - * Returns 1 if the mailbox has at least 1 new messages (not old) - * otherwise returns 0. +/** + * 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 */ static bool mbox_has_new(struct Context *ctx) { @@ -1354,11 +1358,13 @@ bail: /* Come here in case of disaster */ return rc; } -/* - * Returns: - * 1 if the mailbox is not empty - * 0 if the mailbox is empty - * -1 on error +/** + * mbox_check_empty - Is the mailbox empty + * @param path Path to mailbox + * @return + * * 1 mailbox is not empty + * * 0 mailbox is empty + * * -1 on error */ int mbox_check_empty(const char *path) { diff --git a/mh.c b/mh.c index f7d4435e4..b110df2c8 100644 --- a/mh.c +++ b/mh.c @@ -220,10 +220,13 @@ static inline mode_t mh_umask(struct Context *ctx) return 0777 & ~st.st_mode; } -/* - * Returns 1 if the .mh_sequences last modification time is more recent than the last visit to this mailbox - * Returns 0 if the modification time is older - * Returns -1 on error +/** + * mh_sequences_changed - Has the mailbox changed + * @param b Mailbox + * @return + * * 1 mh_sequences last modification time is more recent than the last visit to this mailbox + * * 0 modification time is older + * * -1 Error */ static int mh_sequences_changed(struct Buffy *b) { @@ -236,10 +239,14 @@ static int mh_sequences_changed(struct Buffy *b) return -1; } -/* - * Returns 1 if the modification time on the message file is older than the last visit to this mailbox - * Returns 0 if the modtime is newer - * Returns -1 on error +/** + * mh_already_notified - Has the message changed + * @param b Mailbox + * @param msgno Message number + * @return + * * 1 Modification time on the message file is older than the last visit to this mailbox + * * 0 Modification time on the message file is newer + * * -1 Error */ static int mh_already_notified(struct Buffy *b, int msgno) { @@ -252,7 +259,12 @@ static int mh_already_notified(struct Buffy *b, int msgno) return -1; } -/* Ignore the garbage files. A valid MH message consists of only +/** + * mh_valid_message - Is this a valid MH message filename + * @param s Pathname to examine + * @return true name is valid, false name is invalid + * + * Ignore the garbage files. A valid MH message consists of only * digits. Deleted message get moved to a filename with a comma before * it. */ @@ -266,9 +278,11 @@ static bool mh_valid_message(const char *s) return true; } -/* Checks new mail for a mh mailbox. - * check_stats: if true, also count total, new, and flagged messages. - * Returns 1 if the mailbox has new mail. +/** + * mh_buffy - Check for new mail for a mh mailbox + * @param mailbox Mailbox to check + * @param check_stats Also count total, new, and flagged messages + * @returns true if the mailbox has new mail */ int mh_buffy(struct Buffy *mailbox, int check_stats) { @@ -2446,11 +2460,13 @@ FILE *maildir_open_find_message(const char *folder, const char *msg, char **newn } -/* - * Returns: - * 1 if there are no messages in the mailbox - * 0 if there are messages in the mailbox - * -1 on error +/** + * maildir_check_empty - Is the mailbox empty + * @param path Mailbox to check + * @return + * * 1 Mailbox is empty + * * 0 Mailbox contains mail + * * -1 Error */ int maildir_check_empty(const char *path) { @@ -2486,11 +2502,13 @@ int maildir_check_empty(const char *path) return r; } -/* - * Returns: - * 1 if there are no messages in the mailbox - * 0 if there are messages in the mailbox - * -1 on error +/** + * mh_check_empty - Is mailbox empty + * @param path Mailbox to check + * @return + * * 1 Mailbox is empty + * * 0 Mailbox contains mail + * * -1 Error */ int mh_check_empty(const char *path) { diff --git a/mutt.h b/mutt.h index 9ff92954b..68c31b996 100644 --- a/mutt.h +++ b/mutt.h @@ -58,22 +58,22 @@ struct State; #endif /* flags for mutt_enter_string() */ -#define MUTT_ALIAS 1 /* do alias "completion" by calling up the alias-menu */ -#define MUTT_FILE (1 << 1) /* do file completion */ -#define MUTT_EFILE (1 << 2) /* do file completion, plus incoming folders */ -#define MUTT_CMD (1 << 3) /* do completion on previous word */ -#define MUTT_PASS (1 << 4) /* password mode (no echo) */ -#define MUTT_CLEAR (1 << 5) /* clear input if printable character is pressed */ -#define MUTT_COMMAND (1 << 6) /* do command completion */ -#define MUTT_PATTERN (1 << 7) /* pattern mode - only used for history classes */ -#define MUTT_LABEL (1 << 8) /* do label completion */ +#define MUTT_ALIAS (1 << 0) /**< do alias "completion" by calling up the alias-menu */ +#define MUTT_FILE (1 << 1) /**< do file completion */ +#define MUTT_EFILE (1 << 2) /**< do file completion, plus incoming folders */ +#define MUTT_CMD (1 << 3) /**< do completion on previous word */ +#define MUTT_PASS (1 << 4) /**< password mode (no echo) */ +#define MUTT_CLEAR (1 << 5) /**< clear input if printable character is pressed */ +#define MUTT_COMMAND (1 << 6) /**< do command completion */ +#define MUTT_PATTERN (1 << 7) /**< pattern mode - only used for history classes */ +#define MUTT_LABEL (1 << 8) /**< do label completion */ #ifdef USE_NOTMUCH -#define MUTT_NM_QUERY (1 << 9) /* Notmuch query mode. */ -#define MUTT_NM_TAG (1 << 10) /* Notmuch tag +/- mode. */ +#define MUTT_NM_QUERY (1 << 9) /**< Notmuch query mode. */ +#define MUTT_NM_TAG (1 << 10) /**< Notmuch tag +/- mode. */ #endif /* flags for _mutt_system() */ -#define MUTT_DETACH_PROCESS 1 /* detach subprocess from group */ +#define MUTT_DETACH_PROCESS 1 /**< detach subprocess from group */ /* types for mutt_add_hook() */ #define MUTT_FOLDERHOOK (1 << 0) @@ -274,9 +274,9 @@ enum QuadOptionVars #define SENDMAILX (1 << 6) #define SENDKEY (1 << 7) #define SENDRESEND (1 << 8) -#define SENDPOSTPONEDFCC (1 << 9) /* used by mutt_get_postponed() to signal that the x-mutt-fcc header field was present */ -#define SENDNOFREEHEADER (1 << 10) /* Used by the -E flag */ -#define SENDDRAFTFILE (1 << 11) /* Used by the -H flag */ +#define SENDPOSTPONEDFCC (1 << 9) /**< used by mutt_get_postponed() to signal that the x-mutt-fcc header field was present */ +#define SENDNOFREEHEADER (1 << 10) /**< Used by the -E flag */ +#define SENDDRAFTFILE (1 << 11) /**< Used by the -H flag */ #define SENDNEWS (1 << 12) /* flags for mutt_compose_menu() */ @@ -293,10 +293,10 @@ enum QuadOptionVars #define MUTT_NOSPAM 2 /* flags for keywords headers */ -#define MUTT_X_LABEL (1 << 0) /* introduced to mutt in 2000 */ -#define MUTT_X_KEYWORDS (1 << 1) /* used in c-client, dovecot */ -#define MUTT_X_MOZILLA_KEYS (1 << 2) /* tbird */ -#define MUTT_KEYWORDS (1 << 3) /* rfc2822 */ +#define MUTT_X_LABEL (1 << 0) /**< introduced to mutt in 2000 */ +#define MUTT_X_KEYWORDS (1 << 1) /**< used in c-client, dovecot */ +#define MUTT_X_MOZILLA_KEYS (1 << 2) /**< tbird */ +#define MUTT_KEYWORDS (1 << 3) /**< rfc2822 */ void mutt_free_list(struct List **list); void mutt_free_rx_list(struct RxList **list); @@ -322,14 +322,14 @@ void mutt_init(int skip_sys_rc, struct List *commands); #define MUTT_FULL_MSG (1 << 0) /* enable body and header matching */ /* flags for the State struct */ -#define MUTT_DISPLAY (1 << 0) /* output is displayed to the user */ -#define MUTT_VERIFY (1 << 1) /* perform signature verification */ -#define MUTT_PENDINGPREFIX (1 << 2) /* prefix to write, but character must follow */ -#define MUTT_WEED (1 << 3) /* weed headers even when not in display mode */ -#define MUTT_CHARCONV (1 << 4) /* Do character set conversions */ -#define MUTT_PRINTING (1 << 5) /* are we printing? - MUTT_DISPLAY "light" */ -#define MUTT_REPLYING (1 << 6) /* are we replying? */ -#define MUTT_FIRSTDONE (1 << 7) /* the first attachment has been done */ +#define MUTT_DISPLAY (1 << 0) /**< output is displayed to the user */ +#define MUTT_VERIFY (1 << 1) /**< perform signature verification */ +#define MUTT_PENDINGPREFIX (1 << 2) /**< prefix to write, but character must follow */ +#define MUTT_WEED (1 << 3) /**< weed headers even when not in display mode */ +#define MUTT_CHARCONV (1 << 4) /**< Do character set conversions */ +#define MUTT_PRINTING (1 << 5) /**< are we printing? - MUTT_DISPLAY "light" */ +#define MUTT_REPLYING (1 << 6) /**< are we replying? */ +#define MUTT_FIRSTDONE (1 << 7) /**< the first attachment has been done */ #define state_set_prefix(s) ((s)->flags |= MUTT_PENDINGPREFIX) #define state_reset_prefix(s) ((s)->flags &= ~MUTT_PENDINGPREFIX) diff --git a/mutt_curses.h b/mutt_curses.h index 7d0bcda48..85b13dc51 100644 --- a/mutt_curses.h +++ b/mutt_curses.h @@ -190,8 +190,8 @@ struct ColorLine struct ColorLine *next; }; -#define MUTT_PROGRESS_SIZE (1 << 0) /* traffic-based progress */ -#define MUTT_PROGRESS_MSG (1 << 1) /* message-based progress */ +#define MUTT_PROGRESS_SIZE (1 << 0) /**< traffic-based progress */ +#define MUTT_PROGRESS_MSG (1 << 1) /**< message-based progress */ struct Progress { diff --git a/mutt_options.h b/mutt_options.h index e56ba0f89..d49c2f969 100644 --- a/mutt_options.h +++ b/mutt_options.h @@ -23,18 +23,18 @@ struct Buffer; #define DT_MASK 0x0f -#define DT_BOOL 1 /* boolean option */ -#define DT_NUM 2 /* a number */ -#define DT_STR 3 /* a string */ -#define DT_PATH 4 /* a pathname */ -#define DT_QUAD 5 /* quad-option (yes/no/ask-yes/ask-no) */ -#define DT_SORT 6 /* sorting methods */ -#define DT_RX 7 /* regular expressions */ -#define DT_MAGIC 8 /* mailbox type */ -#define DT_SYN 9 /* synonym for another variable */ -#define DT_ADDR 10 /* e-mail address */ -#define DT_MBCHARTBL 11 /* multibyte char table */ -#define DT_HCACHE 12 /* header cache backend */ +#define DT_BOOL 1 /**< boolean option */ +#define DT_NUM 2 /**< a number */ +#define DT_STR 3 /**< a string */ +#define DT_PATH 4 /**< a pathname */ +#define DT_QUAD 5 /**< quad-option (yes/no/ask-yes/ask-no) */ +#define DT_SORT 6 /**< sorting methods */ +#define DT_RX 7 /**< regular expressions */ +#define DT_MAGIC 8 /**< mailbox type */ +#define DT_SYN 9 /**< synonym for another variable */ +#define DT_ADDR 10 /**< e-mail address */ +#define DT_MBCHARTBL 11 /**< multibyte char table */ +#define DT_HCACHE 12 /**< header cache backend */ #define DTYPE(x) ((x) &DT_MASK) diff --git a/mutt_ssl_gnutls.c b/mutt_ssl_gnutls.c index f0958b6d0..62ed42108 100644 --- a/mutt_ssl_gnutls.c +++ b/mutt_ssl_gnutls.c @@ -508,8 +508,14 @@ static char *tls_make_date(time_t t, char *s, size_t len) return s; } -/* - * Returns 0 on failure, nonzero on success. +/** + * tls_check_one_certificate - + * @param certdata List of GnuTLS certificates + * @param certstat GnuTLS certificate status + * @param hostname Hostname + * @param idx Index into certificate list + * @param len Length of certificate list + * @return 0 on failure, nonzero on success */ static int tls_check_one_certificate(const gnutls_datum_t *certdata, gnutls_certificate_status_t certstat, diff --git a/muttlib.c b/muttlib.c index ad5542dfe..6700525d7 100644 --- a/muttlib.c +++ b/muttlib.c @@ -2132,13 +2132,19 @@ bool mutt_match_rx_list(const char *s, struct RxList *l) return false; } -/* Match a string against the patterns defined by the 'spam' command and output +/** + * mutt_match_spam_list - Does a string match a spam pattern + * @param s String to check + * @param l List of spam patterns + * @param text Buffer to save match + * @param textsize Buffer length + * @return true if \a s matches a pattern in \a l, false otherwise + * + * Match a string against the patterns defined by the 'spam' command and output * the expanded format into `text` when there is a match. If textsize<=0, the * match is performed but the format is not expanded and no assumptions are made * about the value of `text` so it may be NULL. - * - * Returns true if the argument `s` matches a pattern in the spam list, otherwise - * false. */ + */ bool mutt_match_spam_list(const char *s, struct ReplaceList *l, char *text, int textsize) { static regmatch_t *pmatch = NULL; @@ -2220,10 +2226,14 @@ void mutt_encode_path(char *dest, size_t dlen, const char *src) FREE(&p); } -/* - * Process an XDG environment variable or its fallback. +/** + * mutt_set_xdg_path - Find an XDG path or its fallback + * @param type Type of XDG variable, e.g. #XDG_CONFIG_HOME + * @param buf Buffer to save path + * @param bufsize Buffer length + * @return 1 if an entry was found that actually exists on disk and 0 otherwise * - * Return 1 if an entry was found that actually exists on disk and 0 otherwise. + * Process an XDG environment variable or its fallback. */ int mutt_set_xdg_path(enum XdgType type, char *buf, size_t bufsize) { diff --git a/mx.c b/mx.c index aac41e55d..20e0bfee2 100644 --- a/mx.c +++ b/mx.c @@ -250,16 +250,13 @@ static void mx_unlink_empty(const char *path) close(fd); } -/* try to figure out what type of mailbox ``path'' is - * - * return values: - * MUTT_* mailbox type - * 0 not a mailbox - * -1 error - */ - #ifdef USE_IMAP +/** + * mx_is_imap - Is this an IMAP mailbox + * @param p Mailbox string to test + * return boolean + */ bool mx_is_imap(const char *p) { enum UrlScheme scheme; @@ -280,6 +277,11 @@ bool mx_is_imap(const char *p) #endif #ifdef USE_POP +/** + * mx_is_pop - Is this a POP mailbox + * @param p Mailbox string to test + * return boolean + */ bool mx_is_pop(const char *p) { enum UrlScheme scheme; @@ -296,6 +298,11 @@ bool mx_is_pop(const char *p) #endif #ifdef USE_NNTP +/** + * mx_is_nntp - Is this an NNTP mailbox + * @param p Mailbox string to test + * return boolean + */ bool mx_is_nntp(const char *p) { enum UrlScheme scheme; @@ -312,6 +319,11 @@ bool mx_is_nntp(const char *p) #endif #ifdef USE_NOTMUCH +/** + * mx_is_notmuch - Is this a notmuch mailbox + * @param p Mailbox string to test + * return boolean + */ bool mx_is_notmuch(const char *p) { enum UrlScheme scheme; @@ -327,6 +339,13 @@ bool mx_is_notmuch(const char *p) } #endif +/** + * mx_get_magic - Identify the type of mailbox + * @param path Mailbox path to test + * return + * * -1 Error, can't identify mailbox + * * >0 Success, e.g. #MUTT_IMAP + */ int mx_get_magic(const char *path) { struct stat st; @@ -1081,11 +1100,11 @@ void mx_update_tables(struct Context *ctx, int committing) } -/* save changes to mailbox - * - * return values: - * 0 success - * -1 error +/** + * mx_sync_mailbox - Save changes to mailbox + * @param[in] ctx Context + * @param[out] index_hint Currently selected mailbox + * @return 0 on success, -1 on error */ int mx_sync_mailbox(struct Context *ctx, int *index_hint) { @@ -1433,11 +1452,13 @@ void mx_update_context(struct Context *ctx, int new_messages) } } -/* - * Return: - * 1 if the specified mailbox contains 0 messages. - * 0 if the mailbox contains messages - * -1 on error +/** + * mx_check_empty - Is the mailbox empty + * @param path Mailbox to check + * @return + * * 1 Mailbox is empty + * * 0 Mailbox contains mail + * * -1 Error */ int mx_check_empty(const char *path) { diff --git a/ncrypt/crypt_gpgme.c b/ncrypt/crypt_gpgme.c index 22eb01e1a..60c5c7f4c 100644 --- a/ncrypt/crypt_gpgme.c +++ b/ncrypt/crypt_gpgme.c @@ -219,8 +219,12 @@ static const char *crypt_fpr(struct CryptKeyInfo *k) return s; } -/* Returns the fingerprint if available, otherwise - * returns the long keyid. +/** + * crypt_fpr_or_lkeyid - Find the fingerprint of a key + * @param k Key to examine + * @return + * * fingerprint if available + * * otherwise returns the long keyid */ static const char *crypt_fpr_or_lkeyid(struct CryptKeyInfo *k) { @@ -2113,11 +2117,17 @@ err_ctx: return rc; } -/* Check that 'b' is a complete line containing 'a' followed by either LF or CRLF. +/** + * line_compare - Compare two strings ignore line endings + * @param a String a + * @param n Maximum length to compare + * @param b String b + * @return + * * 0 Strings match + * * -1 Strings differ * - * returns: - * 0 if the is a match - * -1 otherwise + * Check that \a b is a complete line containing \a a followed by either LF or + * CRLF. */ static int line_compare(const char *a, size_t n, const char *b) { diff --git a/nntp.c b/nntp.c index 727ad221f..5540c3a41 100644 --- a/nntp.c +++ b/nntp.c @@ -904,8 +904,17 @@ static int fetch_description(char *line, void *data) return 0; } -/* Fetch newsgroups descriptions. - * Returns the same code as nntp_fetch_lines() */ +/** + * get_description - Fetch newsgroups descriptions + * @param nntp_data NNTP data + * @param wildmat String to match + * @param msg Progress message + * @return + * * 0 Success + * * 1 Bad response (answer in query buffer) + * * -1 Connection lost + * * -2 Error + */ static int get_description(struct NntpData *nntp_data, char *wildmat, char *msg) { struct NntpServer *nserv = NULL; diff --git a/options.h b/options.h index 0de0c6a13..4dc8e0f05 100644 --- a/options.h +++ b/options.h @@ -113,17 +113,17 @@ enum GlobalBool OPTMAILDIRCHECKCUR, OPTMARKERS, OPTMARKOLD, - OPTMENUSCROLL, /* scroll menu instead of implicit next-page */ - OPTMENUMOVEOFF, /* allow menu to scroll past last entry */ + OPTMENUSCROLL, /**< scroll menu instead of implicit next-page */ + OPTMENUMOVEOFF, /**< allow menu to scroll past last entry */ #if defined(USE_IMAP) || defined(USE_POP) OPTMESSAGECACHECLEAN, #endif - OPTMETAKEY, /* interpret ALT-x as ESC-x */ + OPTMETAKEY, /**< interpret ALT-x as ESC-x */ OPTMETOO, OPTMHPURGE, OPTMIMEFORWDECODE, #ifdef USE_NNTP - OPTMIMESUBJECT, /* encode subject line with RFC2047 */ + OPTMIMESUBJECT, /**< encode subject line with RFC2047 */ #endif OPTNARROWTREE, OPTPAGERSTOP, @@ -189,7 +189,7 @@ enum GlobalBool OPTWEED, OPTWRAP, OPTWRAPSEARCH, - OPTWRITEBCC, /* write out a bcc header? */ + OPTWRITEBCC, /**< write out a bcc header? */ OPTXMAILER, OPTCRYPTUSEGPGME, @@ -236,35 +236,34 @@ enum GlobalBool /* pseudo options */ - OPTAUXSORT, /* (pseudo) using auxiliary sort function */ - OPTFORCEREFRESH, /* (pseudo) refresh even during macros */ - OPTLOCALES, /* (pseudo) set if user has valid locale definition */ - OPTNOCURSES, /* (pseudo) when sending in batch mode */ - OPTSEARCHREVERSE, /* (pseudo) used by ci_search_command */ - OPTMSGERR, /* (pseudo) used by mutt_error/mutt_message */ - OPTSEARCHINVALID, /* (pseudo) used to invalidate the search pat */ - OPTSIGNALSBLOCKED, /* (pseudo) using by mutt_block_signals () */ - OPTSYSSIGNALSBLOCKED, /* (pseudo) using by mutt_block_signals_system () */ - OPTNEEDRESORT, /* (pseudo) used to force a re-sort */ - OPTRESORTINIT, /* (pseudo) used to force the next resort to be from scratch */ - OPTVIEWATTACH, /* (pseudo) signals that we are viewing attachments */ - OPTSORTSUBTHREADS, /* (pseudo) used when $sort_aux changes */ - OPTNEEDRESCORE, /* (pseudo) set when the `score' command is used */ - OPTATTACHMSG, /* (pseudo) used by attach-message */ - OPTHIDEREAD, /* (pseudo) whether or not hide read messages */ - OPTKEEPQUIET, /* (pseudo) shut up the message and refresh - * functions while we are executing an - * external program. - */ - OPTMENUCALLER, /* (pseudo) tell menu to give caller a take */ - OPTREDRAWTREE, /* (pseudo) redraw the thread tree */ - OPTPGPCHECKTRUST, /* (pseudo) used by pgp_select_key () */ - OPTDONTHANDLEPGPKEYS, /* (pseudo) used to extract PGP keys */ - OPTIGNOREMACROEVENTS, /* (pseudo) don't process macro/push/exec events while set */ + OPTAUXSORT, /**< (pseudo) using auxiliary sort function */ + OPTFORCEREFRESH, /**< (pseudo) refresh even during macros */ + OPTLOCALES, /**< (pseudo) set if user has valid locale definition */ + OPTNOCURSES, /**< (pseudo) when sending in batch mode */ + OPTSEARCHREVERSE, /**< (pseudo) used by ci_search_command */ + OPTMSGERR, /**< (pseudo) used by mutt_error/mutt_message */ + OPTSEARCHINVALID, /**< (pseudo) used to invalidate the search pat */ + OPTSIGNALSBLOCKED, /**< (pseudo) using by mutt_block_signals () */ + OPTSYSSIGNALSBLOCKED, /**< (pseudo) using by mutt_block_signals_system () */ + OPTNEEDRESORT, /**< (pseudo) used to force a re-sort */ + OPTRESORTINIT, /**< (pseudo) used to force the next resort to be from scratch */ + OPTVIEWATTACH, /**< (pseudo) signals that we are viewing attachments */ + OPTSORTSUBTHREADS, /**< (pseudo) used when $sort_aux changes */ + OPTNEEDRESCORE, /**< (pseudo) set when the `score' command is used */ + OPTATTACHMSG, /**< (pseudo) used by attach-message */ + OPTHIDEREAD, /**< (pseudo) whether or not hide read messages */ + OPTKEEPQUIET, /**< (pseudo) shut up the message and refresh + * functions while we are executing an + * external program. */ + OPTMENUCALLER, /**< (pseudo) tell menu to give caller a take */ + OPTREDRAWTREE, /**< (pseudo) redraw the thread tree */ + OPTPGPCHECKTRUST, /**< (pseudo) used by pgp_select_key () */ + OPTDONTHANDLEPGPKEYS, /**< (pseudo) used to extract PGP keys */ + OPTIGNOREMACROEVENTS, /**< (pseudo) don't process macro/push/exec events while set */ #ifdef USE_NNTP - OPTNEWS, /* (pseudo) used to change reader mode */ - OPTNEWSSEND, /* (pseudo) used to change behavior when posting */ + OPTNEWS, /**< (pseudo) used to change reader mode */ + OPTNEWSSEND, /**< (pseudo) used to change behavior when posting */ #endif #ifdef USE_NOTMUCH OPTVIRTSPOOLFILE, diff --git a/pager.c b/pager.c index 328c5dc15..c78eebc16 100644 --- a/pager.c +++ b/pager.c @@ -1357,21 +1357,33 @@ static int format_line(struct Line **line_info, int n, unsigned char *buf, int f return ch; } -/* - * Args: - * flags MUTT_SHOWFLAT, show characters (used for displaying help) - * MUTT_SHOWCOLOR, show characters in color - * otherwise don't show characters - * MUTT_HIDE, don't show quoted text - * MUTT_SEARCH, resolve search patterns - * MUTT_TYPES, compute line's type - * MUTT_PAGER_NSKIP, keeps leading whitespace - * MUTT_PAGER_MARKER, eventually show markers +/** + * display_line - Print a line on screen + * @param f File to read from + * @param last_pos Offset into file + * @param line_info Line attributes + * @param n Line number + * @param last Last line + * @param max Maximum number of lines + * @param flags See below + * @param quote_list Email quoting style + * @param q_level Level of quoting + * @param force_redraw Force a repaint + * @param search_re Regex to highlight + * @param pager_window Window to draw into + * @return + * * -1 EOF was reached + * * 0 normal exit, line was not displayed + * * >0 normal exit, line was displayed * - * Return values: - * -1 EOF was reached - * 0 normal exit, line was not displayed - * >0 normal exit, line was displayed + * flags: + * * #MUTT_SHOWFLAT, show characters (used for displaying help) + * * #MUTT_SHOWCOLOR, show characters in color otherwise don't show characters + * * #MUTT_HIDE, don't show quoted text + * * #MUTT_SEARCH, resolve search patterns + * * #MUTT_TYPES, compute line's type + * * #MUTT_PAGER_NSKIP, keeps leading whitespace + * * #MUTT_PAGER_MARKER, eventually show markers */ static int display_line(FILE *f, LOFF_T *last_pos, struct Line **line_info, int n, int *last, int *max, int flags, diff --git a/pager.h b/pager.h index 7e87e7ccb..3d6326fe3 100644 --- a/pager.h +++ b/pager.h @@ -32,12 +32,12 @@ struct Menu; #define MUTT_SHOW (MUTT_SHOWCOLOR | MUTT_SHOWFLAT) /* exported flags for mutt_(do_)?pager */ -#define MUTT_PAGER_NSKIP (1 << 5) /* preserve whitespace with smartwrap */ -#define MUTT_PAGER_MARKER (1 << 6) /* use markers if option is set */ -#define MUTT_PAGER_RETWINCH (1 << 7) /* need reformatting on SIGWINCH */ +#define MUTT_PAGER_NSKIP (1 << 5) /**< preserve whitespace with smartwrap */ +#define MUTT_PAGER_MARKER (1 << 6) /**< use markers if option is set */ +#define MUTT_PAGER_RETWINCH (1 << 7) /**< need reformatting on SIGWINCH */ #define MUTT_PAGER_MESSAGE (MUTT_SHOWCOLOR | MUTT_PAGER_MARKER) #define MUTT_PAGER_ATTACHMENT (1 << 8) -#define MUTT_PAGER_NOWRAP (1 << 9) /* format for term width, ignore $wrap */ +#define MUTT_PAGER_NOWRAP (1 << 9) /**< format for term width, ignore $wrap */ #define MUTT_DISPLAYFLAGS (MUTT_SHOW | MUTT_PAGER_NSKIP | MUTT_PAGER_MARKER) diff --git a/parse.c b/parse.c index 522a04eeb..d20251565 100644 --- a/parse.c +++ b/parse.c @@ -1367,23 +1367,18 @@ done: } -/* mutt_read_rfc822_header() -- parses a RFC822 header - * - * Args: - * - * f stream to read from - * - * hdr header structure of current message (optional). - * - * user_hdrs If set, store user headers. Used for recall-message and - * postpone modes. - * - * weed If this parameter is set and the user has activated the - * $weed option, honor the header weed list for user headers. - * Used for recall-message. +/** + * mutt_read_rfc822_header - parses an RFC822 header + * @param f Stream to read from + * @param hdr Header structure of current message (optional) + * @param user_hdrs If set, store user headers + * Used for recall-message and postpone modes + * @param weed If this parameter is set and the user has activated the + * $weed option, honor the header weed list for user headers. + * Used for recall-message + * @return newly allocated envelope structure * - * Returns: newly allocated envelope structure. You should free it by - * mutt_free_envelope() when envelope stay unneeded. + * Caller should free the Envelope using mutt_free_envelope(). */ struct Envelope *mutt_read_rfc822_header(FILE *f, struct Header *hdr, short user_hdrs, short weed) diff --git a/pop.c b/pop.c index 7f3eaf418..b7d4f7fa2 100644 --- a/pop.c +++ b/pop.c @@ -63,13 +63,15 @@ static int fetch_message(char *line, void *file) return 0; } -/* - * Read header - * returns: - * 0 on success - * -1 - connection lost, - * -2 - invalid command or execution error, - * -3 - error writing to tempfile +/** + * pop_read_header - Read header + * @param pop_data POP data + * @param h Email header + * @return + * * 0 Success + * * -1 Connection lost, + * * -2 Invalid command or execution error, + * * -3 Error writing to tempfile */ static int pop_read_header(struct PopData *pop_data, struct Header *h) { @@ -235,13 +237,14 @@ static header_cache_t *pop_hcache_open(struct PopData *pop_data, const char *pat } #endif -/* - * Read headers - * returns: - * 0 on success - * -1 - connection lost, - * -2 - invalid command or execution error, - * -3 - error writing to tempfile +/** + * pop_fetch_headers - Read headers + * @param ctx Context + * @return + * * 0 Success + * * -1 Connection lost, + * * -2 Invalid command or execution error, + * * -3 Error writing to tempfile */ static int pop_fetch_headers(struct Context *ctx) { diff --git a/pop_lib.c b/pop_lib.c index abf85f5a1..fa470b308 100644 --- a/pop_lib.c +++ b/pop_lib.c @@ -40,7 +40,14 @@ #include "mutt_ssl.h" #endif -/* given an POP mailbox name, return host, port, username and password */ +/** + * pop_parse_path - Parse a POP mailbox name + * @param path Path to parse + * @param acct Account to store details + * @return 0 success, -1 error + * + * Split a POP path into host, port, username and password + */ int pop_parse_path(const char *path, struct Account *acct) { struct CissUrl url; @@ -80,7 +87,11 @@ int pop_parse_path(const char *path, struct Account *acct) return 0; } -/* Copy error message to err_msg buffer */ +/** + * pop_error - Copy error message to err_msg buffer + * @param pop_data POP data + * @param msg Error message to save + */ static void pop_error(struct PopData *pop_data, char *msg) { char *t = NULL, *c = NULL, *c2 = NULL; @@ -100,7 +111,12 @@ static void pop_error(struct PopData *pop_data, char *msg) mutt_remove_trailing_ws(pop_data->err_msg); } -/* Parse CAPA output */ +/** + * fetch_capa - Parse CAPA output + * @param line List of capabilities + * @param data POP data + * @return 0 (always) + */ static int fetch_capa(char *line, void *data) { struct PopData *pop_data = (struct PopData *) data; @@ -128,7 +144,12 @@ static int fetch_capa(char *line, void *data) return 0; } -/* Fetch list of the authentication mechanisms */ +/** + * fetch_auth - Fetch list of the authentication mechanisms + * @param line List of authentication methods + * @param data POP data + * @return 0 (always) + */ static int fetch_auth(char *line, void *data) { struct PopData *pop_data = (struct PopData *) data; @@ -148,11 +169,14 @@ static int fetch_auth(char *line, void *data) return 0; } -/* - * Get capabilities - * 0 - successful, - * -1 - connection lost, - * -2 - execution error. +/** + * pop_capabilities - Get capabilities from a POP server + * @param pop_data POP data + * @param mode Initial capabilities + * @return + * * 0 Successful + * * -1 Connection lost + * * -2 Execution error */ static int pop_capabilities(struct PopData *pop_data, int mode) { @@ -226,11 +250,13 @@ static int pop_capabilities(struct PopData *pop_data, int mode) return 0; } -/* - * Open connection - * 0 - successful, - * -1 - connection lost, - * -2 - invalid response. +/** + * pop_connect - Open connection + * @param pop_data POP data + * @return + * * 0 Successful + * * -1 Connection lost + * * -2 Invalid response */ int pop_connect(struct PopData *pop_data) { @@ -259,12 +285,14 @@ int pop_connect(struct PopData *pop_data) return 0; } -/* - * Open connection and authenticate - * 0 - successful, - * -1 - connection lost, - * -2 - invalid command or execution error, - * -3 - authentication canceled. +/** + * pop_open_connection - Open connection and authenticate + * @param pop_data POP data + * @return + * * 0 Successful + * * -1 Connection lost + * * -2 Invalid command or execution error + * * -3 Authentication cancelled */ int pop_open_connection(struct PopData *pop_data) { @@ -384,7 +412,10 @@ err_conn: return -1; } -/* logout from POP server */ +/** + * pop_logout - logout from a POP server + * @param ctx Context + */ void pop_logout(struct Context *ctx) { int ret = 0; @@ -417,11 +448,16 @@ void pop_logout(struct Context *ctx) return; } -/* - * Send data from buffer and receive answer to the same buffer - * 0 - successful, - * -1 - connection lost, - * -2 - invalid command or execution error. +/** + * pop_query_d - Send data from buffer and receive answer to the same buffer + * @param pop_data POP data + * @param buf Buffer to send/store data + * @param buflen Buffer length + * @param msg Progress message + * @return + * * 0 Successful + * * -1 Connection lost + * * -2 Invalid command or execution error */ int pop_query_d(struct PopData *pop_data, char *buf, size_t buflen, char *msg) { @@ -459,7 +495,10 @@ int pop_query_d(struct PopData *pop_data, char *buf, size_t buflen, char *msg) return -2; } -/* +/** + * pop_fetch_data - Read Headers with callback function + * + * * This function calls funct(*line, *data) for each received line, * funct(NULL, *data) if rewind(*data) needs, exits when fail or done. * Returned codes: @@ -527,7 +566,12 @@ int pop_fetch_data(struct PopData *pop_data, char *query, struct Progress *progr return ret; } -/* find message with this UIDL and set refno */ +/** + * check_uidl - find message with this UIDL and set refno + * @param line String containing UIDL + * @param data POP data + * @return 0 on success, -1 on error + */ static int check_uidl(char *line, void *data) { unsigned int index; @@ -554,7 +598,11 @@ static int check_uidl(char *line, void *data) return 0; } -/* reconnect and verify indexes if connection was lost */ +/** + * pop_reconnect - reconnect and verify indexes if connection was lost + * @param ctx Context + * @return 0 on success, -1 on error + */ int pop_reconnect(struct Context *ctx) { int ret; diff --git a/postpone.c b/postpone.c index 8fae4a63d..c37fe62c0 100644 --- a/postpone.c +++ b/postpone.c @@ -240,19 +240,18 @@ static struct Header *select_msg(void) return (r > -1 ? PostContext->hdrs[r] : NULL); } -/* args: - * ctx Context info, used when recalling a message to which - * we reply. - * hdr envelope/attachment info for recalled message - * cur if message was a reply, `cur' is set to the message which - * `hdr' is in reply to - * fcc fcc for the recalled message - * fcclen max length of fcc - * - * return vals: - * -1 error/no messages - * 0 normal exit - * SENDREPLY recalled message is a reply +/** + * mutt_get_postponed - Recall a postponed message + * @param ctx Context info, used when recalling a message to which we reply + * @param hdr envelope/attachment info for recalled message + * @param cur if message was a reply, `cur' is set to the message + * which `hdr' is in reply to + * @param fcc fcc for the recalled message + * @param fcclen max length of fcc + * @return + * * -1 Error/no messages + * * 0 Normal exit + * * SENDREPLY Recalled message is a reply */ int mutt_get_postponed(struct Context *ctx, struct Header *hdr, struct Header **cur, char *fcc, size_t fcclen) diff --git a/rfc1524.c b/rfc1524.c index 2bbf47e26..be45157b8 100644 --- a/rfc1524.c +++ b/rfc1524.c @@ -113,8 +113,11 @@ int rfc1524_expand_command(struct Body *a, char *filename, char *_type, char *co return needspipe; } -/* NUL terminates a rfc 1524 field, - * returns start of next field or NULL */ +/** + * get_field - NUL terminate a rfc 1524 field + * @param s String to alter + * @return start of next field or NULL + */ static char *get_field(char *s) { char *ch = NULL; @@ -416,16 +419,6 @@ int rfc1524_mailcap_lookup(struct Body *a, char *type, return found; } -/* This routine will create a _temporary_ filename matching the - * name template given if this needs to be done. - * - * Please note that only the last path element of the - * template and/or the old file name will be used for the - * comparison and the temporary file name. - * - * Returns 0 if oldfile is fine as is. - * Returns 1 if newfile specified - */ static void strnfcpy(char *d, char *s, size_t siz, size_t len) { if (len > siz) @@ -433,6 +426,23 @@ static void strnfcpy(char *d, char *s, size_t siz, size_t len) strfcpy(d, s, len); } +/** + * rfc1524_expand_filename - Create temp filename match a template + * @param nametemplate Template + * @param oldfile Original filename + * @param newfile Buffer for new filename + * @param nflen Buffer length + * @return + * * 0 oldfile is fine as is + * * 1 newfile specified + * + * This routine will create a _temporary_ filename matching the + * name template given if this needs to be done. + * + * Please note that only the last path element of the + * template and/or the old file name will be used for the + * comparison and the temporary file name. + */ int rfc1524_expand_filename(char *nametemplate, char *oldfile, char *newfile, size_t nflen) { int i, j, k, ps; diff --git a/rfc2047.c b/rfc2047.c index f5044a152..17f8a14ae 100644 --- a/rfc2047.c +++ b/rfc2047.c @@ -237,7 +237,16 @@ static size_t q_encoder(char *s, ICONV_CONST char *d, size_t dlen, const char *t return s - s0; } -/* +/** + * try_block - Attempt to convert a block ot text + * @param d String to convert + * @param dlen Length of string + * @param fromcode Original encoding + * @param tocode New encoding + * @param encoder Encoding function + * @param wlen Number of characters converted + * @return 0 string could be converted >0 maximum that could be converted + * * Return 0 if and set *encoder and *wlen if the data (d, dlen) could * be converted to an encoded word of length *wlen using *encoder. * Otherwise return an upper bound on the maximum length of the data @@ -312,9 +321,17 @@ static size_t try_block(ICONV_CONST char *d, size_t dlen, const char *fromcode, return dlen; } -/* +/** + * encode_block - Encode a block of text using an encoder + * @param s String to convert + * @param d Buffer for result + * @param dlen Buffer length + * @param fromcode Original encoding + * @param tocode New encoding + * @param encoder Encoding funtion + * @return Length of the encoded word + * * Encode the data (d, dlen) into s using the encoder. - * Return the length of the encoded word. */ static size_t encode_block(char *s, char *d, size_t dlen, const char *fromcode, const char *tocode, encoder_t encoder) @@ -368,7 +385,18 @@ static size_t choose_block(char *d, size_t dlen, int col, const char *fromcode, return n; } -/* +/** + * rfc2047_encode - RFC-2047-encode a string + * @param[in] d String to be encoded + * @param[in] dlen Length of string + * @param[in] col Starting index in string + * @param[in] fromcode Original encoding + * @param[in] charsets List of charsets to choose from + * @param[out] e Buffer to save result + * @param[out] elen Buffer length + * @param[in] specials Special characters to be encoded + * + * * Place the result of RFC-2047-encoding (d, dlen) into the dynamically * allocated buffer (e, elen). The input data is in charset fromcode * and is converted into a charset chosen from charsets. diff --git a/send.c b/send.c index 97e153745..68696ed6a 100644 --- a/send.c +++ b/send.c @@ -1305,16 +1305,21 @@ static int search_attach_keyword(char *filename) return found; } -/* - * Returns 0 if the message was successfully sent - * -1 if the message was aborted or an error occurred - * 1 if the message was postponed +/** + * ci_send_message - Send an email + * @param flags send mode + * @param msg template to use for new message + * @param tempfile file specified by -i or -H + * @param ctx current mailbox + * @param cur current message + * @return + * + * * 0 Message was successfully sent + * * -1 Message was aborted or an error occurred + * * 1 Message was postponed */ -int ci_send_message(int flags, /* send mode */ - struct Header *msg, /* template to use for new message */ - char *tempfile, /* file specified by -i or -H */ - struct Context *ctx, /* current mailbox */ - struct Header *cur) /* current message */ +int ci_send_message(int flags, struct Header *msg, char *tempfile, + struct Context *ctx, struct Header *cur) { char buffer[LONG_STRING]; char fcc[_POSIX_PATH_MAX] = ""; /* where to copy this message */ diff --git a/sendlib.c b/sendlib.c index ab2bd1b2e..fadbe39f2 100644 --- a/sendlib.c +++ b/sendlib.c @@ -641,11 +641,21 @@ static void update_content_info(struct Content *info, struct ContentState *s, /* Define as 1 if iconv sometimes returns -1(EILSEQ) instead of transcribing. */ #define BUGGY_ICONV 1 -/* +/** + * convert_file_to - Change the encoding of a file + * @param[in] file File to convert + * @param[in] fromcode Original encoding + * @param[in] ncodes Number of target encodings + * @param[in] tocodes List of target encodings + * @param[out] tocode Chosen encoding + * @param[in] info Encoding information + * @return + * * -1 Error, no conversion was possible + * * >0 Success, number of bytes converted + * * Find the best charset conversion of the file from fromcode into one * of the tocodes. If successful, set *tocode and Content *info and - * return the number of characters converted inexactly. If no - * conversion was possible, return -1. + * return the number of characters converted inexactly. * * We convert via UTF-8 in order to avoid the condition -1(EINVAL), * which would otherwise prevent us from knowing the number of inexact @@ -942,7 +952,13 @@ struct Content *mutt_get_content_info(const char *fname, struct Body *b) return info; } -/* Given a file with path ``s'', see if there is a registered MIME type. +/** + * mutt_lookup_mime_type - Find the MIME type for an attachment + * @param att Email with attachment + * @param path Path to attachment + * @return MIME type, e.g. #TYPEIMAGE + * + * Given a file with path ``s'', see if there is a registered MIME type. * returns the major MIME type, and copies the subtype to ``d''. First look * for ~/.mime.types, then look in a system mime.types if we can find one. * The longest match is used so that we can match `ps.gz' when `gz' also diff --git a/sidebar.c b/sidebar.c index dd66fe2eb..1aeac4a38 100644 --- a/sidebar.c +++ b/sidebar.c @@ -419,10 +419,7 @@ static void sort_entries(void) /** * select_next - Selects the next unhidden mailbox - * - * Returns: - * true: Success - * false: Failure + * @return true: Success, false: Failure */ static bool select_next(void) { @@ -444,12 +441,9 @@ static bool select_next(void) /** * select_next_new - Selects the next new mailbox + * @return true: Success, false: Failure * * Search down the list of mail folders for one containing new mail. - * - * Returns: - * true: Success - * false: Failure */ static int select_next_new(void) { @@ -478,10 +472,7 @@ static int select_next_new(void) /** * select_prev - Selects the previous unhidden mailbox - * - * Returns: - * true: Success - * false: Failure + * @return true: Success, false: Failure */ static bool select_prev(void) { @@ -503,12 +494,9 @@ static bool select_prev(void) /** * select_prev_new - Selects the previous new mailbox + * @return true: Success, false: Failure * * Search up the list of mail folders for one containing new mail. - * - * Returns: - * true: Success - * false: Failure */ static bool select_prev_new(void) { @@ -537,10 +525,7 @@ static bool select_prev_new(void) /** * select_page_down - Selects the first entry in the next page of mailboxes - * - * Returns: - * 1: Success - * 0: Failure + * @return true: Success, false: Failure */ static int select_page_down(void) { @@ -560,10 +545,7 @@ static int select_page_down(void) /** * select_page_up - Selects the last entry in the previous page of mailboxes - * - * Returns: - * 1: Success - * 0: Failure + * @return true: Success, false: Failure */ static int select_page_up(void) { @@ -1060,11 +1042,9 @@ void mutt_sb_set_buffystats(const struct Context *ctx) /** * mutt_sb_get_highlight - Get the Buffy that's highlighted in the sidebar + * @return mailbox path * * Get the path of the mailbox that's highlighted in the sidebar. - * - * Returns: - * Mailbox path */ const char *mutt_sb_get_highlight(void) { diff --git a/smtp.c b/smtp.c index bb7198776..850bca30a 100644 --- a/smtp.c +++ b/smtp.c @@ -93,10 +93,12 @@ static bool valid_smtp_code(char *buf, size_t len, int *n) return true; } -/* Reads a command response from the SMTP server. - * Returns: - * 0 on success (2xx code) or continue (354 code) - * -1 write error, or any other response code +/** + * smtp_get_resp - Read a command response from the SMTP server + * @param conn SMTP connection + * @return + * * 0 Success (2xx code) or continue (354 code) + * * -1 Write error, or any other response code */ static int smtp_get_resp(struct Connection *conn) { diff --git a/version.c b/version.c index 1b5cbbe80..74295e13f 100644 --- a/version.c +++ b/version.c @@ -336,10 +336,9 @@ static void print_compile_options(struct CompileOptions *co) /** * rstrip_in_place - Strip a trailing carriage return * @param s String to be modified + * @return The modified string * * The string has its last carriage return set to NUL. - * Returns: - * The modified string */ static char *rstrip_in_place(char *s) {