From 8410cd0cdcfd35c232b22ead3d452ea31c643de0 Mon Sep 17 00:00:00 2001 From: Richard Russon Date: Fri, 21 Jul 2017 19:30:07 +0100 Subject: [PATCH] doxygen: tidy comments @return x, y -> multiple @retval @return -> @retval more /* */ comments to /**< */ merge .h and .c function descriptions Prefix defines with # --- alias.c | 4 +-- attach.c | 28 ++++++++--------- base64.c | 5 +-- bcache.h | 20 +++++++----- buffy.c | 21 +++++++------ buffy.h | 8 ++--- commands.c | 11 +++---- complete.c | 3 +- compose.c | 9 +++--- compress.c | 75 ++++++++++++++++++-------------------------- copy.c | 10 +++--- curs_lib.c | 15 ++++----- date.c | 2 +- editmsg.c | 7 ++--- enter.c | 12 +++---- filter.c | 6 ++-- handler.c | 7 ++--- hash.c | 5 ++- hcache/backend.h | 14 ++++++--- hcache/hcache.c | 17 +++++----- hcache/hcache.h | 32 ++++++++++--------- hcache/lmdb.c | 2 +- hdrline.c | 25 ++++++++------- imap/auth_cram.c | 4 +-- imap/auth_gss.c | 2 +- imap/command.c | 13 ++++---- imap/imap.c | 49 ++++++++++++++++------------- imap/imap_private.h | 32 ++++++++----------- imap/message.c | 21 ++++++------- imap/utf7.c | 6 ++-- imap/util.c | 13 ++++---- init.c | 20 ++++++------ init.h | 6 ++-- keymap.c | 9 +++--- lib.c | 14 +++++---- main.c | 3 +- mbox.c | 32 +++++++++---------- md5.c | 12 +++---- md5.h | 2 +- mh.c | 33 +++++++++---------- mutt_notmuch.c | 74 +++++++++++++++++++------------------------ mutt_sasl_plain.h | 2 +- mutt_socket.c | 7 ++--- mutt_ssl_gnutls.c | 3 +- muttlib.c | 26 +++++++-------- mx.c | 15 ++++----- ncrypt/crypt.c | 36 ++++++++++++++++++++- ncrypt/crypt.h | 19 ----------- ncrypt/crypt_gpgme.c | 44 +++++++++++++------------- ncrypt/crypt_mod.h | 4 +-- ncrypt/cryptglue.c | 4 +-- ncrypt/cryptglue.h | 35 --------------------- ncrypt/ncrypt.h | 54 ------------------------------- ncrypt/pgp.h | 1 - ncrypt/pgpinvoke.h | 2 +- ncrypt/pgpkey.h | 4 +-- ncrypt/smime.c | 2 +- ncrypt/smime.h | 10 ------ newsrc.c | 7 ++--- nntp.c | 64 +++++++++++++++++-------------------- pager.c | 7 ++--- parse.c | 6 ++-- pattern.c | 15 ++++----- pop.c | 18 +++++------ pop.h | 1 - pop_auth.c | 11 +++---- pop_lib.c | 52 +++++++++++++++--------------- postpone.c | 12 +++---- recvattach.c | 5 ++- recvcmd.c | 2 +- rfc1524.c | 29 ++++++++--------- rfc1524.h | 2 +- rfc2047.c | 12 +++---- rfc2047.h | 2 +- rfc2231.c | 6 ++-- rfc2231.h | 2 +- rfc3676.c | 7 +++-- rfc3676.h | 5 +-- rfc822.c | 2 +- rfc822.h | 2 +- send.c | 13 ++++---- sendlib.c | 9 +++--- sidebar.c | 47 ++++++++++++++------------- smtp.c | 9 +++--- sort.h | 8 ++--- thread.c | 2 +- version.c | 7 ++--- 87 files changed, 593 insertions(+), 722 deletions(-) diff --git a/alias.c b/alias.c index ede00b001..0ace8e176 100644 --- a/alias.c +++ b/alias.c @@ -243,7 +243,7 @@ static void recode_buf(char *buf, size_t buflen) /** * check_alias_name - Sanity-check an alias name * - * Only characters which are non-special to both the RFC 822 and the mutt + * Only characters which are non-special to both the RFC822 and the mutt * configuration parser are permitted. */ int check_alias_name(const char *s, char *dest, size_t destlen) @@ -625,7 +625,7 @@ static bool string_is_address(const char *str, const char *u, const char *d) /** * mutt_addr_is_user - Does the address belong to the user - * @return true if the given address belongs to the user + * @retval true if the given address belongs to the user */ bool mutt_addr_is_user(struct Address *addr) { diff --git a/attach.c b/attach.c index e722b9d29..236976c56 100644 --- a/attach.c +++ b/attach.c @@ -93,9 +93,8 @@ int mutt_get_tmp_attachment(struct Body *a) /** * mutt_compose_attachment - Create an attachment - * @return - * * 1 if require full screen redraw - * * 0 otherwise + * @retval 1 if require full screen redraw + * @retval 0 otherwise */ int mutt_compose_attachment(struct Body *a) { @@ -222,7 +221,8 @@ bailout: /** * mutt_edit_attachment - Edit an attachment * @param a Email containing attachment - * @return 1 if editor found, 0 if not + * @retval 1 if editor found + * @retval 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 @@ -355,10 +355,9 @@ void mutt_check_lookup_list(struct Body *b, char *type, int len) * @param hdr Message header for the current message. Can be NULL * @param idx Attachment * @param idxlen Number of attachments - * @return - * * 0 if the viewer is run and exited succesfully - * * -1 on error - * * The return value of mutt_do_pager() when it is used + * @retval 0 If the viewer is run and exited succesfully + * @retval -1 Error + * @retval n Return value of mutt_do_pager() when it is used * * flag can be one of: #MUTT_MAILCAP, #MUTT_REGULAR, #MUTT_AS_TEXT * @@ -642,9 +641,8 @@ return_error: /** * mutt_pipe_attachment - Pipe an attachment to a command - * @return - * * 1 on success - * * 0 on error + * @retval 1 on success + * @retval 0 on error */ int mutt_pipe_attachment(FILE *fp, struct Body *b, const char *path, char *outfile) { @@ -750,9 +748,8 @@ static FILE *save_attachment_open(char *path, int flags) /** * mutt_save_attachment - Save an attachment - * @return - * * 0 on success - * * -1 on error + * @retval 0 on success + * @retval -1 on error */ int mutt_save_attachment(FILE *fp, struct Body *m, char *path, int flags, struct Header *hdr) { @@ -869,7 +866,8 @@ int mutt_save_attachment(FILE *fp, struct Body *m, char *path, int flags, struct /** * mutt_decode_save_attachment - Decode, then save an attachment - * @return 0 on success, -1 on error + * @retval 0 on success + * @retval -1 on error */ int mutt_decode_save_attachment(FILE *fp, struct Body *m, char *path, int displaying, int flags) { diff --git a/base64.c b/base64.c index f160743e8..da8c495af 100644 --- a/base64.c +++ b/base64.c @@ -57,7 +57,7 @@ static const char B64Chars[64] = { * @param cin Input buffer for the raw bytes * @param len Length of the input buffer * @param olen Length of the output buffer - * @return The length of the string written to the output buffer + * @retval n Length of the string written to the output buffer * * This function performs base64 encoding. The resulting string is guaranteed * to be null-terminated. The number of characters up to the terminating @@ -100,7 +100,8 @@ size_t mutt_to_base64(char *out, const char *cin, size_t len, size_t olen) * mutt_from_base64 - convert null-terminated base64 string to raw bytes * @param out Output buffer for the raw bytes * @param in Input buffer for the null-terminated base64-encoded string - * @return The number of bytes written on success, -1 on error + * @retval n Number of bytes written on success + * @retval -1 on error * * This function performs base64 decoding. The resulting buffer is NOT * null-terminated. If the input buffer contains invalid base64 characters, diff --git a/bcache.h b/bcache.h index 861cc823c..63a65f250 100644 --- a/bcache.h +++ b/bcache.h @@ -33,7 +33,7 @@ struct BodyCache; * 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 + * @retval 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 @@ -53,7 +53,8 @@ void mutt_bcache_close(struct BodyCache **bcache); * 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 + * @retval FILE* on success + * @retval NULL on failure */ FILE *mutt_bcache_get(struct BodyCache *bcache, const char *id); @@ -63,7 +64,8 @@ FILE *mutt_bcache_get(struct BodyCache *bcache, const char *id); * @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 + * @retval FILE* on success + * @retval NULL on failure */ FILE *mutt_bcache_put(struct BodyCache *bcache, const char *id, int tmp); @@ -71,7 +73,8 @@ 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 + * @retval 0 on success + * @retval -1 on failure */ int mutt_bcache_commit(struct BodyCache *bcache, const char *id); @@ -79,7 +82,8 @@ 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 + * @retval 0 on success + * @retval -1 on failure */ int mutt_bcache_del(struct BodyCache *bcache, const char *id); @@ -87,7 +91,8 @@ 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 + * @retval 0 on success + * @retval -1 on failure */ int mutt_bcache_exists(struct BodyCache *bcache, const char *id); @@ -96,7 +101,8 @@ int mutt_bcache_exists(struct BodyCache *bcache, const char *id); * @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 + * @retval -1 on failure + * @retval >=0 count of matching items * * This more or less "examines" the cache and calls a function with * each id it finds if given. diff --git a/buffy.c b/buffy.c index 871314f65..8cbfe4733 100644 --- a/buffy.c +++ b/buffy.c @@ -51,15 +51,16 @@ #include "mutt_notmuch.h" #endif -static time_t BuffyTime = 0; /* last time we started checking for mail */ -static time_t BuffyStatsTime = 0; /* last time we check performed mail_check_stats */ -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 */ +static time_t BuffyTime = 0; /**< last time we started checking for mail */ +static time_t BuffyStatsTime = 0; /**< last time we check performed mail_check_stats */ +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 */ /** * fseek_last_message - Find the last message in the file - * @return 0 on success, -1 if no message found + * @retval 0 on success + * @retval -1 if no message found */ static int fseek_last_message(FILE *f) { @@ -108,7 +109,7 @@ static int fseek_last_message(FILE *f) /** * test_last_status_new - Is the last message new - * @return 1 if the last message is new + * @retval 1 if the last message is new */ static int test_last_status_new(FILE *f) { @@ -179,7 +180,7 @@ static void buffy_free(struct Buffy **mailbox) * @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 + * @retval 1 if the dir has new mail * * Checks the specified maildir subdir (cur or new) for new mail or mail counts. */ @@ -263,7 +264,7 @@ static int buffy_maildir_check_dir(struct Buffy *mailbox, const char *dir_name, * 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 + * @retval 1 if the mailbox has new mail */ static int buffy_maildir_check(struct Buffy *mailbox, int check_stats) { @@ -291,7 +292,7 @@ static int buffy_maildir_check(struct Buffy *mailbox, int check_stats) * @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 + * @retval 1 if the mailbox has new mail */ static int buffy_mbox_check(struct Buffy *mailbox, struct stat *sb, int check_stats) { diff --git a/buffy.h b/buffy.h index a768e954b..bffa7bf9d 100644 --- a/buffy.h +++ b/buffy.h @@ -68,16 +68,16 @@ WHERE short BuffyCheckStatsInterval INITVAL(60); void mutt_buffy_vfolder(char *s, size_t slen); #endif -extern time_t BuffyDoneTime; /* last time we knew for sure how much mail there was */ +extern time_t BuffyDoneTime; /**< last time we knew for sure how much mail there was */ struct Buffy *mutt_find_mailbox(const char *path); void mutt_update_mailbox(struct Buffy *b); -/* fixes up atime + mtime after mbox/mmdf mailbox was modified - according to stat() info taken before a modification */ +/** fixes up atime + mtime after mbox/mmdf mailbox was modified + * according to stat() info taken before a modification */ void mutt_buffy_cleanup(const char *buf, struct stat *st); -/* mark mailbox just left as already notified */ +/** mark mailbox just left as already notified */ void mutt_buffy_setnotified(const char *path); int mh_buffy(struct Buffy *mailbox, int check_stats); diff --git a/commands.c b/commands.c index 8be3204d8..202f25764 100644 --- a/commands.c +++ b/commands.c @@ -69,7 +69,7 @@ static const char *ExtPagerProgress = "all"; -/* The folder the user last saved to. Used by ci_save_message() */ +/** The folder the user last saved to. Used by ci_save_message() */ static char LastSaveFolder[_POSIX_PATH_MAX] = ""; int mutt_display_message(struct Header *cur) @@ -267,7 +267,7 @@ void ci_bounce_message(struct Header *h) char *err = NULL; int rc; - /* RfC 5322 mandates a From: header, so warn before bouncing + /* RFC5322 mandates a From: header, so warn before bouncing * messages without one */ if (h) { @@ -708,7 +708,7 @@ static void set_copy_flags(struct Header *hdr, int decode, int decrypt, if (!decrypt) /* If decode doesn't kick in for decrypt, */ { - *chflags |= CH_DECODE; /* then decode RFC 2047 headers, */ + *chflags |= CH_DECODE; /* then decode RFC2047 headers, */ if (option(OPTWEED)) { @@ -745,9 +745,8 @@ int _mutt_save_message(struct Header *h, struct Context *ctx, int delete, int de /** * mutt_save_message - Save an email - * @return - * * 0 if the copy/save was successful - * * -1 on error/abort + * @retval 0 if the copy/save was successful + * @retval -1 on error/abort */ int mutt_save_message(struct Header *h, int delete, int decode, int decrypt) { diff --git a/complete.c b/complete.c index 570eb478a..b9e91a91f 100644 --- a/complete.c +++ b/complete.c @@ -42,7 +42,8 @@ * 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 + * @retval 0 if ok + * @retval -1 if no matches * * Given a partial pathname, fill in as much of the rest of the path as is * unique. diff --git a/compose.c b/compose.c index f2eb29b5f..c6260217d 100644 --- a/compose.c +++ b/compose.c @@ -590,7 +590,7 @@ static void compose_menu_redraw(struct Menu *menu) /** * cum_attachs_size - Cumulative Attachments Size * @param menu Menu listing attachments - * @return Number of bytes in attachments + * @retval n 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. @@ -699,10 +699,9 @@ static void compose_status_line(char *buf, size_t buflen, size_t col, int cols, /** * mutt_compose_menu - Allow the user to edit the message envelope - * @return - * * 1 Message should be postponed - * * 0 Normal exit - * * -1 Abort message + * @retval 1 Message should be postponed + * @retval 0 Normal exit + * @retval -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/compress.c b/compress.c index 316ea21e5..7dc81eab9 100644 --- a/compress.c +++ b/compress.c @@ -68,9 +68,8 @@ struct CompressInfo * lock_realpath - Try to lock the ctx->realpath * @param ctx Mailbox to lock * @param excl Lock exclusively? - * @return - * * 1: Success (locked or readonly) - * * 0: Error (can't lock the file) + * @retval 1 Success (locked or readonly) + * @retval 0 Error (can't lock the file) * * Try to (exclusively) lock the mailbox. If we succeed, then we mark the * mailbox as locked. If we fail, but we didn't want exclusive rights, then @@ -139,9 +138,8 @@ static void unlock_realpath(struct Context *ctx) /** * setup_paths - Set the mailbox paths * @param ctx Mailbox to modify - * @return - * * 0: Success - * * -1: Error + * @retval 0 Success + * @retval -1 Error * * Save the compressed filename in ctx->realpath. * Create a temporary filename and put its name in ctx->path. @@ -173,9 +171,8 @@ static int setup_paths(struct Context *ctx) /** * get_size - Get the size of a file * @param path File to measure - * @return - * * number: Size in bytes - * * 0: On error + * @retval n Size in bytes + * @retval 0 On error */ static int get_size(const char *path) { @@ -209,11 +206,10 @@ static void store_size(const struct Context *ctx) /** * find_hook - Find a hook to match a path - * @param type Type of hook, e.g. MUTT_CLOSEHOOK + * @param type Type of hook, e.g. #MUTT_CLOSEHOOK * @param path Filename to test - * @return - * * string: Matching hook command - * * NULL: No matches + * @retval string Matching hook command + * @retval NULL No matches * * Each hook has a type and a pattern. * Find a command that matches the type and path supplied. e.g. @@ -222,7 +218,7 @@ static void store_size(const struct Context *ctx) * open-hook '\.gz$' "gzip -cd '%f' > '%t'" * * Call: - * find_hook (MUTT_OPENHOOK, "myfile.gz"); + * find_hook (#MUTT_OPENHOOK, "myfile.gz"); */ static const char *find_hook(int type, const char *path) { @@ -239,9 +235,8 @@ static const char *find_hook(int type, const char *path) /** * set_compress_info - Find the compress hooks for a mailbox * @param ctx Mailbox to examine - * @return - * * CompressInfo: Hook info for the mailbox's path - * * NULL: On error + * @retval ptr CompressInfo Hook info for the mailbox's path + * @retval NULL On error * * When a mailbox is opened, we check if there are any matching hooks. */ @@ -295,7 +290,7 @@ static void free_compress_info(struct Context *ctx) /** * escape_path - Escapes single quotes in a path for a command string * @param src the path to escape - * @return a pointer to the escaped string + * @retval ptr The escaped string */ static char *escape_path(char *src) { @@ -346,7 +341,7 @@ static char *escape_path(char *src) * @param elsestring Otherwise, display this string, UNUSED * @param data Pointer to the mailbox Context * @param flags Format flags, UNUSED - * @return src (unchanged) + * @retval src (unchanged) * * cb_format_str is a callback function for mutt_expando_format. It understands * two operators. '%f' : 'from' filename, '%t' : 'to' filename. @@ -405,9 +400,8 @@ static void expand_command_str(const struct Context *ctx, const char *cmd, char * @param ctx Mailbox to work with * @param command Command string to execute * @param progress Message to show the user - * @return - * * 1: Success - * * 0: Failure + * @retval 1 Success + * @retval 0 Failure * * Run the supplied command, taking care of all the Mutt requirements, * such as locking files and blocking signals. @@ -506,9 +500,8 @@ or_fail: * comp_open_append_mailbox - Open a compressed mailbox for appending * @param ctx Mailbox to open * @param flags e.g. Does the file already exist? - * @return - * * 0: Success - * * -1: Failure + * @retval 0 Success + * @retval -1 Failure * * To append to a compressed mailbox we need an append-hook (or both open- and * close-hooks). @@ -587,9 +580,8 @@ oa_fail1: /** * comp_close_mailbox - Close a compressed mailbox * @param ctx Mailbox to close - * @return - * * 0: Success - * * -1: Failure + * @retval 0 Success + * @retval -1 Failure * * If the mailbox has been changed then re-compress the tmp file. * Then delete the tmp file. @@ -663,10 +655,9 @@ static int comp_close_mailbox(struct Context *ctx) * comp_check_mailbox - Check for changes in the compressed file * @param ctx Mailbox * @param index_hint Currently selected mailbox - * @return - * * 0: Mailbox OK - * * MUTT_REOPENED: The mailbox was closed and reopened - * * -1: Mailbox bad + * @retval 0 Mailbox OK + * @retval #MUTT_REOPENED The mailbox was closed and reopened + * @retval -1 Mailbox bad * * If the compressed file changes in size but the mailbox hasn't been changed * in Mutt, then we can close and reopen the mailbox. @@ -792,9 +783,8 @@ static int comp_open_new_message(struct Message *msg, struct Context *ctx, struc /** * mutt_comp_can_append - Can we append to this path? * @param ctx Mailbox - * @return - * * true: Yes, we can append to the file - * * false: No, appending isn't possible + * @retval true Yes, we can append to the file + * @retval false No, appending isn't possible * * To append to a file we can either use an 'append-hook' or a combination of * 'open-hook' and 'close-hook'. @@ -823,9 +813,8 @@ bool mutt_comp_can_append(struct Context *ctx) /** * mutt_comp_can_read - Can we read from this file? * @param path Pathname of file to be tested - * @return - * * true: Yes, we can read the file - * * false: No, we cannot read the file + * @retval true Yes, we can read the file + * @retval false No, we cannot read the file * * Search for an 'open-hook' with a regex that matches the path. * @@ -846,9 +835,8 @@ bool mutt_comp_can_read(const char *path) * comp_sync_mailbox - Save changes to the compressed mailbox file * @param ctx Mailbox to sync * @param index_hint Currently selected mailbox - * @return - * * 0: Success - * * -1: Failure + * @retval 0 Success + * @retval -1 Failure * * Changes in Mutt only affect the tmp file. Calling comp_sync_mailbox() * will commit them to the compressed file. @@ -904,9 +892,8 @@ sync_cleanup: /** * mutt_comp_valid_command - Is this command string allowed? * @param cmd Command string - * @return - * * 1: Valid command - * * 0: "%f" and/or "%t" is missing + * @retval 1 Valid command + * @retval 0 "%f" and/or "%t" is missing * * A valid command string must have both "%f" (from file) and "%t" (to file). * We don't check if we can actually run the command. diff --git a/copy.c b/copy.c index 9cca5164c..d73335c00 100644 --- a/copy.c +++ b/copy.c @@ -313,7 +313,7 @@ int mutt_copy_hdr(FILE *in, FILE *out, LOFF_T off_start, LOFF_T off_end, { if (headers[x]) { - /* We couldn't do the prefixing when reading because RFC 2047 + /* We couldn't do the prefixing when reading because RFC2047 * decoding may have concatenated lines. */ @@ -782,7 +782,8 @@ int mutt_copy_message(FILE *fpout, struct Context *src, struct Header *hdr, * @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 + * @retval 0 on success + * @retval -1 on error */ static int _mutt_append_message(struct Context *dest, FILE *fpin, struct Context *src, struct Header *hdr, @@ -830,9 +831,8 @@ int mutt_append_message(struct Context *dest, struct Context *src, /** * copy_delete_attach - Copy a message, deleting marked attachments - * @return - * * 0 on success - * * -1 on failure + * @retval 0 on success + * @retval -1 on failure * * This function copies a message body, while deleting _in_the_copy_ * any attachments which are marked for deletion. diff --git a/curs_lib.c b/curs_lib.c index 70822e974..708de04b0 100644 --- a/curs_lib.c +++ b/curs_lib.c @@ -108,7 +108,8 @@ void mutt_refresh(void) * 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. */ + * of course the Mutt way. + */ void mutt_need_hard_redraw(void) { keypad(stdscr, true); @@ -1335,7 +1336,7 @@ void mutt_paddstr(int n, const char *s) * @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 + * @retval n 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 @@ -1389,10 +1390,10 @@ out: * 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) + * @retval n Number of bytes in the first (multibyte) character of input consumes + * @retval <0 Conversion error + * @retval =0 End of input + * @retval >0 Length (bytes) */ int mutt_charlen(const char *s, int *width) { @@ -1414,7 +1415,7 @@ int mutt_charlen(const char *s, int *width) /** * mutt_strwidth - Measure a string's width in screen cells * @param s String to be measured - * @return Number of screen cells string would use + * @retval n Number of screen cells string would use */ int mutt_strwidth(const char *s) { diff --git a/date.c b/date.c index 7c958a827..c87022cce 100644 --- a/date.c +++ b/date.c @@ -130,7 +130,7 @@ time_t mutt_mktime(struct tm *t, int local) /** * is_leap_year_feb - Is it a leap year * @param tm Date to be tested - * @return true if it's a leap year + * @retval true if it's a leap year */ static int is_leap_year_feb(struct tm *tm) { diff --git a/editmsg.c b/editmsg.c index eb6e7ab29..100fa1ab2 100644 --- a/editmsg.c +++ b/editmsg.c @@ -46,10 +46,9 @@ * 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 + * @retval 1 Message not modified + * @retval 0 Message edited successfully + * @retval -1 Error */ static int edit_one_message(struct Context *ctx, struct Header *cur) { diff --git a/enter.c b/enter.c index 6d7b207d9..c03b7eb9d 100644 --- a/enter.c +++ b/enter.c @@ -213,7 +213,7 @@ static void replace_part(struct EnterState *state, size_t from, char *buf) /** * 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 + * @retval 1 if the character is not typically part of a pathname */ static inline int is_shell_char(wchar_t ch) { @@ -227,7 +227,8 @@ static inline int is_shell_char(wchar_t ch) * @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 + * @retval 0 if input was given + * @retval -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 @@ -264,10 +265,9 @@ int mutt_enter_string(char *buf, size_t buflen, int col, int flags) * @param[out] files List of files selected * @param[out] numfiles Number of files selected * @param[out] state Current state (if function is called repeatedly) - * @return - * * 1 need to redraw the screen and call me again - * * 0 if input was given - * * -1 if abort. + * @retval 1 need to redraw the screen and call me again + * @retval 0 if input was given + * @retval -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/filter.c b/filter.c index e1fcdf26a..62af41f85 100644 --- a/filter.c +++ b/filter.c @@ -38,7 +38,8 @@ * @param fdin If `in` is NULL and fdin is not -1 then fdin will be used as stdin for the command process * @param fdout If `out` is NULL and fdout is not -1 then fdout will be used as stdout for the command process * @param fderr If `error` is NULL and fderr is not -1 then fderr will be used as stderr for the command process - * @return Pid of the created process or -1 on any error creating pipes or forking + * @retval n pid of the created process + * @retval -1 on any error creating pipes or forking * * This function provides multiple mechanisms to handle IO sharing for the * command process. File streams are prioritized over file descriptors if @@ -202,7 +203,8 @@ pid_t mutt_create_filter(const char *s, FILE **in, FILE **out, FILE **err) /** * mutt_wait_filter - Wait for the exit of a process and return its status * @param pid Process id of the process to wait for - * @return Exit status of the process identified by pid or -1 in the event of an error + * @retval n Exit status of the process identified by pid + * @retval -1 Error */ int mutt_wait_filter(pid_t pid) { diff --git a/handler.c b/handler.c index b8cca5425..d1637f670 100644 --- a/handler.c +++ b/handler.c @@ -1019,9 +1019,8 @@ static int is_mmnoask(const char *buf) /** * 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 + * @retval 1 body part should be filtered by a mailcap entry prior to viewing inline + * @retval 0 otherwise */ static int is_autoview(struct Body *b) { @@ -1294,7 +1293,7 @@ static int message_handler(struct Body *a, struct State *s) /** * mutt_can_decode - Will decoding the attachment produce any output - * @return 1 if decoding the attachment will produce output + * @retval 1 if decoding the attachment will produce output */ int mutt_can_decode(struct Body *a) { diff --git a/hash.c b/hash.c index c219973ec..34b377984 100644 --- a/hash.c +++ b/hash.c @@ -121,9 +121,8 @@ struct Hash *int_hash_create(int nelem, int flags) * @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 + * @retval -1 on error + * @retval >=0 on success, index into the hash table */ static int union_hash_insert(struct Hash *table, union HashKey key, void *data) { diff --git a/hcache/backend.h b/hcache/backend.h index 636986811..68985aa13 100644 --- a/hcache/backend.h +++ b/hcache/backend.h @@ -31,7 +31,8 @@ /** * hcache_open_t - backend-specific routing to open the header cache database * @param path The path to the database file - * @return Pointer to backend-specific context on success, NULL otherwise + * @retval Pointer to backend-specific context on success + * @retval NULL otherwise * * The hcache_open function has the purpose of opening a backend-specific * connection to the database file specified by the path parameter. Backends @@ -46,7 +47,8 @@ typedef void *(*hcache_open_t)(const char *path); * @param ctx The backend-specific context retrieved via hcache_open * @param key A message identification string * @param keylen The length of the string pointed to by key - * @return Pointer to the message's headers on success, NULL otherwise + * @retval Pointer to the message's headers on success + * @retval NULL otherwise */ typedef void *(*hcache_fetch_t)(void *ctx, const char *key, size_t keylen); @@ -64,7 +66,8 @@ typedef void (*hcache_free_t)(void *ctx, void **data); * @param keylen The length of the string pointed to by key * @param data The message headers data * @param datalen The length of the string pointed to by data - * @return 0 on success, a backend-specific error code otherwise + * @retval 0 on success + * @retval a backend-specific error code otherwise */ typedef int (*hcache_store_t)(void *ctx, const char *key, size_t keylen, void *data, size_t datalen); @@ -74,7 +77,8 @@ typedef int (*hcache_store_t)(void *ctx, const char *key, size_t keylen, * @param ctx The backend-specific context retrieved via hcache_open * @param key A message identification string * @param keylen The length of the string pointed to by key - * @return 0 on success, a backend-specific error code otherwise + * @retval 0 on success + * @retval a backend-specific error code otherwise */ typedef int (*hcache_delete_t)(void *ctx, const char *key, size_t keylen); @@ -91,7 +95,7 @@ typedef void (*hcache_close_t)(void **ctx); /** * hcache_backend_t - backend-specific identification string * - * @return String describing the currently used hcache backend + * @retval String describing the currently used hcache backend */ typedef const char *(*hcache_backend_t)(void); diff --git a/hcache/hcache.c b/hcache/hcache.c index c0051c49d..9eb67603c 100644 --- a/hcache/hcache.c +++ b/hcache/hcache.c @@ -535,9 +535,8 @@ static int crc_matches(const char *d, unsigned int crc) /** * create_hcache_dir - Create parent dirs for the hcache database * @param path Database filename - * @return - * * true Success - * * false Failure (errno set) + * @retval true Success + * @retval false Failure (errno set) */ static bool create_hcache_dir(const char *path) { @@ -565,16 +564,16 @@ static bool create_hcache_dir(const char *path) * @param path Base directory, from $header_cache * @param folder Mailbox name (including protocol) * @param namer Callback to generate database filename - * @return Full pathname to the database (to be generated) - * (path must be freed by the caller) + * @retval ptr Full pathname to the database (to be generated) + * (path must be freed by the caller) * * Generate the pathname for the hcache database, it will be of the form: * BASE/FOLDER/NAME-SUFFIX * - * BASE : Base directory (@a path) - * FOLDER: Mailbox name (@a folder) - * NAME: Create by @a namer, or md5sum of @a folder - * SUFFIX: Character set (if ICONV isn't being used) + * * BASE: Base directory (@a path) + * * FOLDER: Mailbox name (@a folder) + * * NAME: Create by @a namer, or md5sum of @a folder + * * SUFFIX: Character set (if ICONV isn't being used) * * This function will create any parent directories needed, so the caller just * needs to create the database file. diff --git a/hcache/hcache.h b/hcache/hcache.h index 2ffeec165..e348ed4b1 100644 --- a/hcache/hcache.h +++ b/hcache/hcache.h @@ -39,7 +39,8 @@ typedef int (*hcache_namer_t)(const char *path, char *dest, size_t dlen); * @param folder Name of the folder containing the messages * @param namer Optional (might be NULL) client-specific function to form the * final name of the hcache database file. - * @return Pointer to a header_cache_t struct on success, NULL otherwise + * @retval Pointer to a header_cache_t struct on success + * @retval NULL otherwise */ header_cache_t *mutt_hcache_open(const char *path, const char *folder, hcache_namer_t namer); @@ -54,7 +55,8 @@ void mutt_hcache_close(header_cache_t *h); * @param h Pointer to the header_cache_t structure got by mutt_hcache_open * @param key Message identification string * @param keylen Length of the string pointed to by key - * @return Pointer to the data if found and valid, NULL otherwise + * @retval Pointer to the data if found and valid + * @retval NULL otherwise * @note This function performs a check on the validity of the data found by * comparing it with the crc value of the header_cache_t structure. * @note The returned pointer must be freed by calling mutt_hcache_free. This @@ -67,7 +69,8 @@ void *mutt_hcache_fetch(header_cache_t *h, const char *key, size_t keylen); * @param h Pointer to the header_cache_t structure got by mutt_hcache_open * @param key Message identification string * @param keylen Length of the string pointed to by key - * @return Pointer to the data if found, NULL otherwise + * @retval Pointer to the data if found + * @retval NULL otherwise * @note This function does not perform any check on the validity of the data * found. * @note The returned pointer must be freed by calling mutt_hcache_free. This @@ -85,21 +88,21 @@ void mutt_hcache_free(header_cache_t *h, void **data); /** * mutt_hcache_restore - restore a Header from data retrieved from the cache * @param d Data retrieved using mutt_hcache_fetch or mutt_hcache_fetch_raw - * @return Pointer to the restored header (cannot be NULL) + * @retval Pointer to the restored header (cannot be NULL) * @note The returned Header must be free'd by caller code with - * mutt_free_header. + * mutt_free_header(). */ struct Header *mutt_hcache_restore(const unsigned char *d); /** * mutt_hcache_store - store a Header along with a validity datum - * * @param h Pointer to the header_cache_t structure got by mutt_hcache_open * @param key Message identification string * @param keylen Length of the string pointed to by key * @param header Message header to store * @param uidvalidity IMAP-specific UIDVALIDITY value, or 0 to use the current time - * @return 0 on success, -1 otherwise + * @retval 0 on success + * @retval -1 otherwise */ int mutt_hcache_store(header_cache_t *h, const char *key, size_t keylen, struct Header *header, unsigned int uidvalidity); @@ -111,7 +114,8 @@ int mutt_hcache_store(header_cache_t *h, const char *key, size_t keylen, * @param keylen Length of the string pointed to by key * @param data Payload to associate with key * @param dlen Length of the buffer pointed to by the @a data parameter - * @return 0 on success, -1 otherwise + * @retval 0 on success + * @retval -1 otherwise */ int mutt_hcache_store_raw(header_cache_t *h, const char *key, size_t keylen, void *data, size_t dlen); @@ -121,23 +125,23 @@ int mutt_hcache_store_raw(header_cache_t *h, const char *key, size_t keylen, * @param h Pointer to the header_cache_t structure got by mutt_hcache_open * @param key Message identification string * @param keylen Length of the string pointed to by key - * @return 0 on success, -1 otherwise + * @retval 0 on success + * @retval -1 otherwise */ int mutt_hcache_delete(header_cache_t *h, const char *key, size_t keylen); /** * mutt_hcache_backend_list - get a list of backend identification strings - * - * @return Comma separated string describing the compiled-in backends + * @retval Comma separated string describing the compiled-in backends * @note The returned string must be free'd by the caller */ const char *mutt_hcache_backend_list(void); /** - * mutt_hcache_is_valid_backend - * + * mutt_hcache_is_valid_backend - Is the string a valid hcache backend * @param s String identifying a backend - * @return 1 if s is recognized as a valid backend, 0 otherwise + * @retval 1 if s is recognized as a valid backend + * @retval 0 otherwise */ int mutt_hcache_is_valid_backend(const char *s); diff --git a/hcache/lmdb.c b/hcache/lmdb.c index 12461f99b..3ee2e82b5 100644 --- a/hcache/lmdb.c +++ b/hcache/lmdb.c @@ -29,7 +29,7 @@ #include "backend.h" #include "lib.h" -/* The maximum size of the database file (2GiB). +/** The maximum size of the database file (2GiB). * The file is mmap(2)'d into memory. */ const size_t LMDB_DB_SIZE = 2147483648; diff --git a/hdrline.c b/hdrline.c index a1bf1385d..9d4379577 100644 --- a/hdrline.c +++ b/hdrline.c @@ -93,7 +93,8 @@ bool mutt_is_subscribed_list(struct Address *addr) * @param pfx Prefix string * @param buf Buffer to store results * @param buflen Buffer length - * @return 1 Mailing list found, 0 No list found + * @retval 1 Mailing list found + * @retval 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. @@ -152,7 +153,7 @@ static bool first_mailing_list(char *buf, size_t buflen, struct Address *a) * @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 + * @retval n Number of characters written * * The colors are stored as "magic" strings embedded in the text. */ @@ -201,7 +202,7 @@ enum FieldType * get_nth_wchar - Extract one char from a multi-byte table * @param table Multi-byte table * @param index Select this character - * @return String pointer to the character + * @retval ptr String pointer to the character * * Extract one multi-byte character from a string table. * If the index is invalid, then a space character will be returned. @@ -221,7 +222,7 @@ static char *get_nth_wchar(struct MbCharTable *table, int index) /** * make_from_prefix - Create a prefix for an author field * @param disp Type of field - * @return Prefix string (do not free it) + * @retval string Prefix string (do not free it) * * If $from_chars is set, pick an appropriate character from it. * If not, use the default prefix: "To", "Cc", etc @@ -341,13 +342,12 @@ static bool user_in_addr(struct Address *a) /** * 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 + * @retval 0 User is not in list + * @retval 1 User is unique recipient + * @retval 2 User is in the TO list + * @retval 3 User is in the CC list + * @retval 4 User is originator + * @retval 5 Sent to a subscribed mailinglist */ static int user_is_recipient(struct Header *h) { @@ -387,7 +387,8 @@ static int user_is_recipient(struct Header *h) * @param name String to be converted * @param buf Buffer for the result * @param buflen Size of the buffer - * @return 1 on Success, 0 on Failure + * @retval 1 on Success + * @retval 0 on Failure * * Take a name, e.g. "John F. Kennedy" and reduce it to initials "JFK". * The function saves the first character from each word. Words are delimited diff --git a/imap/auth_cram.c b/imap/auth_cram.c index 4e172a6b2..ad11198dd 100644 --- a/imap/auth_cram.c +++ b/imap/auth_cram.c @@ -64,11 +64,11 @@ enum ImapAuthRes imap_auth_cram_md5(struct ImapData *idata, const char *method) imap_cmd_start(idata, "AUTHENTICATE CRAM-MD5"); - /* From RFC 2195: + /* From RFC2195: * The data encoded in the first ready response contains a presumptively * arbitrary string of random digits, a timestamp, and the fully-qualified * primary host name of the server. The syntax of the unencoded form must - * correspond to that of an RFC 822 'msg-id' [RFC822] as described in [POP3]. + * correspond to that of an RFC822 'msg-id' [RFC822] as described in [POP3]. */ do rc = imap_cmd_step(idata); diff --git a/imap/auth_gss.c b/imap/auth_gss.c index 03c9c61ff..01908f79b 100644 --- a/imap/auth_gss.c +++ b/imap/auth_gss.c @@ -284,7 +284,7 @@ enum ImapAuthRes imap_auth_gss(struct ImapData *idata, const char *method) mutt_debug(1, "Error releasing credentials\n"); /* send_token may contain a notification to the server to flush - * credentials. RFC 1731 doesn't specify what to do, and since this + * credentials. RFC1731 doesn't specify what to do, and since this * support is only for authentication, we'll assume the server knows * enough to flush its own credentials */ gss_release_buffer(&min_stat, &send_token); diff --git a/imap/command.c b/imap/command.c index f6df30e7e..ba43ae4cc 100644 --- a/imap/command.c +++ b/imap/command.c @@ -86,7 +86,7 @@ static bool cmd_queue_full(struct ImapData *idata) /** * cmd_new - Create and queue a new command control block * @param idata IMAP data - * @return NULL if the pipeline is full + * @retval NULL if the pipeline is full */ static struct ImapCommand *cmd_new(struct ImapData *idata) { @@ -955,7 +955,9 @@ int imap_cmd_step(struct ImapData *idata) /** * imap_code - Was the command successful - * @return 1 if the command result was OK, or 0 if NO or BAD + * @param s IMAP command status + * @retval 1 if the command result was OK + * @retval 0 if NO or BAD */ int imap_code(const char *s) { @@ -996,10 +998,9 @@ const char *imap_cmd_trailer(struct ImapData *idata) * @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 + * @retval 0 on success + * @retval -1 on Failure + * @retval -2 on OK Failure * * Also, handle untagged responses. * diff --git a/imap/imap.c b/imap/imap.c index 4ab2f6c05..568dd9434 100644 --- a/imap/imap.c +++ b/imap/imap.c @@ -494,7 +494,7 @@ int imap_open_connection(struct ImapData *idata) } else { - /* RFC 2595 demands we recheck CAPABILITY after TLS completes. */ + /* RFC2595 demands we recheck CAPABILITY after TLS completes. */ if (imap_exec(idata, "CAPABILITY", 0)) goto bail; } @@ -892,8 +892,11 @@ static int imap_open_new_message(struct Message *msg, struct Context *dest, stru return 0; } -/* imap_set_flag: append str to flags if we currently have permission - * according to aclbit */ +/** + * imap_set_flag - append str to flags if we currently have permission + * + * according to aclbit + */ static void imap_set_flag(struct ImapData *idata, int aclbit, int flag, const char *str, char *flags, size_t flsize) { @@ -904,7 +907,7 @@ static void imap_set_flag(struct ImapData *idata, int aclbit, int flag, /** * imap_has_flag - Does the flag exist in the list - * @return boolean + * @retval boolean * * Do a caseless comparison of the flag against a flag list, return true if * found or flag list has '\*'. @@ -933,7 +936,8 @@ bool imap_has_flag(struct List *flag_list, const char *flag) * 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. */ + * 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) { @@ -1025,7 +1029,8 @@ static int imap_make_msg_set(struct ImapData *idata, struct Buffer *buf, * @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 + * @retval n Number of matched messages + * @retval -1 Failure * * pre/post: commands are of the form "%s %s %s %s", tag, pre, message set, post * Prepares commands for all messages matching conditions @@ -1097,7 +1102,7 @@ out: /** * compare_flags - Compare local flags against the server - * @return 0 if mutt's flags match cached server flags + * @retval 0 if mutt's flags match cached server flags */ static bool compare_flags(struct Header *h) { @@ -1224,7 +1229,8 @@ static int sync_helper(struct ImapData *idata, int right, int flag, const char * * 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 + * @retval 0 on success + * @retval -1 on error */ int imap_sync_mailbox(struct Context *ctx, int expunge) { @@ -1486,11 +1492,10 @@ int imap_close_mailbox(struct Context *ctx) * 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 + * @retval #MUTT_REOPENED mailbox has been externally modified + * @retval #MUTT_NEW_MAIL new mail has arrived + * @retval 0 no change + * @retval -1 error */ int imap_check_mailbox(struct Context *ctx, int force) { @@ -1684,11 +1689,12 @@ int imap_buffy_check(int force, int check_stats) /** * imap_status - Get the status of a mailbox - * @return - * * -1 on error - * * >=0 count of messages in mailbox + * @retval -1 on error + * @retval >=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) */ + * on the next call (for pipelining the postponed count) + */ int imap_status(char *path, int queue) { static int queued = 0; @@ -2043,7 +2049,7 @@ fail: * @param src Source buffer * @param start Starting offset into string * @param dlen Destination buffer length - * @return Length of the common string + * @retval n Length of the common string * * Trim dest to the length of the longest prefix it shares with src. */ @@ -2209,10 +2215,9 @@ int imap_complete(char *dest, size_t dlen, char *path) /** * 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 + * @retval -1 error + * @retval 0 success + * @retval 1 non-fatal error - try fetch/append */ int imap_fast_trash(struct Context *ctx, char *dest) { diff --git a/imap/imap_private.h b/imap/imap_private.h index 9956ecda9..e99b8e517 100644 --- a/imap/imap_private.h +++ b/imap/imap_private.h @@ -51,18 +51,12 @@ struct Progress; #define IMAP_LOG_PASS 5 /* IMAP command responses. Used in ImapCommand.state too */ -/* OK ... */ -#define IMAP_CMD_OK (0) -/* BAD ... */ -#define IMAP_CMD_BAD (-1) -/* NO ... */ -#define IMAP_CMD_NO (-2) -/* * ... */ -#define IMAP_CMD_CONTINUE (1) -/* + */ -#define IMAP_CMD_RESPOND (2) -/* ImapCommand.state additions */ -#define IMAP_CMD_NEW (3) +#define IMAP_CMD_OK (0) /**< OK ... */ +#define IMAP_CMD_BAD (-1) /**< BAD ... */ +#define IMAP_CMD_NO (-2) /**< NO ... */ +#define IMAP_CMD_CONTINUE (1) /**< \* ... */ +#define IMAP_CMD_RESPOND (2) /**< \+ */ +#define IMAP_CMD_NEW (3) /**< ImapCommand.state additions */ /* number of entries in the hash table */ #define IMAP_CACHE_LEN 10 @@ -128,16 +122,16 @@ 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 */ + ACL, /**< RFC2086: IMAP4 ACL extension */ + NAMESPACE, /**< RFC2342: IMAP4 Namespace */ + ACRAM_MD5, /**< RFC2195: CRAM-MD5 authentication */ + AGSSAPI, /**< RFC1731: GSSAPI authentication */ AUTH_ANON, /**< AUTH=ANONYMOUS */ - STARTTLS, /**< RFC 2595: STARTTLS */ + STARTTLS, /**< RFC2595: STARTTLS */ LOGINDISABLED, /**< LOGINDISABLED */ - IDLE, /**< RFC 2177: IDLE */ + IDLE, /**< RFC2177: IDLE */ SASL_IR, /**< SASL initial response draft */ - ENABLE, /**< RFC 5161 */ + ENABLE, /**< RFC5161 */ X_GM_EXT1, /**< https://developers.google.com/gmail/imap/imap-extensions */ CAPMAX diff --git a/imap/message.c b/imap/message.c index 18b3b776f..45c827c96 100644 --- a/imap/message.c +++ b/imap/message.c @@ -226,10 +226,9 @@ static char *msg_parse_flags(struct ImapHeader *h, char *s) * 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 + * @retval 0 Success + * @retval -1 String is corrupted + * @retval -2 Fetch contains a body or header lines that still need to be parsed */ static int msg_parse_fetch(struct ImapHeader *h, char *s) { @@ -306,10 +305,9 @@ static int msg_parse_fetch(struct ImapHeader *h, char *s) /** * 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 + * @retval 0 Success + * @retval -1 String is not a fetch response + * @retval -2 String is a corrupt fetch response * * Expects string beginning with * n FETCH. */ @@ -1195,10 +1193,9 @@ fail: /** * imap_copy_messages - Server COPY messages to another folder - * @return - * * -1 Error - * * 0 Success - * * 1 Non-fatal error - try fetch/append + * @retval -1 Error + * @retval 0 Success + * @retval 1 Non-fatal error - try fetch/append */ int imap_copy_messages(struct Context *ctx, struct Header *h, char *dest, int delete) { diff --git a/imap/utf7.c b/imap/utf7.c index 32e973dd4..6d2cc78d2 100644 --- a/imap/utf7.c +++ b/imap/utf7.c @@ -49,11 +49,11 @@ static const char B64Chars[64] = { }; /** - * utf7_to_utf8 - Convert the data (u7,u7len) from RFC 2060's UTF-7 to UTF-8 + * utf7_to_utf8 - Convert the data (u7,u7len) from RFC2060'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 + * store anything. RFC2060 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-). */ @@ -143,7 +143,7 @@ bail: } /** - * utf8_to_utf7 - Convert the data (u8,u8len) from UTF-8 to RFC 2060's UTF-7 + * utf8_to_utf7 - Convert the data (u8,u8len) from UTF-8 to RFC2060'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 diff --git a/imap/util.c b/imap/util.c index 9c5821f1b..b1f032c99 100644 --- a/imap/util.c +++ b/imap/util.c @@ -63,9 +63,8 @@ * imap_expand_path - Canonicalise an IMAP path * @param path Buffer containing path * @param len Buffer length - * @return - * * 0 on success - * * -1 on error + * @retval 0 on success + * @retval -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 @@ -504,7 +503,7 @@ void imap_error(const char *where, const char *msg) /** * imap_new_idata - Allocate and initialise a new ImapData structure - * @return NULL on failure (no mem) + * @retval NULL on failure (no mem) */ struct ImapData *imap_new_idata(void) { @@ -612,7 +611,8 @@ void imap_cachepath(struct ImapData *idata, const char *mailbox, char *dest, siz /** * imap_get_literal_count - write number of bytes in an IMAP literal into bytes - * @return 0 on success, -1 on failure + * @retval 0 on success + * @retval -1 on failure */ int imap_get_literal_count(const char *buf, long *bytes) { @@ -730,7 +730,8 @@ time_t imap_parse_date(char *s) /** * imap_make_date - format date in IMAP style: DD-MMM-YYYY HH:MM:SS +ZZzz * - * Caller should provide a buffer of IMAP_DATELEN bytes */ + * Caller should provide a buffer of IMAP_DATELEN bytes + */ void imap_make_date(char *buf, time_t timestamp) { struct tm *tm = localtime(×tamp); diff --git a/init.c b/init.c index 35670ac14..1f24f68c1 100644 --- a/init.c +++ b/init.c @@ -238,7 +238,8 @@ int query_quadoption(int opt, const char *prompt) /** * 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 + * @retval -1 on error + * @retval >0 on success */ int mutt_option_index(const char *s) { @@ -802,9 +803,8 @@ static void remove_from_list(struct List **l, const char *str) * @param s Current line of the config file * @param data data field from init.h:struct Command * @param err Buffer for any error message - * @return - * * 1 Stop processing the current file - * * -1 Failed + * @retval 1 Stop processing the current file + * @retval -1 Failed * * If the 'finish' command is found, we should stop reading the current file. */ @@ -826,9 +826,8 @@ static int finish_source(struct Buffer *tmp, struct Buffer *s, * @param s Current line of the config file * @param data data field from init.h:struct Command * @param err Buffer for any error message - * @return - * * 0 Success - * * -1 Failed + * @retval 0 Success + * @retval -1 Failed * * The 'ifdef' command allows conditional elements in the config file. * If a given variable, function, command or compile-time symbol exists, then @@ -3008,7 +3007,8 @@ static struct List *MuttrcStack; * 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 + * @retval true on success + * @retval 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 @@ -3052,7 +3052,7 @@ static int to_absolute_path(char *path, const char *reference) * 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 + * @retval <0 if mutt should pause to let the user know */ static int source_rc(const char *rcfile_path, struct Buffer *err) { @@ -4217,7 +4217,7 @@ void mutt_init(int skip_sys_rc, struct List *commands) * The creator of a mailto URL cannot expect the resolver of a URL to * understand more than the "subject" and "body" headers. Clients that * resolve mailto URLs into mail messages should be able to correctly - * create RFC 822-compliant mail messages using the "subject" and "body" + * create RFC822-compliant mail messages using the "subject" and "body" * headers. */ add_to_list(&MailtoAllow, "body"); diff --git a/init.h b/init.h index 5d0b7afef..c0fd122a6 100644 --- a/init.h +++ b/init.h @@ -779,9 +779,9 @@ struct Option MuttVars[] = { ** along with the body of your message. ** .pp ** Although the compose menu may have localized header labels, the - ** labels passed to your editor will be standard RFC 2822 headers, + ** labels passed to your editor will be standard RFC2822 headers, ** (e.g. To:, Cc:, Subject:). Headers added in your editor must - ** also be RFC 2822 headers, or one of the pseudo headers listed in + ** also be RFC2822 headers, or one of the pseudo headers listed in ** ``$edit-header''. Mutt will not understand localized header ** labels, just as it would not when parsing an actual email. ** .pp @@ -1290,7 +1290,7 @@ struct Option MuttVars[] = { /* ** .pp ** When \fIset\fP, Mutt will encode international domain names using - ** IDN. Unset this if your SMTP server can handle newer (RFC 6531) + ** IDN. Unset this if your SMTP server can handle newer (RFC6531) ** UTF-8 encoded domains. (IDN only) */ #endif /* HAVE_LIBIDN */ diff --git a/keymap.c b/keymap.c index 90c319ed2..e6a2d928f 100644 --- a/keymap.c +++ b/keymap.c @@ -471,11 +471,10 @@ static int retry_generic(int menu, keycode_t *keys, int keyslen, int lastkey) /** * 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 + * @retval >0 Function to execute + * @retval #OP_NULL No function bound to key sequence + * @retval -1 Error occurred while reading input + * @retval -2 A timeout or sigwinch occurred */ int km_dokey(int menu) { diff --git a/lib.c b/lib.c index 6c2209b1e..43f4fcf82 100644 --- a/lib.c +++ b/lib.c @@ -308,7 +308,7 @@ char *mutt_strlower(char *s) * mutt_strchrnul - find first occurrence of character in string * @param s Haystack * @param c Needle - * @return Pointer to the first occurrence if found or to the NULL character + * @retval ptr First occurrence if found or to the NULL character * * This function is like GNU's strchrnul, which is similar to the standard * strchr function: it looks for the c character in the NULL-terminated string @@ -960,7 +960,8 @@ void mutt_remove_trailing_ws(char *s) * @param dirlen Directory length * @param fname Filename * @param fnamelen Filename length - * @return NULL on error, pointer to \a dst on success + * @retval NULL Error + * @retval ptr 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. @@ -1127,7 +1128,9 @@ int mutt_atoi(const char *str, int *dst) * mutt_inbox_cmp - do two folders share the same path and one is an inbox * @param a First path * @param b Second path - * @return -1 if a is INBOX of b, 0 if none is INBOX, 1 if b is INBOX for a + * @retval -1 if a is INBOX of b + * @retval 0 if none is INBOX + * @retval 1 if b is INBOX for a * * This function compares two folder paths. It first looks for the position of * the last common '/' character. If a valid position is found and it's not the @@ -1195,9 +1198,8 @@ char *strfcpy(char *dest, const char *src, size_t dlen) * mutt_mkdir - Recursively create directories * @param path Directories to create * @param mode Permissions for final directory - * @return - * * 0 Success - * * -1 Error (errno set) + * @retval 0 Success + * @retval -1 Error (errno set) * * Create a directory, creating the parents if necessary. (like mkdir -p) * diff --git a/main.c b/main.c index ffc367680..43b665232 100644 --- a/main.c +++ b/main.c @@ -185,7 +185,8 @@ static void start_curses(void) * @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 + * @retval 0 on success + * @retval 1 on error */ int main(int argc, char **argv, char **env) { diff --git a/mbox.c b/mbox.c index 7b2567868..3fed369e5 100644 --- a/mbox.c +++ b/mbox.c @@ -557,7 +557,7 @@ static int mbox_open_new_message(struct Message *msg, struct Context *dest, stru /** * strict_addrcmp - Strictly compare two address list - * @return 1 if address lists are strictly identical + * @retval 1 if address lists are strictly identical */ static int strict_addrcmp(const struct Address *a, const struct Address *b) { @@ -645,7 +645,7 @@ static int strict_cmp_bodies(const struct Body *b1, const struct Body *b2) /** * mbox_strict_cmp_headers - Strictly compare message headers - * @return 1 if headers are strictly identical + * @retval 1 if headers are strictly identical */ int mbox_strict_cmp_headers(const struct Header *h1, const struct Header *h2) { @@ -851,12 +851,11 @@ static int reopen_mailbox(struct Context *ctx, int *index_hint) * 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 + * @retval #MUTT_REOPENED Mailbox has been reopened + * @retval #MUTT_NEW_MAIL New mail has arrived + * @retval #MUTT_LOCKED Couldn't lock the file + * @retval 0 No change + * @retval -1 Error */ static int mbox_check_mailbox(struct Context *ctx, int *index_hint) { @@ -966,9 +965,8 @@ 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 + * @retval true if the mailbox has at least 1 new messages (not old) + * @retval false otherwise */ static bool mbox_has_new(struct Context *ctx) { @@ -1011,9 +1009,8 @@ void mbox_reset_atime(struct Context *ctx, struct stat *st) /** * mbox_sync_mailbox - Sync a mailbox to disk - * @return - * * 0 Success - * * -1 Failure + * @retval 0 Success + * @retval -1 Failure */ static int mbox_sync_mailbox(struct Context *ctx, int *index_hint) { @@ -1387,10 +1384,9 @@ bail: /* Come here in case of disaster */ /** * 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 + * @retval 1 mailbox is not empty + * @retval 0 mailbox is empty + * @retval -1 on error */ int mbox_check_empty(const char *path) { diff --git a/md5.c b/md5.c index 825497bd8..23eb30313 100644 --- a/md5.c +++ b/md5.c @@ -20,7 +20,7 @@ * this program. If not, see . * * md5.c - Functions to compute MD5 message digest of files or memory blocks - * according to the definition of MD5 in RFC 1321 from April 1992. + * according to the definition of MD5 in RFC1321 from April 1992. * * NOTE: The canonical source of this file is maintained with the GNU C * Library. Bugs can be reported to bug-glibc@prep.ai.mit.edu. @@ -44,13 +44,13 @@ #define BLOCKSIZE 4096 /* This array contains the bytes used to pad the buffer to the next - 64-byte boundary. (RFC 1321, 3.1: Step 1) */ + 64-byte boundary. (RFC1321, 3.1: Step 1) */ static const unsigned char fillbuf[64] = { 0x80, 0 /* , 0, 0, ... */ }; /** * md5_init_ctx - Initialise the MD5 computation * - * (RFC 1321, 3.3: Step 3) + * (RFC1321, 3.3: Step 3) */ void md5_init_ctx(struct Md5Ctx *ctx) { @@ -275,7 +275,7 @@ void md5_process_bytes(const void *buffer, size_t len, struct Md5Ctx *ctx) /* These are the four functions used in the four steps of the MD5 algorithm - and defined in the RFC 1321. The first function is a little bit optimized + and defined in the RFC1321. The first function is a little bit optimized (as found in Colin Plumbs public domain implementation). */ /* #define FF(b, c, d) ((b & c) | (~b & d)) */ #define FF(b, c, d) (d ^ (b & (c ^ d))) @@ -300,7 +300,7 @@ void md5_process_block(const void *buffer, size_t len, struct Md5Ctx *ctx) md5_uint32 C = ctx->C; md5_uint32 D = ctx->D; - /* First increment the byte count. RFC 1321 specifies the possible length of + /* First increment the byte count. RFC1321 specifies the possible length of * the file up to 2^64 bits. Here we only compute the number of bytes. Do a * double word increment. */ ctx->total[0] += len; @@ -337,7 +337,7 @@ void md5_process_block(const void *buffer, size_t len, struct Md5Ctx *ctx) #define CYCLIC(w, s) (w = (w << s) | (w >> (32 - s))) /* Before we start, one word to the strange constants. - * They are defined in RFC 1321 as + * They are defined in RFC1321 as * T[i] = (int) (4294967296.0 * fabs (sin (i))), i=1..64 * Here is an equivalent invocation using Perl: * perl -e 'foreach(1..64){printf "0x%08x\n", int (4294967296 * abs (sin $_))}' diff --git a/md5.h b/md5.h index 774726d61..f7f417354 100644 --- a/md5.h +++ b/md5.h @@ -58,7 +58,7 @@ struct Md5Ctx */ /* Initialize structure containing state of computation. - * (RFC 1321, 3.3: Step 3) */ + * (RFC1321, 3.3: Step 3) */ void md5_init_ctx(struct Md5Ctx *ctx); /* Starting with the result of former calls of this function (or the diff --git a/mh.c b/mh.c index 2c563c9e5..55cbfd68b 100644 --- a/mh.c +++ b/mh.c @@ -237,10 +237,9 @@ static inline mode_t mh_umask(struct Context *ctx) /** * 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 + * @retval 1 mh_sequences last modification time is more recent than the last visit to this mailbox + * @retval 0 modification time is older + * @retval -1 Error */ static int mh_sequences_changed(struct Buffy *b) { @@ -257,10 +256,9 @@ static int mh_sequences_changed(struct Buffy *b) * 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 + * @retval 1 Modification time on the message file is older than the last visit to this mailbox + * @retval 0 Modification time on the message file is newer + * @retval -1 Error */ static int mh_already_notified(struct Buffy *b, int msgno) { @@ -276,7 +274,8 @@ static int mh_already_notified(struct Buffy *b, int msgno) /** * mh_valid_message - Is this a valid MH message filename * @param s Pathname to examine - * @return true name is valid, false name is invalid + * @retval true name is valid + * @retval 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 @@ -296,7 +295,7 @@ static bool mh_valid_message(const char *s) * 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 + * @retval true if the mailbox has new mail */ int mh_buffy(struct Buffy *mailbox, int check_stats) { @@ -2498,10 +2497,9 @@ FILE *maildir_open_find_message(const char *folder, const char *msg, char **newn /** * maildir_check_empty - Is the mailbox empty * @param path Mailbox to check - * @return - * * 1 Mailbox is empty - * * 0 Mailbox contains mail - * * -1 Error + * @retval 1 Mailbox is empty + * @retval 0 Mailbox contains mail + * @retval -1 Error */ int maildir_check_empty(const char *path) { @@ -2540,10 +2538,9 @@ int maildir_check_empty(const char *path) /** * mh_check_empty - Is mailbox empty * @param path Mailbox to check - * @return - * * 1 Mailbox is empty - * * 0 Mailbox contains mail - * * -1 Error + * @retval 1 Mailbox is empty + * @retval 0 Mailbox contains mail + * @retval -1 Error */ int mh_check_empty(const char *path) { diff --git a/mutt_notmuch.c b/mutt_notmuch.c index e18a552a2..046d951c4 100644 --- a/mutt_notmuch.c +++ b/mutt_notmuch.c @@ -225,9 +225,8 @@ static void url_free_tags(struct UriTag *tags) * @param[in] url URI to parse * @param[out] filename Save the filename * @param[out] tags Save the list of tags - * @return - * * true Success - * * false Error: Bad format + * @retval true Success + * @retval false Error Bad format * * Parse a NotMuch URI, such as: * * notmuch:///path/to/db?query=tag:lkml&limit=1000 @@ -382,7 +381,7 @@ static void free_ctxdata(struct NmCtxData *data) /** * new_ctxdata - Create a new nm_ctxdata object from a query * @param uri NotMuch query string - * @return a new nm_ctxdata struct + * @retval ptr New nm_ctxdata struct * * A new nm_ctxdata struct is created, then the query is parsed and saved * within it. This should be freed using free_ctxdata(). @@ -412,9 +411,8 @@ static struct NmCtxData *new_ctxdata(char *uri) /** * init_context - Add NotMuch data to the Context * @param ctx A mailbox CONTEXT - * @return - * * 0 Success - * * -1 Error: Bad format + * @retval 0 Success + * @retval -1 Error Bad format * * Create a new nm_ctxdata struct and add it CONTEXT::data. * NotMuch-specific data will be stored in this struct. @@ -473,7 +471,7 @@ static int string_to_query_type(const char *str) /** * query_window_check_timebase - Checks if a given timebase string is valid * @param[in] timebase: string containing a time base - * @return true if the given time base is valid + * @retval true if the given time base is valid * * This function returns whether a given timebase string is valid or not, * which is used to validate the user settable configuration setting: @@ -509,8 +507,8 @@ static void query_window_reset(void) * @param[in] query vfolder search string * @param[out] buf allocated string buffer to receive the modified search query * @param[in] bufsz allocated maximum size of the buf string buffer - * @return boolean value set to true if a transformed search query is available as - * a string in buf, otherwise if the search query shall not be transformed. + * @retval true Transformed search query is available as a string in buf + * @retval false Search query shall not be transformed * * This is where the magic of windowed queries happens. Taking a vfolder search * query string as parameter, it will use the following two user settings: @@ -585,8 +583,8 @@ static bool windowed_query_from_query(const char *query, char *buf, size_t bufsz * get_query_string - builds the notmuch vfolder search string * @param data internal notmuch context * @param window if true enable application of the window on the search string - * @return string containing a notmuch search query, or a NULL pointer - * if none can be generated. + * @retval string Containing a notmuch search query + * @retval NULL If none can be generated * * This function parses the internal representation of a search, and returns * a search query string ready to be fed to the notmuch API, given the search @@ -754,10 +752,9 @@ static int release_db(struct NmCtxData *data) /** * db_trans_begin - Start a NotMuch database transaction * @param data Header data - * @return - * * < 0 = error - * * 1 = new transaction started - * * 0 = already within transaction + * @retval <0 error + * @retval 1 new transaction started + * @retval 0 already within transaction */ static int db_trans_begin(struct NmCtxData *data) { @@ -795,7 +792,7 @@ static int db_trans_end(struct NmCtxData *data) /** * is_longrun - Is NotMuch in the middle of a long-running transaction * @param data Header data - * @return true if it is + * @retval true if it is */ static int is_longrun(struct NmCtxData *data) { @@ -806,9 +803,8 @@ static int is_longrun(struct NmCtxData *data) * get_database_mtime - Get the database modification time * @param[in] data Struct holding database info * @param[out] mtime Save the modification time - * @return - * * 0 Success (result in mtime) - * * -1 Error + * @retval 0 Success (result in mtime) + * @retval -1 Error * * Get the "mtime" (modification time) of the database file. * This is the time of the last update. @@ -1041,7 +1037,7 @@ static void deinit_header(struct Header *h) /** * nm2mutt_message_id - converts notmuch message Id to mutt message Id * @param id NotMuch ID to convert - * @return Mutt message ID + * @retval string Mutt message ID * * Caller must free the Mutt Message ID */ @@ -1870,9 +1866,8 @@ char *nm_uri_from_query(struct Context *ctx, char *buf, size_t bufsz) * @param new_uri allocated string receiving the reformatted URI * @param orig_uri original URI to be parsed * @param new_uri_sz size of the allocated new_uri string - * @return - * * true if new_uri contains a normalized version of the query - * * false if orig_uri contains an invalid query + * @retval true if new_uri contains a normalized version of the query + * @retval false if orig_uri contains an invalid query * * This function aims at making notmuch searches URI representations deterministic, * so that when comparing two equivalent searches they will be the same. It works @@ -2281,9 +2276,8 @@ done: /** * nm_open_mailbox - Open a notmuch virtual mailbox * @param ctx A mailbox CONTEXT - * @return - * * 0 Success - * * -1 Error + * @retval 0 Success + * @retval -1 Error */ static int nm_open_mailbox(struct Context *ctx) @@ -2336,9 +2330,8 @@ static int nm_open_mailbox(struct Context *ctx) /** * nm_close_mailbox - Close a notmuch virtual mailbox * @param ctx A mailbox CONTEXT - * @return - * * 0 Success - * * -1 Error + * @retval 0 Success + * @retval -1 Error */ static int nm_close_mailbox(struct Context *ctx) { @@ -2365,12 +2358,11 @@ static int nm_close_mailbox(struct Context *ctx) * nm_check_mailbox - Check a notmuch mailbox for new mail * @param ctx A mailbox CONTEXT * @param index_hint Remeber our place in the index - * @return - * * -1 Error - * * 0 QWQ - * * #MUTT_NEW_MAIL - new mail has arrived - * * #MUTT_REOPENED - mailbox closed and reopened - * * #MUTT_FLAGS - QWQ + * @retval -1 Error + * @retval 0 Success + * @retval #MUTT_NEW_MAIL - new mail has arrived + * @retval #MUTT_REOPENED - mailbox closed and reopened + * @retval #MUTT_FLAGS - flags have changed */ static int nm_check_mailbox(struct Context *ctx, int *index_hint) { @@ -2577,9 +2569,8 @@ static int nm_sync_mailbox(struct Context *ctx, int *index_hint) * @param ctx A mailbox CONTEXT * @param msg Message to open * @param msgno Index of message to open - * @return - * * 0 Success - * * 1 Error + * @retval 0 Success + * @retval 1 Error */ static int nm_open_message(struct Context *ctx, struct Message *msg, int msgno) { @@ -2605,9 +2596,8 @@ static int nm_open_message(struct Context *ctx, struct Message *msg, int msgno) * nm_close_message - Close a message * @param ctx A mailbox CONTEXT * @param msg Message to close - * @return - * * 0 Success - * * 1 Error + * @retval 0 Success + * @retval 1 Error */ static int nm_close_message(struct Context *ctx, struct Message *msg) { diff --git a/mutt_sasl_plain.h b/mutt_sasl_plain.h index 5eee888b6..4413363a5 100644 --- a/mutt_sasl_plain.h +++ b/mutt_sasl_plain.h @@ -33,7 +33,7 @@ * @param authz Authorization identity * @param user Authentication identity (username) * @param pass Password - * @return The number of bytes written to buf + * @retval Number Bytes written to buf * * This function can be used to build a protocol-specific SASL Response message * using the PLAIN mechanism. The protocol specific command is given in the cmd diff --git a/mutt_socket.c b/mutt_socket.c index 96960ec94..7174dddc5 100644 --- a/mutt_socket.c +++ b/mutt_socket.c @@ -141,10 +141,9 @@ int mutt_socket_write_d(struct Connection *conn, const char *buf, int len, int d /** * 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 + * @retval >0 There is data to read + * @retval 0 Read would block + * @retval -1 Connection doesn't support polling */ int mutt_socket_poll(struct Connection *conn) { diff --git a/mutt_ssl_gnutls.c b/mutt_ssl_gnutls.c index 9c5ec2d54..cd9053c48 100644 --- a/mutt_ssl_gnutls.c +++ b/mutt_ssl_gnutls.c @@ -528,7 +528,8 @@ static char *tls_make_date(time_t t, char *s, size_t len) * @param hostname Hostname * @param idx Index into certificate list * @param len Length of certificate list - * @return 0 on failure, nonzero on success + * @retval 0 on failure + * @retval >0 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 0f2eca32f..3f6429b15 100644 --- a/muttlib.c +++ b/muttlib.c @@ -427,7 +427,7 @@ void mutt_free_header(struct Header **h) /** * mutt_matches_list - Is the string in the list - * @return true if the header contained in "s" is in list "t" + * @retval true if the header contained in "s" is in list "t" */ bool mutt_matches_list(const char *s, struct List *t) { @@ -727,9 +727,8 @@ void mutt_delete_parameter(const char *attribute, struct Parameter **p) /** * mutt_needs_mailcap - Does this type need a mailcap entry do display * @param m Attachment body to be displayed - * @return - * * true Mutt requires a mailcap entry to display - * * false otherwise + * @retval true Mutt requires a mailcap entry to display + * @retval false otherwise */ bool mutt_needs_mailcap(struct Body *m) { @@ -1129,10 +1128,9 @@ void mutt_expand_fmt(char *dest, size_t destlen, const char *fmt, const char *sr /** * mutt_check_overwrite - Ask the user if overwriting is necessary - * @return - * * 0 on success - * * -1 on abort - * * 1 on error + * @retval 0 on success + * @retval -1 on abort + * @retval 1 on error */ int mutt_check_overwrite(const char *attname, const char *path, char *fname, size_t flen, int *append, char **directory) @@ -1889,10 +1887,9 @@ FILE *mutt_open_read(const char *path, pid_t *thepid) /** * mutt_save_confirm - Ask the user to save - * @return - * * 0 if OK to proceed - * * -1 to abort - * * 1 to retry + * @retval 0 if OK to proceed + * @retval -1 to abort + * @retval 1 to retry */ int mutt_save_confirm(const char *s, struct stat *st) { @@ -2202,7 +2199,8 @@ bool mutt_match_rx_list(const char *s, struct RxList *l) * @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 + * @retval true if \a s matches a pattern in \a l + * @retval 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 @@ -2295,7 +2293,7 @@ void mutt_encode_path(char *dest, size_t dlen, const char *src) * @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 + * @retval 1 if an entry was found that actually exists on disk and 0 otherwise * * Process an XDG environment variable or its fallback. */ diff --git a/mx.c b/mx.c index e0754de9b..30a552ee4 100644 --- a/mx.c +++ b/mx.c @@ -119,7 +119,8 @@ struct MxOps *mx_get_ops(int magic) * @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 + * @retval 0 on success + * @retval -1 on failure */ int mx_lock_file(const char *path, int fd, int excl, int timeout) { @@ -1128,7 +1129,8 @@ void mx_update_tables(struct Context *ctx, int committing) * 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 + * @retval 0 on success + * @retval -1 on error */ int mx_sync_mailbox(struct Context *ctx, int *index_hint) { @@ -1258,7 +1260,7 @@ int mx_sync_mailbox(struct Context *ctx, int *index_hint) * @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 + * @retval ptr new Message */ struct Message *mx_open_new_message(struct Context *dest, struct Header *hdr, int flags) { @@ -1493,10 +1495,9 @@ void mx_update_context(struct Context *ctx, int new_messages) /** * mx_check_empty - Is the mailbox empty * @param path Mailbox to check - * @return - * * 1 Mailbox is empty - * * 0 Mailbox contains mail - * * -1 Error + * @retval 1 Mailbox is empty + * @retval 0 Mailbox contains mail + * @retval -1 Error */ int mx_check_empty(const char *path) { diff --git a/ncrypt/crypt.c b/ncrypt/crypt.c index b2ecd78c0..820ca306c 100644 --- a/ncrypt/crypt.c +++ b/ncrypt/crypt.c @@ -78,6 +78,9 @@ void crypt_current_time(struct State *s, char *app_name) state_attach_puts(tmp, s); } +/** + * crypt_forget_passphrase - Forget a passphrase and display a message + */ void crypt_forget_passphrase(void) { if ((WithCrypto & APPLICATION_PGP)) @@ -107,6 +110,9 @@ static void disable_coredumps(void) #endif +/** + * crypt_valid_passphrase - Check that we have a usable passphrase, ask if not + */ int crypt_valid_passphrase(int flags) { int ret = 0; @@ -513,6 +519,11 @@ int mutt_is_application_smime(struct Body *m) return 0; } +/** + * crypt_query - Check out the type of encryption used + * + * Set the cached status values if there are any. + */ int crypt_query(struct Body *m) { int t = 0; @@ -577,6 +588,11 @@ int crypt_query(struct Body *m) return t; } +/** + * crypt_write_signed - Write the message body/part + * + * Body/part A described by state S to the given TEMPFILE. + */ int crypt_write_signed(struct Body *a, struct State *s, const char *tempfile) { FILE *fp = NULL; @@ -774,6 +790,15 @@ void crypt_extract_keys_from_messages(struct Header *h) unset_option(OPTDONTHANDLEPGPKEYS); } +/** + * crypt_get_keys - Check we have all the keys we need + * + * Do a quick check to make sure that we can find all of the + * encryption keys if the user has requested this service. + * Return the list of keys in KEYLIST. + * If oppenc_mode is true, only keys that can be determined without + * prompting will be used. + */ int crypt_get_keys(struct Header *msg, char **keylist, int oppenc_mode) { struct Address *adrlist = NULL, *last = NULL; @@ -1009,9 +1034,18 @@ int mutt_signed_handler(struct Body *a, struct State *s) /** * crypt_get_fingerprint_or_id - Get the fingerprint or long key ID + * @param pphint Start of string to be passed to pgp_add_string_to_hints() or + * crypt_add_string_to_hints() + * @param ppl Start of long key ID if detected, else NULL + * @param pps Start of short key ID if detected, else NULL + * @retval string Copy of fingerprint, if any, stripped of all spaces + * Must be FREE'd by caller + * @retval NULL Otherwise * * Obtain pointers to fingerprint or short or long key ID, if any. - * See ncrypt.h for details. + * + * Upon return, at most one of return, *ppl and *pps pointers is non-NULL, + * indicating the longest fingerprint or ID found, if any. */ const char *crypt_get_fingerprint_or_id(char *p, const char **pphint, const char **ppl, const char **pps) diff --git a/ncrypt/crypt.h b/ncrypt/crypt.h index d36efccdf..5e75d3a26 100644 --- a/ncrypt/crypt.h +++ b/ncrypt/crypt.h @@ -29,29 +29,10 @@ struct Body; struct State; void convert_to_7bit(struct Body *a); - -/* Print the current time. */ void crypt_current_time(struct State *s, char *app_name); - -/* Write the message body/part A described by state S to the given - TEMPFILE. */ int crypt_write_signed(struct Body *a, struct State *s, const char *tempfile); - -/* Obtain pointers to fingerprint or short or long key ID, if any. - - Upon return, at most one of return, *ppl and *pps pointers is non-NULL, - indicating the longest fingerprint or ID found, if any. - - Return: Copy of fingerprint, if any, stripped of all spaces, else NULL. - Must be FREE'd by caller. - *pphint Start of string to be passed to pgp_add_string_to_hints() or - crypt_add_string_to_hints(). - *ppl Start of long key ID if detected, else NULL. - *pps Start of short key ID if detected, else NULL. */ const char *crypt_get_fingerprint_or_id(char *p, const char **pphint, const char **ppl, const char **pps); - -/* Check if a string contains a numerical key */ bool crypt_is_numerical_keyid(const char *s); #endif /* _NCRYPT_CRYPT_H */ diff --git a/ncrypt/crypt_gpgme.c b/ncrypt/crypt_gpgme.c index 80ed32caa..3473b4bb4 100644 --- a/ncrypt/crypt_gpgme.c +++ b/ncrypt/crypt_gpgme.c @@ -153,7 +153,7 @@ static void redraw_if_needed(gpgme_ctx_t ctx) /** * 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 + * @retval true when s points to a digit or letter */ static int digit_or_letter(const unsigned char *s) { @@ -257,9 +257,8 @@ static const char *crypt_fpr(struct CryptKeyInfo *k) /** * crypt_fpr_or_lkeyid - Find the fingerprint of a key * @param k Key to examine - * @return - * * fingerprint if available - * * otherwise returns the long keyid + * @retval string fingerprint if available + * @retval string otherwise the long keyid */ static const char *crypt_fpr_or_lkeyid(struct CryptKeyInfo *k) { @@ -364,7 +363,7 @@ static void crypt_free_key(struct CryptKeyInfo **keylist) /** * crypt_key_is_valid - Is the key valid - * @return true when key K is valid + * @retval true when key K is valid */ static bool crypt_key_is_valid(struct CryptKeyInfo *k) { @@ -375,7 +374,7 @@ static bool crypt_key_is_valid(struct CryptKeyInfo *k) /** * crypt_id_is_strong - Is the key strong - * @return true when validity of KEY is sufficient + * @retval true when validity of KEY is sufficient */ static int crypt_id_is_strong(struct CryptKeyInfo *key) { @@ -776,7 +775,7 @@ static gpgme_key_t *create_recipient_set(const char *keylist, gpgme_protocol_t p /** * set_signer - Make sure that the correct signer is set - * @return 0 on success + * @retval 0 on success */ static int set_signer(gpgme_ctx_t ctx, int for_smime) { @@ -924,13 +923,13 @@ static int get_micalg(gpgme_ctx_t ctx, int use_smime, char *buf, size_t buflen) { if (use_smime) { - /* convert GPGME raw hash name to RFC 2633 format */ + /* convert GPGME raw hash name to RFC2633 format */ snprintf(buf, buflen, "%s", algorithm_name); ascii_strlower(buf); } else { - /* convert GPGME raw hash name to RFC 3156 format */ + /* convert GPGME raw hash name to RFC3156 format */ snprintf(buf, buflen, "pgp-%s", algorithm_name); ascii_strlower(buf + 4); } @@ -956,7 +955,8 @@ static void print_time(time_t t, struct State *s) * 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 + * @retval ptr new Body + * @retval NULL error */ static struct Body *sign_message(struct Body *a, int use_smime) { @@ -1215,7 +1215,7 @@ struct Body *smime_gpgme_build_smime_entity(struct Body *a, char *keylist) /** * show_sig_summary - Show a signature summary - * @return 1 if there is is a severe warning + * @retval 1 if there is is a severe warning * * Display the common attributes of the signature summary SUM. */ @@ -1488,11 +1488,10 @@ static void print_smime_keyinfo(const char *msg, gpgme_signature_t sig, /** * 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 + * @retval 0 Normal procession + * @retval 1 A bad signature + * @retval 2 A signature with a warning + * @retval -1 No more signature * * This function is called with the context CTX of a successful verification * operation and the enumerator IDX which should start at 0 and increment for @@ -1911,7 +1910,7 @@ restart: /** * pgp_gpgme_decrypt_mime - Decrypt a PGP/MIME message - * @return 0 on success + * @retval 0 on success * * The message in FPIN and B and return a new body and the stream in CUR and * FPOUT. @@ -2001,7 +2000,7 @@ bail: /** * smime_gpgme_decrypt_mime - Decrypt a S/MIME message - * @returns 0 on success + * @retval 0 on success * * The message in FPIN and B and return a new body and * the stream in CUR and FPOUT. @@ -2247,9 +2246,8 @@ err_ctx: * @param a String a * @param n Maximum length to compare * @param b String b - * @return - * * 0 Strings match - * * -1 Strings differ + * @retval 0 Strings match + * @retval -1 Strings differ * * Check that \a b is a complete line containing \a a followed by either LF or * CRLF. @@ -4541,7 +4539,7 @@ static struct CryptKeyInfo *crypt_ask_for_key(char *tag, char *whatfor, short ab /** * find_keys - Find keys of the recipients of the message - * @return NULL if any of the keys can not be found + * @retval 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. @@ -5004,7 +5002,7 @@ static int verify_sender(struct Header *h, gpgme_protocol_t protocol) /* * Assume address is 'mailbox@domainname'. * The mailbox part is case-sensitive, - * the domainname is not. (RFC 2821) + * the domainname is not. (RFC2821) */ const char *tmp_email = uid->email + 1; const char *tmp_sender = sender->mailbox; diff --git a/ncrypt/crypt_mod.h b/ncrypt/crypt_mod.h index dd406df1b..c9133290b 100644 --- a/ncrypt/crypt_mod.h +++ b/ncrypt/crypt_mod.h @@ -123,14 +123,14 @@ typedef struct CryptModuleSpecs void crypto_module_register(crypt_module_specs_t specs); crypt_module_specs_t crypto_module_lookup(int identifier); -/* If the crypto module identifier by IDENTIFIER has been registered, +/** If the crypto module identifier by IDENTIFIER has been registered, call its function FUNC. Do nothing else. This may be used as an expression. */ #define CRYPT_MOD_CALL_CHECK(identifier, func) \ (crypto_module_lookup(APPLICATION_##identifier) && \ (crypto_module_lookup(APPLICATION_##identifier))->functions.func) -/* Call the function FUNC in the crypto module identified by +/** Call the function FUNC in the crypto module identified by IDENTIFIER. This may be used as an expression. */ #define CRYPT_MOD_CALL(identifier, func) \ *(crypto_module_lookup(APPLICATION_##identifier))->functions.func diff --git a/ncrypt/cryptglue.c b/ncrypt/cryptglue.c index e8328e647..b99caf69d 100644 --- a/ncrypt/cryptglue.c +++ b/ncrypt/cryptglue.c @@ -131,7 +131,7 @@ void crypt_invoke_message(int type) */ /** - * crypt_pgp_void_passphrase - Reset a PGP passphrase + * crypt_pgp_void_passphrase - Silently, reset a PGP passphrase */ void crypt_pgp_void_passphrase(void) { @@ -297,7 +297,7 @@ void crypt_pgp_set_sender(const char *sender) */ /** - * crypt_smime_void_passphrase - Reset an SMIME passphrase + * crypt_smime_void_passphrase - Silently, reset an SMIME passphrase */ void crypt_smime_void_passphrase(void) { diff --git a/ncrypt/cryptglue.h b/ncrypt/cryptglue.h index 62da2df20..d5b8594b3 100644 --- a/ncrypt/cryptglue.h +++ b/ncrypt/cryptglue.h @@ -27,58 +27,23 @@ struct Address; struct Body; struct State; -/* Silently forget about a passphrase. */ void crypt_pgp_void_passphrase(void); - int crypt_pgp_valid_passphrase(void); - -/* fixme: needs documentation. */ struct Body *crypt_pgp_traditional_encryptsign(struct Body *a, int flags, char *keylist); - -/* 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. */ char *crypt_pgp_findkeys(struct Address *adrlist, int oppenc_mode); - -/* Create a new body with a PGP signed message from A. */ struct Body *crypt_pgp_sign_message(struct Body *a); - -/* 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); - -/* Invoke the PGP command to import a key. */ void crypt_pgp_invoke_import(const char *fname); - -/* fixme: needs documentation */ int crypt_pgp_verify_one(struct Body *sigbdy, struct State *s, const char *tempf); - void crypt_pgp_set_sender(const char *sender); -/* Silently forget about a passphrase. */ void crypt_smime_void_passphrase(void); - int crypt_smime_valid_passphrase(void); - -/* Ask for an SMIME key. */ - -/* 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. */ char *crypt_smime_findkeys(struct Address *adrlist, int oppenc_mode); - -/* fixme: Needs documentation. */ struct Body *crypt_smime_sign_message(struct Body *a); - -/* fixme: needs documentation. */ struct Body *crypt_smime_build_smime_entity(struct Body *a, char *certlist); - -/* Add a certificate and update index file (externally). */ void crypt_smime_invoke_import(char *infile, char *mailbox); - void crypt_smime_set_sender(const char *sender); - -/* fixme: needs documentation */ int crypt_smime_verify_one(struct Body *sigbdy, struct State *s, const char *tempf); #endif /* _NCRYPT_CRYPTGLUE_H */ diff --git a/ncrypt/ncrypt.h b/ncrypt/ncrypt.h index 6da253ef1..0eb1fc75b 100644 --- a/ncrypt/ncrypt.h +++ b/ncrypt/ncrypt.h @@ -102,93 +102,39 @@ struct State; #define KEYFLAG_ABILITIES (KEYFLAG_CANSIGN | KEYFLAG_CANENCRYPT | KEYFLAG_PREFER_ENCRYPTION | KEYFLAG_PREFER_SIGNING) /* Some prototypes -- old crypt.h. */ - int mutt_protect(struct Header *msg, char *keylist); - int mutt_is_multipart_encrypted(struct Body *b); - int mutt_is_valid_multipart_pgp_encrypted(struct Body *b); - int mutt_is_malformed_multipart_pgp_encrypted(struct Body *b); - int mutt_is_multipart_signed(struct Body *b); - int mutt_is_application_pgp(struct Body *m); - int mutt_is_application_smime(struct Body *m); - int mutt_signed_handler(struct Body *a, struct State *s); - int mutt_parse_crypt_hdr(const char *p, int set_empty_signas, int crypt_app); /* -- crypt.c -- */ - -/* Check out the type of encryption used and set the cached status - values if there are any. */ int crypt_query(struct Body *m); - -/* Fixme: To be documented. */ void crypt_extract_keys_from_messages(struct Header *h); - -/* Do a quick check to make sure that we can find all of the - encryption keys if the user has requested this service. - Return the list of keys in KEYLIST. - If oppenc_mode is true, only keys that can be determined without - prompting will be used. */ int crypt_get_keys(struct Header *msg, char **keylist, int oppenc_mode); - -/* Check if all recipients keys can be automatically determined. - * Enable encryption if they can, otherwise disable encryption. */ void crypt_opportunistic_encrypt(struct Header *msg); - -/* Forget a passphrase and display a message. */ void crypt_forget_passphrase(void); - -/* Check that we have a usable passphrase, ask if not. */ int crypt_valid_passphrase(int flags); /* -- cryptglue.c -- */ - -/* Show a message that a backend will be invoked. */ void crypt_invoke_message(int type); - -/* Decrypt a PGP/MIME message. */ int crypt_pgp_decrypt_mime(FILE *a, FILE **b, struct Body *c, struct Body **d); - -/* MIME handler for the application/pgp content-type. */ int crypt_pgp_application_pgp_handler(struct Body *m, struct State *s); - -/* MIME handler for an PGP/MIME encrypted message. */ int crypt_pgp_encrypted_handler(struct Body *a, struct State *s); - -/* fixme: needs documentation. */ void crypt_pgp_invoke_getkeys(struct Address *addr); - -/* Check for a traditional PGP message in body B. */ int crypt_pgp_check_traditional(FILE *fp, struct Body *b, int tagged_only); - -/* Generate a PGP public key attachment. */ struct Body *crypt_pgp_make_key_attachment(char *tempf); - int crypt_pgp_send_menu(struct Header *msg); - -/* fixme: needs documentation */ void crypt_pgp_extract_keys_from_attachment_list(FILE *fp, int tag, struct Body *top); - -/* Decrypt an S/MIME message. */ int crypt_smime_decrypt_mime(FILE *a, FILE **b, struct Body *c, struct Body **d); - -/* MIME handler for the application/smime content-type. */ int crypt_smime_application_smime_handler(struct Body *m, struct State *s); - -/* fixme: Needs documentation. */ void crypt_smime_getkeys(struct Envelope *env); - -/* Check that the sender matches. */ int crypt_smime_verify_sender(struct Header *h); - int crypt_smime_send_menu(struct Header *msg); - void crypt_init(void); #endif /* _NCRYPT_NCRYPT_H */ diff --git a/ncrypt/pgp.h b/ncrypt/pgp.h index 5a87805e2..9b663d74c 100644 --- a/ncrypt/pgp.h +++ b/ncrypt/pgp.h @@ -59,7 +59,6 @@ void pgp_extract_keys_from_attachment_list(FILE *fp, int tag, struct Body *top); void pgp_void_passphrase(void); int pgp_valid_passphrase(void); -/* private ? */ int pgp_verify_one(struct Body *sigbdy, struct State *s, const char *tempfile); struct Body *pgp_traditional_encryptsign(struct Body *a, int flags, char *keylist); struct Body *pgp_encrypt_message(struct Body *a, char *keylist, int sign); diff --git a/ncrypt/pgpinvoke.h b/ncrypt/pgpinvoke.h index 297c9926d..9730e97bd 100644 --- a/ncrypt/pgpinvoke.h +++ b/ncrypt/pgpinvoke.h @@ -30,7 +30,7 @@ struct Address; struct List; -/* The PGP invocation interface - not really beautiful. */ +/* The PGP invocation interface */ void pgp_invoke_import(const char *fname); void pgp_invoke_getkeys(struct Address *addr); diff --git a/ncrypt/pgpkey.h b/ncrypt/pgpkey.h index 15d6297fe..6d70ca2d3 100644 --- a/ncrypt/pgpkey.h +++ b/ncrypt/pgpkey.h @@ -32,8 +32,8 @@ struct PgpKeyInfo; */ enum PgpRing { - PGP_PUBRING, - PGP_SECRING, + PGP_PUBRING, /**< Public keys */ + PGP_SECRING, /**< Secret keys */ }; struct Body *pgp_make_key_attachment(char *tempf); diff --git a/ncrypt/smime.c b/ncrypt/smime.c index c81dbb073..1cb2d5b32 100644 --- a/ncrypt/smime.c +++ b/ncrypt/smime.c @@ -852,7 +852,7 @@ void smime_getkeys(struct Envelope *env) /** * smime_find_keys - Find the keys of the recipients of a message - * @return NULL if any of the keys can not be found + * @retval 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. diff --git a/ncrypt/smime.h b/ncrypt/smime.h index 94ea252fc..da3723898 100644 --- a/ncrypt/smime.h +++ b/ncrypt/smime.h @@ -50,25 +50,15 @@ struct SmimeKey void smime_void_passphrase(void); int smime_valid_passphrase(void); - int smime_decrypt_mime(FILE *fpin, FILE **fpout, struct Body *b, struct Body **cur); - int smime_application_smime_handler(struct Body *m, struct State *s); - struct Body *smime_sign_message(struct Body *a); - struct Body *smime_build_smime_entity(struct Body *a, char *certlist); - int smime_verify_one(struct Body *sigbdy, struct State *s, const char *tempfile); - int smime_verify_sender(struct Header *h); - void smime_getkeys(struct Envelope *env); - char *smime_find_keys(struct Address *adrlist, int oppenc_mode); - void smime_invoke_import(char *infile, char *mailbox); - int smime_send_menu(struct Header *msg); #endif diff --git a/newsrc.c b/newsrc.c index 5900df231..2aa9c91a1 100644 --- a/newsrc.c +++ b/newsrc.c @@ -156,10 +156,9 @@ void nntp_group_unread_stat(struct NntpData *nntp_data) /** * nntp_newsrc_parse - Parse .newsrc file * @param nserv NNTP server - * @return - * * 0 Not changed - * * 1 Parsed - * * -1 Error + * @retval 0 Not changed + * @retval 1 Parsed + * @retval -1 Error */ int nntp_newsrc_parse(struct NntpServer *nserv) { diff --git a/nntp.c b/nntp.c index dfecfd1e0..ab7f3241d 100644 --- a/nntp.c +++ b/nntp.c @@ -69,10 +69,9 @@ static int nntp_connect_error(struct NntpServer *nserv) /** * nntp_capabilities - Get capabilities - * @return - * * -1 Error, connection is closed - * * 0 Mode is reader, capabilities setted up - * * 1 Need to switch to reader mode + * @retval -1 Error, connection is closed + * @retval 0 Mode is reader, capabilities setted up + * @retval 1 Need to switch to reader mode */ static int nntp_capabilities(struct NntpServer *nserv) { @@ -814,11 +813,10 @@ static int nntp_query(struct NntpData *nntp_data, char *line, size_t linelen) /** * 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) + * @retval 0 Success + * @retval 1 Bad response (answer in query buffer) + * @retval -1 Connection lost + * @retval -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: @@ -932,11 +930,10 @@ static int fetch_description(char *line, void *data) * @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 + * @retval 0 Success + * @retval 1 Bad response (answer in query buffer) + * @retval -1 Connection lost + * @retval -2 Error */ static int get_description(struct NntpData *nntp_data, char *wildmat, char *msg) { @@ -1786,10 +1783,9 @@ int nntp_post(const char *msg) /** * nntp_group_poll - Check newsgroup for new articles - * @return - * * 1 New articles found - * * 0 No change - * * -1 Lost connection + * @retval 1 New articles found + * @retval 0 No change + * @retval -1 Lost connection */ static int nntp_group_poll(struct NntpData *nntp_data, int update_stat) { @@ -1831,11 +1827,10 @@ static int nntp_group_poll(struct NntpData *nntp_data, int update_stat) /** * 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 + * @retval #MUTT_REOPENED Articles have been renumbered or removed from server + * @retval #MUTT_NEW_MAIL New articles found + * @retval 0 No change + * @retval -1 Lost connection * * Leave newsrc locked */ @@ -2050,11 +2045,10 @@ static int check_mailbox(struct Context *ctx) /** * 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 + * @retval #MUTT_REOPENED Articles have been renumbered or removed from server + * @retval #MUTT_NEW_MAIL New articles found + * @retval 0 No change + * @retval -1 Lost connection */ static int nntp_check_mailbox(struct Context *ctx, int *index_hint) { @@ -2250,10 +2244,9 @@ int nntp_active_fetch(struct NntpServer *nserv, unsigned int new) /** * nntp_check_new_groups - Check for new groups/articles in subscribed groups - * @return - * * 1 New groups found - * * 0 No new groups - * * -1 Error + * @retval 1 New groups found + * @retval 0 No new groups + * @retval -1 Error */ int nntp_check_new_groups(struct NntpServer *nserv) { @@ -2362,10 +2355,9 @@ int nntp_check_new_groups(struct NntpServer *nserv) /** * nntp_check_msgid - Fetch article by Message-ID - * @return - * * 0 Success - * * 1 No such article - * * -1 Error + * @retval 0 Success + * @retval 1 No such article + * @retval -1 Error */ int nntp_check_msgid(struct Context *ctx, const char *msgid) { diff --git a/pager.c b/pager.c index b7d73f166..a8a77f31f 100644 --- a/pager.c +++ b/pager.c @@ -1395,10 +1395,9 @@ static int format_line(struct Line **line_info, int n, unsigned char *buf, int f * @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 + * @retval -1 EOF was reached + * @retval 0 normal exit, line was not displayed + * @retval >0 normal exit, line was displayed * * flags: * * #MUTT_SHOWFLAT, show characters (used for displaying help) diff --git a/parse.c b/parse.c index f2b9f454f..0052d513c 100644 --- a/parse.c +++ b/parse.c @@ -1133,7 +1133,7 @@ int mutt_parse_rfc822_line(struct Envelope *e, struct Header *hdr, char *line, } else if (ascii_strcasecmp(line + 1, "ist-Post") == 0) { - /* RFC 2369. FIXME: We should ignore whitespace, but don't. */ + /* RFC2369. FIXME: We should ignore whitespace, but don't. */ if (strncmp(p, "NO", 2) != 0) { char *beg = NULL, *end = NULL; @@ -1383,7 +1383,7 @@ done: * @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 + * @retval ptr Newly allocated envelope structure * * Caller should free the Envelope using mutt_free_envelope(). */ @@ -1410,7 +1410,7 @@ struct Envelope *mutt_read_rfc822_header(FILE *f, struct Header *hdr, hdr->content->encoding = ENC7BIT; hdr->content->length = -1; - /* RFC 2183 says this is arbitrary */ + /* RFC2183 says this is arbitrary */ hdr->content->disposition = DISPINLINE; } } diff --git a/pattern.c b/pattern.c index ee0dccef8..b979b04bc 100644 --- a/pattern.c +++ b/pattern.c @@ -1512,9 +1512,8 @@ static void set_pattern_cache_value(int *cache_entry, int value) /** * 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!) + * @retval 1 if the cache value is set and has a true value + * @retval 0 otherwise (even if unset!) */ static int get_pattern_cache_value(int cache_entry) { @@ -1818,9 +1817,8 @@ void mutt_check_simple(char *s, size_t len, const char *simple) /** * top_of_thread - Find the first email in the current thread * @param h Header of current email - * @return - * * MuttThread*: success, email found - * * NULL: on error + * @retval ptr Success, email found + * @retval NULL On error */ static struct MuttThread *top_of_thread(struct Header *h) { @@ -1840,9 +1838,8 @@ static struct MuttThread *top_of_thread(struct Header *h) /** * mutt_limit_current_thread - Limit the email view to the current thread * @param h Header of current email - * @return - * * true: Success - * * false: Failure + * @retval true Success + * @retval false Failure */ bool mutt_limit_current_thread(struct Header *h) { diff --git a/pop.c b/pop.c index aca2fc0ac..dec9dcc7e 100644 --- a/pop.c +++ b/pop.c @@ -74,11 +74,10 @@ static int fetch_message(char *line, void *file) * 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 + * @retval 0 Success + * @retval -1 Connection lost + * @retval -2 Invalid command or execution error + * @retval -3 Error writing to tempfile */ static int pop_read_header(struct PopData *pop_data, struct Header *h) { @@ -249,11 +248,10 @@ static header_cache_t *pop_hcache_open(struct PopData *pop_data, const char *pat /** * 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 + * @retval 0 Success + * @retval -1 Connection lost + * @retval -2 Invalid command or execution error + * @retval -3 Error writing to tempfile */ static int pop_fetch_headers(struct Context *ctx) { diff --git a/pop.h b/pop.h index ead4cf621..ce3012d31 100644 --- a/pop.h +++ b/pop.h @@ -45,7 +45,6 @@ struct Progress; */ enum PopStatus { - /* Status */ POP_NONE = 0, POP_CONNECTED, POP_DISCONNECTED, diff --git a/pop_auth.c b/pop_auth.c index 84eef8acf..60ee75e1c 100644 --- a/pop_auth.c +++ b/pop_auth.c @@ -329,12 +329,11 @@ static const struct PopAuth pop_authenticators[] = { /** * pop_authenticate - Authenticate with a POP server - * @return - * * 0 Successful - * * -1 Connection lost - * * -2 Login failed - * * -3 Authentication cancelled -*/ + * @retval 0 Successful + * @retval -1 Connection lost + * @retval -2 Login failed + * @retval -3 Authentication cancelled + */ int pop_authenticate(struct PopData *pop_data) { struct Account *acct = &pop_data->conn->account; diff --git a/pop_lib.c b/pop_lib.c index fb3c92ef8..4e2547639 100644 --- a/pop_lib.c +++ b/pop_lib.c @@ -49,7 +49,8 @@ * pop_parse_path - Parse a POP mailbox name * @param path Path to parse * @param acct Account to store details - * @return 0 success, -1 error + * @retval 0 success + * @retval -1 error * * Split a POP path into host, port, username and password */ @@ -120,7 +121,7 @@ static void pop_error(struct PopData *pop_data, char *msg) * fetch_capa - Parse CAPA output * @param line List of capabilities * @param data POP data - * @return 0 (always) + * @retval 0 (always) */ static int fetch_capa(char *line, void *data) { @@ -153,7 +154,7 @@ static int fetch_capa(char *line, void *data) * fetch_auth - Fetch list of the authentication mechanisms * @param line List of authentication methods * @param data POP data - * @return 0 (always) + * @retval 0 (always) */ static int fetch_auth(char *line, void *data) { @@ -178,10 +179,9 @@ static int fetch_auth(char *line, void *data) * 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 + * @retval 0 Successful + * @retval -1 Connection lost + * @retval -2 Execution error */ static int pop_capabilities(struct PopData *pop_data, int mode) { @@ -258,10 +258,9 @@ static int pop_capabilities(struct PopData *pop_data, int mode) /** * pop_connect - Open connection * @param pop_data POP data - * @return - * * 0 Successful - * * -1 Connection lost - * * -2 Invalid response + * @retval 0 Successful + * @retval -1 Connection lost + * @retval -2 Invalid response */ int pop_connect(struct PopData *pop_data) { @@ -293,11 +292,10 @@ int pop_connect(struct PopData *pop_data) /** * 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 + * @retval 0 Successful + * @retval -1 Connection lost + * @retval -2 Invalid command or execution error + * @retval -3 Authentication cancelled */ int pop_open_connection(struct PopData *pop_data) { @@ -459,10 +457,9 @@ void pop_logout(struct Context *ctx) * @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 + * @retval 0 Successful + * @retval -1 Connection lost + * @retval -2 Invalid command or execution error */ int pop_query_d(struct PopData *pop_data, char *buf, size_t buflen, char *msg) { @@ -502,11 +499,10 @@ 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) + * @retval 0 Successful + * @retval -1 Connection lost + * @retval -2 Invalid command or execution error + * @retval -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. @@ -574,7 +570,8 @@ int pop_fetch_data(struct PopData *pop_data, char *query, struct Progress *progr * 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 + * @retval 0 on success + * @retval -1 on error */ static int check_uidl(char *line, void *data) { @@ -605,7 +602,8 @@ static int check_uidl(char *line, void *data) /** * pop_reconnect - reconnect and verify indexes if connection was lost * @param ctx Context - * @return 0 on success, -1 on error + * @retval 0 on success + * @retval -1 on error */ int pop_reconnect(struct Context *ctx) { diff --git a/postpone.c b/postpone.c index 13511a762..9d157ad80 100644 --- a/postpone.c +++ b/postpone.c @@ -74,7 +74,7 @@ static short UpdateNumPostponed = 0; * @param force * * 0 Use a cached value if costly to get a fresh count (IMAP) * * 1 Force check - * @return Number of postponed messages + * @retval n Number of postponed messages */ int mutt_num_postponed(int force) { @@ -256,10 +256,9 @@ static struct Header *select_msg(void) * 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 + * @retval -1 Error/no messages + * @retval 0 Normal exit + * @retval #SENDREPLY Recalled message is a reply */ int mutt_get_postponed(struct Context *ctx, struct Header *hdr, struct Header **cur, char *fcc, size_t fcclen) @@ -570,7 +569,8 @@ int mutt_parse_crypt_hdr(const char *p, int set_empty_signas, int crypt_app) * @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 + * @retval 0 on success + * @retval -1 on error */ int mutt_prepare_template(FILE *fp, struct Context *ctx, struct Header *newhdr, struct Header *hdr, short resend) diff --git a/recvattach.c b/recvattach.c index 073ae7681..508704c6e 100644 --- a/recvattach.c +++ b/recvattach.c @@ -408,9 +408,8 @@ int mutt_tag_attach(struct Menu *menu, int n, int m) * mutt_is_message_type - Determine if a mime type matches a message or not * @param type Message type enum value * @param subtype Message subtype - * @return - * * true Type is message/news or message/rfc822 - * * false Otherwise + * @retval true Type is message/news or message/rfc822 + * @retval false Otherwise */ bool mutt_is_message_type(int type, const char *subtype) { diff --git a/recvcmd.c b/recvcmd.c index a26ea0332..5b3e721aa 100644 --- a/recvcmd.c +++ b/recvcmd.c @@ -137,7 +137,7 @@ void mutt_attach_bounce(FILE *fp, struct Header *hdr, struct AttachPtr **idx, /* one or more messages? */ p = (cur || count_tagged(idx, idxlen) == 1); - /* RfC 5322 mandates a From: header, so warn before bouncing + /* RFC5322 mandates a From: header, so warn before bouncing * messages without one */ if (cur) { diff --git a/rfc1524.c b/rfc1524.c index d381c6329..26b8e5298 100644 --- a/rfc1524.c +++ b/rfc1524.c @@ -1,6 +1,6 @@ /** * @file - * RFC 1524 Mailcap routines + * RFC1524 Mailcap routines * * @authors * Copyright (C) 1996-2000,2003,2012 Michael R. Elkins @@ -122,9 +122,10 @@ int rfc1524_expand_command(struct Body *a, char *filename, char *_type, char *co } /** - * get_field - NUL terminate a rfc 1524 field + * get_field - NUL terminate a RFC1524 field * @param s String to alter - * @return start of next field or NULL + * @retval ptr Start of next field + * @retval NULL Error */ static char *get_field(char *s) { @@ -355,7 +356,7 @@ static int rfc1524_mailcap_parse(struct Body *a, char *filename, char *type, /** * rfc1524_new_entry - Allocate memory for a new rfc1524 entry - * @return Pointer to an un-initialized struct Rfc1524MailcapEntry + * @retval ptr An un-initialized struct Rfc1524MailcapEntry */ struct Rfc1524MailcapEntry *rfc1524_new_entry(void) { @@ -364,7 +365,7 @@ struct Rfc1524MailcapEntry *rfc1524_new_entry(void) /** * rfc1524_free_entry - Deallocate an struct Rfc1524MailcapEntry - * @param entry Rfc1524MailcapEntry to deallocate. + * @param entry Rfc1524MailcapEntry to deallocate */ void rfc1524_free_entry(struct Rfc1524MailcapEntry **entry) { @@ -386,9 +387,8 @@ void rfc1524_free_entry(struct Rfc1524MailcapEntry **entry) * @param type Text type in "type/subtype" format * @param entry struct Rfc1524MailcapEntry to populate with results * @param opt Type of mailcap entry to lookup - * @return - * * 1 on success. If *entry is not NULL it poplates it with the mailcap entry - * * 0 if no matching entry is found + * @retval 1 on success. If *entry is not NULL it poplates it with the mailcap entry + * @retval 0 if no matching entry is found * * opt can be one of: #MUTT_EDIT, #MUTT_COMPOSE, #MUTT_PRINT, #MUTT_AUTOVIEW * @@ -456,10 +456,9 @@ static void strnfcpy(char *d, char *s, size_t siz, size_t len) * @param oldfile Original filename * @param newfile Buffer for new filename * @param nflen Buffer length - * @return - * * 0 if the left and right components of the oldfile and newfile match. - * * 1 otherwise. - + * @retval 0 if the left and right components of the oldfile and newfile match + * @retval 1 otherwise + * * If there is no nametemplate, the stripped oldfile name is used as the * template for newfile. * @@ -481,8 +480,7 @@ int rfc1524_expand_filename(char *nametemplate, char *oldfile, char *newfile, si newfile[0] = 0; - /* first, ignore leading path components. - */ + /* first, ignore leading path components */ if (nametemplate && (s = strrchr(nametemplate, '/'))) nametemplate = s + 1; @@ -502,8 +500,7 @@ int rfc1524_expand_filename(char *nametemplate, char *oldfile, char *newfile, si else /* oldfile && nametemplate */ { /* first, compare everything left from the "%s" - * (if there is one). - */ + * (if there is one). */ lmatch = true; ps = 0; diff --git a/rfc1524.h b/rfc1524.h index ae88d8a8f..e52770141 100644 --- a/rfc1524.h +++ b/rfc1524.h @@ -1,6 +1,6 @@ /** * @file - * RFC 1524 Mailcap routines + * RFC1524 Mailcap routines * * @authors * Copyright (C) 1996-2000 Michael R. Elkins diff --git a/rfc2047.c b/rfc2047.c index 0710ccc0b..6712aef79 100644 --- a/rfc2047.c +++ b/rfc2047.c @@ -1,6 +1,6 @@ /** * @file - * RFC 2047 MIME extensions routines + * RFC2047 MIME extensions routines * * @authors * Copyright (C) 1996-2000,2010 Michael R. Elkins @@ -250,7 +250,7 @@ static size_t q_encoder(char *s, ICONV_CONST char *d, size_t dlen, const char *t * @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 + * @retval 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. @@ -306,7 +306,7 @@ static size_t try_block(ICONV_CONST char *d, size_t dlen, const char *fromcode, len_b = len + (((ob - buf1) + 2) / 3) * 4; len_q = len + (ob - buf1) + 2 * count; - /* Apparently RFC 1468 says to use B encoding for iso-2022-jp. */ + /* Apparently RFC1468 says to use B encoding for iso-2022-jp. */ if (ascii_strcasecmp(tocode, "ISO-2022-JP") == 0) len_q = ENCWORD_LEN_MAX + 1; @@ -334,7 +334,7 @@ static size_t try_block(ICONV_CONST char *d, size_t dlen, const char *fromcode, * @param fromcode Original encoding * @param tocode New encoding * @param encoder Encoding funtion - * @return Length of the encoded word + * @retval n Length of the encoded word * * Encode the data (d, dlen) into s using the encoder. */ @@ -658,7 +658,7 @@ static int rfc2047_decode_word(char *d, const char *s, size_t len) switch (count) { case 2: - /* ignore language specification a la RFC 2231 */ + /* ignore language specification a la RFC2231 */ t = pp1; if ((t1 = memchr(pp, '*', t - pp))) t = t1; @@ -733,7 +733,7 @@ error_out_0: * 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, + * grammar in section 2 of RFC2047, 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)). */ diff --git a/rfc2047.h b/rfc2047.h index 604ab1341..f08b5eabc 100644 --- a/rfc2047.h +++ b/rfc2047.h @@ -1,6 +1,6 @@ /** * @file - * RFC 2047 MIME extensions routines + * RFC2047 MIME extensions routines * * @authors * Copyright (C) 1996-2000 Michael R. Elkins diff --git a/rfc2231.c b/rfc2231.c index 7588b8d43..254aef489 100644 --- a/rfc2231.c +++ b/rfc2231.c @@ -1,6 +1,6 @@ /** * @file - * RFC 2231 MIME Charset routines + * RFC2231 MIME Charset routines * * @authors * Copyright (C) 1999-2001 Thomas Roessler @@ -22,7 +22,7 @@ /* * Yet another MIME encoding for header data. This time, it's - * parameters, specified in RFC 2231, and modeled after the + * parameters, specified in RFC2231, and modeled after the * encoding used in URLs. * * Additionally, continuations and encoding are mixed in an, errrm, @@ -236,7 +236,7 @@ void rfc2231_decode_parameters(struct Parameter **headp) if (!(s = strchr(p->attribute, '*'))) { /* - * Using RFC 2047 encoding in MIME parameters is explicitly + * Using RFC2047 encoding in MIME parameters is explicitly * forbidden by that document. Nevertheless, it's being * generated by some software, including certain Lotus Notes to * Internet Gateways. So we actually decode it. diff --git a/rfc2231.h b/rfc2231.h index 1602a1c01..6e0a5eb91 100644 --- a/rfc2231.h +++ b/rfc2231.h @@ -1,6 +1,6 @@ /** * @file - * RFC 2231 MIME Charset routines + * RFC2231 MIME Charset routines * * @authors * Copyright (C) 1999-2000 Thomas Roessler diff --git a/rfc3676.c b/rfc3676.c index 8e4146e6b..1bdae00ae 100644 --- a/rfc3676.c +++ b/rfc3676.c @@ -1,6 +1,6 @@ /** * @file - * RFC 3676 Format Flowed routines + * RFC3676 Format Flowed routines * * @authors * Copyright (C) 2005 Andreas Krennmair @@ -265,6 +265,9 @@ static void print_fixed_line(const char *line, struct State *s, int ql, struct F fst->spaces = 0; } +/** + * rfc3676_handler - body handler implementing RFC3676 for format=flowed + */ int rfc3676_handler(struct Body *a, struct State *s) { char *buf = NULL, *t = NULL; @@ -291,7 +294,7 @@ int rfc3676_handler(struct Body *a, struct State *s) newql = get_quote_level(buf); /* end flowed paragraph (if we're within one) if quoting level - * changes (should not but can happen, see RFC 3676, sec. 4.5.) + * changes (should not but can happen, see RFC3676, sec. 4.5.) */ if (newql != quotelevel) flush_par(s, &fst); diff --git a/rfc3676.h b/rfc3676.h index dba8ace18..4779364df 100644 --- a/rfc3676.h +++ b/rfc3676.h @@ -1,6 +1,6 @@ /** * @file - * RFC 3676 Format Flowed routines + * RFC3676 Format Flowed routines * * @authors * Copyright (C) 2005 Andreas Krennmair @@ -31,10 +31,7 @@ struct Body; struct Header; struct State; -/* body handler implementing RfC 3676 for format=flowed */ int rfc3676_handler(struct Body *a, struct State *s); - -/* this does the space-stuffing for RfC3676 style messages */ void rfc3676_space_stuff(struct Header *hdr); #endif /* _MUTT_RFC3676_H */ diff --git a/rfc822.c b/rfc822.c index 9b58c9954..8ef039e39 100644 --- a/rfc822.c +++ b/rfc822.c @@ -1,6 +1,6 @@ /** * @file - * RFC 822 Email format routines + * RFC822 Email format routines * * @authors * Copyright (C) 1996-2000 Michael R. Elkins diff --git a/rfc822.h b/rfc822.h index 45957541e..8e8804b8a 100644 --- a/rfc822.h +++ b/rfc822.h @@ -1,6 +1,6 @@ /** * @file - * RFC 822 Email format routines + * RFC822 Email format routines * * @authors * Copyright (C) 1996-2000 Michael R. Elkins diff --git a/send.c b/send.c index 43ebe1849..2e4ce9334 100644 --- a/send.c +++ b/send.c @@ -90,7 +90,7 @@ static void append_signature(FILE *f) * addrcmp - compare two e-mail addresses * @param a Address 1 * @param b Address 2 - * @return true if they are equivalent + * @retval true if they are equivalent */ static bool addrcmp(struct Address *a, struct Address *b) { @@ -883,7 +883,8 @@ static int envelope_defaults(struct Envelope *env, struct Context *ctx, * @param flags compose mode * @param ctx current mailbox * @param cur current message - * @return 0 on success, -1 on error + * @retval 0 on success + * @retval -1 on error */ static int generate_body(FILE *tempfp, struct Header *msg, int flags, struct Context *ctx, struct Header *cur) @@ -1345,11 +1346,9 @@ static int search_attach_keyword(char *filename) * @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 + * @retval 0 Message was successfully sent + * @retval -1 Message was aborted or an error occurred + * @retval 1 Message was postponed */ int ci_send_message(int flags, struct Header *msg, char *tempfile, struct Context *ctx, struct Header *cur) diff --git a/sendlib.c b/sendlib.c index 530c95b79..27e6ebae9 100644 --- a/sendlib.c +++ b/sendlib.c @@ -660,9 +660,8 @@ static void update_content_info(struct Content *info, struct ContentState *s, * @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 + * @retval -1 Error, no conversion was possible + * @retval >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 @@ -970,7 +969,7 @@ struct Content *mutt_get_content_info(const char *fname, struct Body *b) * 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 + * @retval n MIME type, e.g. #TYPEIMAGE * * Given a file at `path`, see if there is a registered MIME type. * Returns the major MIME type, and copies the subtype to ``d''. First look @@ -1473,7 +1472,7 @@ static int get_toplevel_encoding(struct Body *a) /** * check_boundary - check for duplicate boundary - * @return true if duplicate found + * @retval true if duplicate found */ static bool check_boundary(const char *boundary, struct Body *b) { diff --git a/sidebar.c b/sidebar.c index e6e5f14c5..3dd970cd3 100644 --- a/sidebar.c +++ b/sidebar.c @@ -100,7 +100,7 @@ enum SidebarSrc * @param[in] elsestring Otherwise, display this string * @param[in] data Pointer to our sidebar_entry * @param[in] flags Format flags, e.g. MUTT_FORMAT_OPTIONAL - * @return src (unchanged) + * @retval src (unchanged) * * cb_format_str is a callback function for mutt_expando_format. It understands * six operators. '%B' : Mailbox name, '%F' : Number of flagged messages, @@ -277,10 +277,9 @@ static void make_sidebar_entry(char *buf, unsigned int buflen, int width, * cb_qsort_sbe - qsort callback to sort SBENTRYs * @param a First SbEntry to compare * @param b Second SbEntry to compare - * @return - * * -1: a precedes b - * * 0: a and b are identical - * * 1: b precedes a + * @retval -1 a precedes b + * @retval 0 a and b are identical + * @retval 1 b precedes a */ static int cb_qsort_sbe(const void *a, const void *b) { @@ -429,7 +428,8 @@ static void sort_entries(void) /** * select_next - Selects the next unhidden mailbox - * @return true: Success, false: Failure + * @retval true Success + * @retval false Failure */ static bool select_next(void) { @@ -451,7 +451,8 @@ static bool select_next(void) /** * select_next_new - Selects the next new mailbox - * @return true: Success, false: Failure + * @retval true Success + * @retval false Failure * * Search down the list of mail folders for one containing new mail. */ @@ -482,7 +483,8 @@ static int select_next_new(void) /** * select_prev - Selects the previous unhidden mailbox - * @return true: Success, false: Failure + * @retval true Success + * @retval false Failure */ static bool select_prev(void) { @@ -504,7 +506,8 @@ static bool select_prev(void) /** * select_prev_new - Selects the previous new mailbox - * @return true: Success, false: Failure + * @retval true Success + * @retval false Failure * * Search up the list of mail folders for one containing new mail. */ @@ -535,7 +538,8 @@ static bool select_prev_new(void) /** * select_page_down - Selects the first entry in the next page of mailboxes - * @return true: Success, false: Failure + * @retval true Success + * @retval false Failure */ static int select_page_down(void) { @@ -555,7 +559,8 @@ static int select_page_down(void) /** * select_page_up - Selects the last entry in the previous page of mailboxes - * @return true: Success, false: Failure + * @retval true Success + * @retval false Failure */ static int select_page_up(void) { @@ -576,9 +581,8 @@ static int select_page_up(void) /** * prepare_sidebar - Prepare the list of SBENTRYs for the sidebar display * @param page_size The number of lines on a page - * @return - * * false: No, don't draw the sidebar - * * true: Yes, draw the sidebar + * @retval false No, don't draw the sidebar + * @retval true Yes, draw the sidebar * * Before painting the sidebar, we determine which are visible, sort * them and set up our page pointers. @@ -661,9 +665,8 @@ static bool prepare_sidebar(int page_size) * draw_divider - Draw a line between the sidebar and the rest of mutt * @param num_rows Height of the Sidebar * @param num_cols Width of the Sidebar - * @return - * * 0: Empty string - * * n: Character occupies n screen columns + * @retval 0 Empty string + * @retval n Character occupies n screen columns * * Draw a divider using characters from the config option "sidebar_divider_char". * This can be an ASCII or Unicode character. @@ -785,10 +788,10 @@ static void fill_empty_space(int first_row, int num_rows, int div_width, int num * On the first run they'll be NULL, so we display the top of Mutt's list * (Incoming). * - * TopBuffy - first visible mailbox - * BotBuffy - last visible mailbox - * OpnBuffy - mailbox shown in Mutt's Index Panel - * HilBuffy - Unselected mailbox (the paging follows this) + * * TopBuffy - first visible mailbox + * * BotBuffy - last visible mailbox + * * OpnBuffy - mailbox shown in Mutt's Index Panel + * * HilBuffy - Unselected mailbox (the paging follows this) * * The entries are formatted using "sidebar_format" and may be abbreviated: * "sidebar_short_path", indented: "sidebar_folder_indent", @@ -1052,7 +1055,7 @@ 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 + * @retval string Mailbox path * * Get the path of the mailbox that's highlighted in the sidebar. */ diff --git a/smtp.c b/smtp.c index a6c139fc6..47ae92124 100644 --- a/smtp.c +++ b/smtp.c @@ -104,9 +104,8 @@ static bool valid_smtp_code(char *buf, size_t len, int *n) /** * 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 + * @retval 0 Success (2xx code) or continue (354 code) + * @retval -1 Write error, or any other response code */ static int smtp_get_resp(struct Connection *conn) { @@ -249,7 +248,7 @@ static int smtp_data(struct Connection *conn, const char *msgfile) /** * address_uses_unicode - Do any addresses use Unicode - * @return true if any of the string of addresses use 8-bit characters + * @retval true if any of the string of addresses use 8-bit characters */ static bool address_uses_unicode(const char *a) { @@ -269,7 +268,7 @@ static bool address_uses_unicode(const char *a) /** * addresses_use_unicode - Do any of a list of addresses use Unicode - * @return true if any use 8-bit characters + * @retval true if any use 8-bit characters */ static bool addresses_use_unicode(const struct Address *a) { diff --git a/sort.h b/sort.h index 7a539e77d..413b78b2b 100644 --- a/sort.h +++ b/sort.h @@ -29,14 +29,14 @@ struct Address; struct Context; -#define SORT_DATE 1 /* the date the mail was sent. */ +#define SORT_DATE 1 /**< the date the mail was sent. */ #define SORT_SIZE 2 #define SORT_SUBJECT 3 -#define SORT_ALPHA 3 /* makedoc.c requires this */ +#define SORT_ALPHA 3 /**< makedoc.c requires this */ #define SORT_FROM 4 -#define SORT_ORDER 5 /* the order the messages appear in the mailbox. */ +#define SORT_ORDER 5 /**< the order the messages appear in the mailbox. */ #define SORT_THREADS 6 -#define SORT_RECEIVED 7 /* when the message were delivered locally */ +#define SORT_RECEIVED 7 /**< when the message were delivered locally */ #define SORT_TO 8 #define SORT_SCORE 9 #define SORT_ALIAS 10 diff --git a/thread.c b/thread.c index 92f6aaed2..a83de5b97 100644 --- a/thread.c +++ b/thread.c @@ -1068,7 +1068,7 @@ static struct Header *find_virtual(struct MuttThread *cur, int reverse) * @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 + * @retval n Index into the virtual email table */ int _mutt_aside_thread(struct Header *hdr, short dir, short subthreads) { diff --git a/version.c b/version.c index 5e68b3509..5d6744d6a 100644 --- a/version.c +++ b/version.c @@ -342,7 +342,7 @@ 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 + * @retval string The modified string * * The string has its last carriage return set to NUL. */ @@ -457,9 +457,8 @@ void print_copyright(void) /** * feature_enabled - Test if a compile-time feature is enabled * @param name Compile-time symbol of the feature - * @return - * * true: Feature enabled - * * false: Feature not enabled, or not compiled in + * @retval true Feature enabled + * @retval false Feature not enabled, or not compiled in * * Many of the larger features of mutt can be disabled at compile time. * They define a symbol and use ifdef's around their code. -- 2.40.0