From: Richard Russon <rich@flatcap.org>
Date: Thu, 19 Apr 2018 16:38:59 +0000 (+0100)
Subject: doxygen: Fix, improve, tidy comment blocks
X-Git-Tag: neomutt-20180512~45
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=dede661b81764a154ed51dd0b83433c7b0f9faa7;p=neomutt

doxygen: Fix, improve, tidy comment blocks
---

diff --git a/attach.c b/attach.c
index 87084c392..186e1e01d 100644
--- a/attach.c
+++ b/attach.c
@@ -350,9 +350,9 @@ void mutt_check_lookup_list(struct Body *b, char *type, size_t len)
  * @param flag   Option flag for how the attachment should be viewed
  * @param hdr    Message header for the current message. Can be NULL
  * @param actx   Attachment context
- * @retval 0  If the viewer is run and exited successfully
- * @retval -1 Error
- * @retval n  Return value of mutt_do_pager() when it is used
+ * @retval 0   If the viewer is run and exited successfully
+ * @retval -1  Error
+ * @retval num Return value of mutt_do_pager() when it is used
  *
  * flag can be one of: #MUTT_MAILCAP, #MUTT_REGULAR, #MUTT_AS_TEXT
  *
@@ -639,8 +639,8 @@ return_error:
 
 /**
  * mutt_pipe_attachment - Pipe an attachment to a command
- * @retval 1 on success
- * @retval 0 on error
+ * @retval 1 Success
+ * @retval 0 Error
  */
 int mutt_pipe_attachment(FILE *fp, struct Body *b, const char *path, char *outfile)
 {
@@ -876,8 +876,8 @@ int mutt_save_attachment(FILE *fp, struct Body *m, char *path, int flags, struct
 
 /**
  * mutt_decode_save_attachment - Decode, then save an attachment
- * @retval 0 on success
- * @retval -1 on error
+ * @retval 0  Success
+ * @retval -1 Error
  */
 int mutt_decode_save_attachment(FILE *fp, struct Body *m, char *path, int displaying, int flags)
 {
diff --git a/bcache.h b/bcache.h
index 6626e263f..2da3548e6 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)
- * @retval NULL on failure
+ * @retval NULL 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,8 +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
- * @retval FILE* on success
- * @retval NULL  on failure
+ * @retval ptr  Success
+ * @retval NULL Failure
  */
 FILE *mutt_bcache_get(struct BodyCache *bcache, const char *id);
 
@@ -62,8 +62,8 @@ FILE *mutt_bcache_get(struct BodyCache *bcache, const char *id);
  * mutt_bcache_put - Create a file in the Body Cache
  * @param bcache Body Cache from mutt_bcache_open()
  * @param id     Per-mailbox unique identifier for the message
- * @retval FILE* on success
- * @retval NULL on failure
+ * @retval ptr  Success
+ * @retval NULL Failure
  *
  * The returned FILE* is in a temporary location.
  * Use mutt_bcache_commit to put it into place
@@ -74,8 +74,8 @@ FILE *mutt_bcache_put(struct BodyCache *bcache, const char *id);
  * 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
- * @retval 0 on success
- * @retval -1 on failure
+ * @retval  0 Success
+ * @retval -1 Failure
  */
 int mutt_bcache_commit(struct BodyCache *bcache, const char *id);
 
@@ -83,8 +83,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
- * @retval 0 on success
- * @retval -1 on failure
+ * @retval  0 Success
+ * @retval -1 Failure
  */
 int mutt_bcache_del(struct BodyCache *bcache, const char *id);
 
@@ -92,8 +92,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
- * @retval 0 on success
- * @retval -1 on failure
+ * @retval  0 Success
+ * @retval -1 Failure
  */
 int mutt_bcache_exists(struct BodyCache *bcache, const char *id);
 
@@ -102,7 +102,7 @@ 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
- * @retval -1  on failure
+ * @retval -1  Failure
  * @retval >=0 count of matching items
  *
  * This more or less "examines" the cache and calls a function with
diff --git a/body.c b/body.c
index d9c770294..4a791ed40 100644
--- a/body.c
+++ b/body.c
@@ -40,7 +40,12 @@ struct Body *mutt_body_new(void)
 }
 
 /**
- * mutt_body_copy - create a send-mode duplicate from a receive-mode body
+ * mutt_body_copy - Create a send-mode duplicate from a receive-mode body
+ * @param[in]  fp  FILE pointer to attachments
+ * @param[out] tgt New Body will be saved here
+ * @param[in]  src Source Body to copy
+ * @retval  0 Success
+ * @retval -1 Failure
  */
 int mutt_body_copy(FILE *fp, struct Body **tgt, struct Body *src)
 {
diff --git a/buffy.c b/buffy.c
index 8bad1fa03..027574e85 100644
--- a/buffy.c
+++ b/buffy.c
@@ -61,8 +61,8 @@ static short BuffyNotify = 0; /**< # of unnotified new boxes */
 
 /**
  * fseek_last_message - Find the last message in the file
- * @retval 0 on success
- * @retval -1 if no message found
+ * @retval  0 Success
+ * @retval -1 No message found
  */
 static int fseek_last_message(FILE *f)
 {
diff --git a/commands.c b/commands.c
index 53044b9ef..73d72bd26 100644
--- a/commands.c
+++ b/commands.c
@@ -748,8 +748,8 @@ int mutt_save_message_ctx(struct Header *h, int delete, int decode, int decrypt,
 
 /**
  * mutt_save_message - Save an email
- * @retval 0 if the copy/save was successful
- * @retval -1 on error/abort
+ * @retval  0 Copy/save was successful
+ * @retval -1 Error/abort
  */
 int mutt_save_message(struct Header *h, int delete, int decode, int decrypt)
 {
diff --git a/compose.c b/compose.c
index a59f96ecc..12d809a4c 100644
--- a/compose.c
+++ b/compose.c
@@ -642,7 +642,7 @@ static void compose_menu_redraw(struct Menu *menu)
 /**
  * cum_attachs_size - Cumulative Attachments Size
  * @param menu Menu listing attachments
- * @retval n Number of bytes in attachments
+ * @retval num Bytes in attachments
  *
  * Returns the total number of bytes used by the attachments in the attachment
  * list _after_ content-transfer-encodings have been applied.
diff --git a/compress.c b/compress.c
index c31969b12..9ab49497b 100644
--- a/compress.c
+++ b/compress.c
@@ -169,8 +169,8 @@ static int setup_paths(struct Context *ctx)
 /**
  * get_size - Get the size of a file
  * @param path File to measure
- * @retval n Size in bytes
- * @retval 0 On error
+ * @retval num Size in bytes
+ * @retval 0   Error
  */
 static int get_size(const char *path)
 {
@@ -206,8 +206,8 @@ 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 path Filename to test
- * @retval string Matching hook command
- * @retval NULL   No matches
+ * @retval ptr  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.
@@ -234,7 +234,7 @@ 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
  * @retval ptr  CompressInfo Hook info for the mailbox's path
- * @retval NULL On error
+ * @retval NULL Error
  *
  * When a mailbox is opened, we check if there are any matching hooks.
  */
@@ -400,9 +400,9 @@ static void expand_command_str(const struct Context *ctx, const char *cmd, char
 
 /**
  * execute_command - Run a system command
- * @param ctx         Mailbox to work with
- * @param command     Command string to execute
- * @param progress    Message to show the user
+ * @param ctx      Mailbox to work with
+ * @param command  Command string to execute
+ * @param progress Message to show the user
  * @retval 1 Success
  * @retval 0 Failure
  *
diff --git a/conn/sasl.c b/conn/sasl.c
index 5135b3aa5..9934e771a 100644
--- a/conn/sasl.c
+++ b/conn/sasl.c
@@ -71,7 +71,7 @@ static sasl_secret_t *secret_ptr = NULL;
 /**
  * getnameinfo_err - Convert a getaddrinfo() error code into an SASL error code
  * @param ret getaddrinfo() error code, e.g. EAI_AGAIN
- * @retval int SASL error code, e.g. SASL_FAIL
+ * @retval num SASL error code, e.g. SASL_FAIL
  */
 static int getnameinfo_err(int ret)
 {
@@ -128,7 +128,7 @@ static int getnameinfo_err(int ret)
  * @param addrlen Size of addr struct
  * @param out     Buffer for result
  * @param outlen  Length of buffer
- * @retval int SASL error code, e.g. SASL_BADPARAM
+ * @retval num SASL error code, e.g. SASL_BADPARAM
  *
  * utility function, copied from sasl2 sample code
  */
@@ -163,7 +163,7 @@ static int iptostring(const struct sockaddr *addr, socklen_t addrlen, char *out,
  * @param context  Supplied context, always NULL
  * @param priority Debug level
  * @param message  Message
- * @retval int SASL_OK, always
+ * @retval num SASL_OK, always
  */
 static int mutt_sasl_cb_log(void *context, int priority, const char *message)
 {
@@ -174,7 +174,7 @@ static int mutt_sasl_cb_log(void *context, int priority, const char *message)
 
 /**
  * mutt_sasl_start - Initialise SASL library
- * @retval int SASL error code, e.g. SASL_OK
+ * @retval num SASL error code, e.g. SASL_OK
  *
  * Call before doing an SASL exchange - initialises library (if necessary).
  */
@@ -216,7 +216,7 @@ static int mutt_sasl_start(void)
  * @param[in]  id      Field to get.  SASL_CB_USER or SASL_CB_AUTHNAME
  * @param[out] result  Resulting string
  * @param[out] len     Length of result
- * @retval int SASL error code, e.g. SASL_FAIL
+ * @retval num SASL error code, e.g. SASL_FAIL
  */
 static int mutt_sasl_cb_authname(void *context, int id, const char **result, unsigned int *len)
 {
@@ -260,7 +260,7 @@ static int mutt_sasl_cb_authname(void *context, int id, const char **result, uns
  * @param[in]  context Account
  * @param[in]  id      SASL_CB_PASS
  * @param[out] psecret SASL secret
- * @retval int SASL error code, e.g SASL_FAIL
+ * @retval num SASL error code, e.g SASL_FAIL
  */
 static int mutt_sasl_cb_pass(sasl_conn_t *conn, void *context, int id, sasl_secret_t **psecret)
 {
@@ -627,7 +627,7 @@ int mutt_sasl_client_new(struct Connection *conn, sasl_conn_t **saslconn)
 /**
  * mutt_sasl_interact - Perform an SASL interaction with the user
  * @param interaction Details of interaction
- * @retval int SASL error code: SASL_OK or SASL_FAIL
+ * @retval num SASL error code: SASL_OK or SASL_FAIL
  *
  * An example interaction might be asking the user for a password.
  */
diff --git a/conn/sasl_plain.h b/conn/sasl_plain.h
index a919de9ff..cd1705c7e 100644
--- a/conn/sasl_plain.h
+++ b/conn/sasl_plain.h
@@ -33,7 +33,7 @@
  * @param authz  Authorization identity
  * @param user   Authentication identity (username)
  * @param pass   Password
- * @retval Number Bytes written to buf
+ * @retval num 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/conn/ssl_gnutls.c b/conn/ssl_gnutls.c
index cc6c284ca..b694497f5 100644
--- a/conn/ssl_gnutls.c
+++ b/conn/ssl_gnutls.c
@@ -543,8 +543,8 @@ static int tls_check_preauth(const gnutls_datum_t *certdata,
  * @param hostname Hostname
  * @param idx      Index into certificate list
  * @param len      Length of certificate list
- * @retval 0  on failure
- * @retval >0 on success
+ * @retval 0  Failure
+ * @retval >0 Success
  */
 static int tls_check_one_certificate(const gnutls_datum_t *certdata,
                                      gnutls_certificate_status_t certstat,
diff --git a/copy.c b/copy.c
index 331b7a97a..4d2c61aa9 100644
--- a/copy.c
+++ b/copy.c
@@ -774,8 +774,8 @@ int mutt_copy_message_ctx(FILE *fpout, struct Context *src, struct Header *hdr,
  * @param hdr     message being copied
  * @param flags   mutt_open_copy_message() flags
  * @param chflags mutt_copy_header() flags
- * @retval 0 on success
- * @retval -1 on error
+ * @retval  0 Success
+ * @retval -1 Error
  */
 static int append_message(struct Context *dest, FILE *fpin, struct Context *src,
                           struct Header *hdr, int flags, int chflags)
@@ -821,8 +821,12 @@ int mutt_append_message(struct Context *dest, struct Context *src,
 
 /**
  * copy_delete_attach - Copy a message, deleting marked attachments
- * @retval 0 on success
- * @retval -1 on failure
+ * @param b     Email Body
+ * @param fpin  FILE pointer to read from
+ * @param fpout FILE pointer to write to
+ * @param date  Date stamp
+ * @retval  0 Success
+ * @retval -1 Failure
  *
  * This function copies a message body, while deleting _in_the_copy_
  * any attachments which are marked for deletion.
@@ -880,7 +884,7 @@ static int copy_delete_attach(struct Body *b, FILE *fpin, FILE *fpout, char *dat
  * a buffer instead of writing to a stream.  mutt_write_address_list could be
  * re-used if we wouldn't store all the decoded headers in a huge array, first.
  *
- * XXX - fix that.
+ * TODO - fix that.
  */
 static void format_address_header(char **h, struct Address *a)
 {
diff --git a/curs_lib.c b/curs_lib.c
index 3e45ebd62..0100d291d 100644
--- a/curs_lib.c
+++ b/curs_lib.c
@@ -941,7 +941,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
- * @retval n Number of bytes to use
+ * @retval num Bytes to use
  *
  * See how many bytes to copy from string so it's at most maxlen bytes long and
  * maxwid columns wide
@@ -994,7 +994,7 @@ out:
 /**
  * mutt_strwidth - Measure a string's width in screen cells
  * @param s String to be measured
- * @retval n Number of screen cells string would use
+ * @retval num Screen cells string would use
  */
 int mutt_strwidth(const char *s)
 {
@@ -1036,7 +1036,7 @@ int mutt_strwidth(const char *s)
  * message_is_visible - Is a message in the index within limit
  * @param ctx   Open mailbox
  * @param index Message ID (index into `ctx->hdrs[]`
- * @retval bool True if the message is within limit
+ * @retval true The message is within limit
  *
  * If no limit is in effect, all the messages are visible.
  */
@@ -1052,7 +1052,7 @@ bool message_is_visible(struct Context *ctx, int index)
  * message_is_tagged - Is a message in the index tagged (and within limit)
  * @param ctx   Open mailbox
  * @param index Message ID (index into `ctx->hdrs[]`
- * @retval bool True if the message is both tagged and within limit
+ * @retval true The message is both tagged and within limit
  *
  * If a limit is in effect, the message must be visible within it.
  */
diff --git a/doxygen/doxygen.conf b/doxygen/doxygen.conf
index 2d9f5fc83..889d54b63 100644
--- a/doxygen/doxygen.conf
+++ b/doxygen/doxygen.conf
@@ -688,7 +688,7 @@ CITE_BIB_FILES         =
 # messages are off.
 # The default value is: NO.
 
-QUIET                  = NO
+QUIET                  = YES
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are
 # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
diff --git a/editmsg.c b/editmsg.c
index 91bf17ab7..878ed91b6 100644
--- a/editmsg.c
+++ b/editmsg.c
@@ -20,7 +20,11 @@
  * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/* simple, editor-based message editing */
+/**
+ * @page editmsg Prepare an email to be edited
+ *
+ * Prepare an email to be edited
+ */
 
 #include "config.h"
 #include <errno.h>
@@ -45,7 +49,7 @@
 /**
  * edit_or_view_one_message - Edit an email or view it in an external editor
  * @param edit true if the message should be editable. If false, changes
- *            to the massage (in the editor) will be ignored.
+ *            to the message (in the editor) will be ignored.
  * @param ctx Context
  * @param cur Header of email
  * @retval 1  Message not modified
diff --git a/enter.c b/enter.c
index a3eb41a3f..98a60eb4b 100644
--- a/enter.c
+++ b/enter.c
@@ -64,8 +64,9 @@ static int my_addwch(wchar_t wc)
 
 /**
  * replace_part - Search and replace on a buffer
- *
- * Replace part of the wchar_t buffer, from FROM to CURPOS, by BUF.
+ * @param state Current state of the input buffer
+ * @param from  Starting point for the replacement
+ * @param buf   Replacement string
  */
 static void replace_part(struct EnterState *state, size_t from, char *buf)
 {
@@ -100,7 +101,7 @@ static void replace_part(struct EnterState *state, size_t from, char *buf)
 }
 
 /**
- * mutt_enter_string_simple - Ask the user for a string
+ * mutt_enter_string - Ask the user for a string
  * @param buf    Buffer to store the string
  * @param buflen Buffer length
  * @param col    Initial cursor position
@@ -768,9 +769,3 @@ void mutt_enter_state_free(struct EnterState **esp)
   FREE(esp);
 }
 
-/*
- * TODO:
- * very narrow screen might crash it
- * sort out the input side
- * unprintable chars
- */
diff --git a/filter.c b/filter.c
index 83fac2dc5..7efa93db2 100644
--- a/filter.c
+++ b/filter.c
@@ -40,8 +40,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
- * @retval n  pid of the created process
- * @retval -1 on any error creating pipes or forking
+ * @retval num PID of the created process
+ * @retval -1  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
@@ -206,8 +206,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
- * @retval n  Exit status of the process identified by pid
- * @retval -1 Error
+ * @retval num Exit status of the process identified by pid
+ * @retval -1  Error
  */
 int mutt_wait_filter(pid_t pid)
 {
diff --git a/flags.c b/flags.c
index 28c75cd31..bb0661575 100644
--- a/flags.c
+++ b/flags.c
@@ -333,7 +333,9 @@ void mutt_set_flag_update(struct Context *ctx, struct Header *h, int flag, int b
 }
 
 /**
- * mutt_thread_set_flag - Set a flag on an entire thread
+ * mutt_tag_set_flag - Set flag on tagged messages
+ * @param flag Flag to set, e.g. #MUTT_DELETE
+ * @param bf   true: set the flag; false: clear the flag
  */
 void mutt_tag_set_flag(int flag, int bf)
 {
diff --git a/from.c b/from.c
index e2eb7495e..0fa271d7a 100644
--- a/from.c
+++ b/from.c
@@ -27,10 +27,17 @@
 #include <time.h>
 #include "mutt/mutt.h"
 
-/*
- * A valid message separator looks like:
+/**
+ * is_from - Is a string a 'From' header line?
+ * @param[in]  s       String to test
+ * @param[out] path    Buffer for extracted path
+ * @param[in]  pathlen Length of buffer
+ * @param[out] tp      Extracted time
+ * @retval 1 Yes, it is
+ * @retval 0 No, it isn't
  *
- * From [ <return-path> ] <weekday> <month> <day> <time> [ <timezone> ] <year>
+ * A valid message separator looks like:
+ * `From [ <return-path> ] <weekday> <month> <day> <time> [ <timezone> ] <year>`
  */
 int is_from(const char *s, char *path, size_t pathlen, time_t *tp)
 {
diff --git a/hcache/backend.h b/hcache/backend.h
index 169510bb9..5bee49282 100644
--- a/hcache/backend.h
+++ b/hcache/backend.h
@@ -31,8 +31,8 @@
 /**
  * hcache_open_t - backend-specific routing to open the header cache database
  * @param path The path to the database file
- * @retval Pointer to backend-specific context on success
- * @retval NULL otherwise
+ * @retval ptr  Success, backend-specific context
+ * @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
@@ -47,8 +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
- * @retval Pointer to the message's headers on success
- * @retval NULL otherwise
+ * @retval ptr  Success, message's headers
+ * @retval NULL Otherwise
  */
 typedef void *(*hcache_fetch_t)(void *ctx, const char *key, size_t keylen);
 
@@ -66,8 +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
- * @retval 0 on success
- * @retval a backend-specific error code otherwise
+ * @retval 0   Success
+ * @retval num Error, a backend-specific error code
  */
 typedef int (*hcache_store_t)(void *ctx, const char *key, size_t keylen,
                               void *data, size_t datalen);
@@ -77,8 +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
- * @retval 0 on success
- * @retval a backend-specific error code otherwise
+ * @retval 0   Success
+ * @retval num Error, a backend-specific error code
  */
 typedef int (*hcache_delete_t)(void *ctx, const char *key, size_t keylen);
 
@@ -94,8 +94,7 @@ typedef void (*hcache_close_t)(void **ctx);
 
 /**
  * hcache_backend_t - backend-specific identification string
- *
- * @retval String describing the currently used hcache backend
+ * @retval ptr String describing the currently used hcache backend
  */
 typedef const char *(*hcache_backend_t)(void);
 
diff --git a/hcache/hcache.h b/hcache/hcache.h
index f5f6ac898..be21297f0 100644
--- a/hcache/hcache.h
+++ b/hcache/hcache.h
@@ -59,8 +59,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.
- * @retval Pointer to a header_cache_t struct on success
- * @retval NULL otherwise
+ * @retval ptr  Success, header_cache_t struct
+ * @retval NULL Otherwise
  */
 header_cache_t *mutt_hcache_open(const char *path, const char *folder, hcache_namer_t namer);
 
@@ -75,10 +75,12 @@ 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
- * @retval Pointer to the data if found and valid
- * @retval NULL otherwise
+ * @retval ptr  Succees, 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
  *       must be done before closing the header cache with mutt_hcache_close.
  */
@@ -89,8 +91,9 @@ 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
- * @retval Pointer to the data if found
- * @retval NULL otherwise
+ * @retval ptr  Success, 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
@@ -108,7 +111,8 @@ 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
- * @retval Pointer to the restored header (cannot be NULL)
+ * @retval ptr Success, the restored header (cannot be NULL)
+ *
  * @note The returned Header must be free'd by caller code with
  *       mutt_header_free().
  */
@@ -121,8 +125,8 @@ struct Header *mutt_hcache_restore(const unsigned char *d);
  * @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
- * @retval 0 on success
- * @return A generic or backend-specific error code otherwise
+ * @retval 0   Success
+ * @retval num Generic or backend-specific error code otherwise
  */
 int mutt_hcache_store(header_cache_t *h, const char *key, size_t keylen,
                       struct Header *header, unsigned int uidvalidity);
@@ -134,8 +138,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
- * @retval 0 on success
- * @return A generic or backend-specific error code otherwise
+ * @retval 0   success
+ * @retval num Generic or backend-specific error code otherwise
  */
 int mutt_hcache_store_raw(header_cache_t *h, const char *key, size_t keylen,
                           void *data, size_t dlen);
@@ -145,14 +149,15 @@ 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
- * @retval 0 on success
- * @return A generic or backend-specific error code otherwise
+ * @retval 0   Success
+ * @retval num Generic or backend-specific error code 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
- * @retval Comma separated string describing the compiled-in backends
+ * @retval ptr 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);
diff --git a/hdrline.c b/hdrline.c
index 6994b2867..ea98c050e 100644
--- a/hdrline.c
+++ b/hdrline.c
@@ -147,7 +147,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
- * @retval n Number of characters written
+ * @retval num Characters written
  *
  * The colors are stored as "magic" strings embedded in the text.
  */
@@ -214,7 +214,7 @@ static char *get_nth_wchar(struct MbTable *table, int index)
 /**
  * make_from_prefix - Create a prefix for an author field
  * @param disp   Type of field
- * @retval string Prefix string (do not free it)
+ * @retval ptr 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
diff --git a/history.c b/history.c
index b9cd3cae2..3b9b7dfa9 100644
--- a/history.c
+++ b/history.c
@@ -508,7 +508,7 @@ static void history_menu(char *buf, size_t buflen, char **matches, int match_cou
  * @param[in]  search_buf String to find
  * @param[in]  hclass     History list
  * @param[out] matches    All the matching lines
- * @retval num Number of matches found
+ * @retval num Matches found
  */
 static int search_history(char *search_buf, enum HistoryClass hclass, char **matches)
 {
diff --git a/hook.c b/hook.c
index 69a551e89..166e8fc89 100644
--- a/hook.c
+++ b/hook.c
@@ -263,7 +263,8 @@ error:
 }
 
 /**
- * delete_hook - XXX
+ * delete_hook - Delete a Hook
+ * @param h Hook to delete
  */
 static void delete_hook(struct Hook *h)
 {
@@ -380,7 +381,12 @@ void mutt_folder_hook(const char *path)
 }
 
 /**
- * mutt_find_hook - XXX
+ * mutt_find_hook - Find a matching hook
+ * @param type Type, e.g. #MUTT_FOLDERHOOK
+ * @param pat  Pattern to match
+ * @retval ptr Command string
+ *
+ * @note The returned string must not be freed.
  */
 char *mutt_find_hook(int type, const char *pat)
 {
diff --git a/imap/imap.c b/imap/imap.c
index 93f62a1bb..efa771c8c 100644
--- a/imap/imap.c
+++ b/imap/imap.c
@@ -173,10 +173,10 @@ static void set_flag(struct ImapData *idata, int aclbit, int flag,
  * @param[in]  changed Matched messages that have been altered
  * @param[in]  invert  Flag matches should be inverted
  * @param[out] pos     Cursor used for multiple calls to this function
- * @retval num Number of message in the set
+ * @retval num Messages in the 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.
+ * @note Headers must be in SORT_ORDER. See imap_exec_msgset() for args.
+ * Pos is an opaque pointer a la strtok(). It should be 0 at first call.
  */
 static int make_msg_set(struct ImapData *idata, struct Buffer *buf, int flag,
                         bool changed, bool invert, int *pos)
@@ -511,7 +511,7 @@ static int compile_search(struct Context *ctx, const struct Pattern *pat, struct
  * @param src   Source buffer
  * @param start Starting offset into string
  * @param dlen  Destination buffer length
- * @retval n Length of the common string
+ * @retval num Length of the common string
  *
  * Trim dest to the length of the longest prefix it shares with src.
  */
@@ -767,8 +767,10 @@ void imap_logout_all(void)
  * @retval  0 Success
  * @retval -1 Failure
  *
- * Not explicitly buffered, relies on FILE buffering. NOTE: strips `\r` from
- * `\r\n`.  Apparently even literals use `\r\n`-terminated strings ?!
+ * Not explicitly buffered, relies on FILE buffering.
+ *
+ * @note Strips `\r` from `\r\n`.
+ *       Apparently even literals use `\r\n`-terminated strings ?!
  */
 int imap_read_literal(FILE *fp, struct ImapData *idata, unsigned long bytes,
                       struct Progress *pbar)
@@ -1163,8 +1165,8 @@ bool imap_has_flag(struct ListHead *flag_list, const char *flag)
  * @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
- * @retval n  Number of matched messages
- * @retval -1 Failure
+ * @retval num 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
@@ -1245,7 +1247,8 @@ out:
  *
  * Update the IMAP server to reflect the flags for a single message before
  * performing a "UID COPY".
- * NOTE: This does not sync the "deleted" flag state, because it is not
+ *
+ * @note This does not sync the "deleted" flag state, because it is not
  *       desirable to propagate that flag into the copy.
  */
 int imap_sync_message_for_copy(struct ImapData *idata, struct Header *hdr,
@@ -1420,9 +1423,7 @@ int imap_check(struct ImapData *idata, int force)
 /**
  * imap_buffy_check - Check for new mail in subscribed folders
  * @param check_stats Check for message stats too
- * @retval 0   Failure
- *
- * @note Returns 0 on failure
+ * @retval 0 Failure
  *
  * Given a list of mailboxes rather than called once for each so that it can
  * batch the commands and save on round trips. Returns number of mailboxes with
diff --git a/imap/message.c b/imap/message.c
index bf5a3424b..220c8d78d 100644
--- a/imap/message.c
+++ b/imap/message.c
@@ -114,8 +114,8 @@ static struct BodyCache *msg_cache_open(struct ImapData *idata)
  * msg_cache_get - Get the message cache entry for an email
  * @param idata Server data
  * @param h     Email header
- * @retval FILE* Success, handle of cache entry
- * @retval NULL  Failure
+ * @retval ptr  Success, handle of cache entry
+ * @retval NULL Failure
  */
 static FILE *msg_cache_get(struct ImapData *idata, struct Header *h)
 {
@@ -133,8 +133,8 @@ static FILE *msg_cache_get(struct ImapData *idata, struct Header *h)
  * msg_cache_put - Put an email into the message cache
  * @param idata Server data
  * @param h     Email header
- * @retval FILE* Success, handle of cache entry
- * @retval NULL  Failure
+ * @retval ptr  Success, handle of cache entry
+ * @retval NULL Failure
  */
 static FILE *msg_cache_put(struct ImapData *idata, struct Header *h)
 {
diff --git a/imap/util.c b/imap/util.c
index a7f8b5760..2328beca1 100644
--- a/imap/util.c
+++ b/imap/util.c
@@ -213,7 +213,7 @@ void imap_clean_path(char *path, size_t plen)
  * @param path Path for the header cache file
  * @param dest Buffer for result
  * @param dlen Length of buffer
- * @retval num Number of chars written to dest
+ * @retval num Chars written to dest
  */
 static int imap_hcache_namer(const char *path, char *dest, size_t dlen)
 {
@@ -573,7 +573,7 @@ void imap_error(const char *where, const char *msg)
 
 /**
  * imap_new_idata - Allocate and initialise a new ImapData structure
- * @retval NULL on failure (no mem)
+ * @retval NULL Failure (no mem)
  * @retval ptr New ImapData
  */
 struct ImapData *imap_new_idata(void)
diff --git a/init.c b/init.c
index 23a7c8ecc..eeb92dbae 100644
--- a/init.c
+++ b/init.c
@@ -229,8 +229,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
- * @retval -1 on error
- * @retval >0 on success
+ * @retval -1 Error
+ * @retval >0 Success
  */
 int mutt_option_index(const char *s)
 {
diff --git a/main.c b/main.c
index 7a0be7a54..15a71e5f5 100644
--- a/main.c
+++ b/main.c
@@ -230,8 +230,8 @@ static int get_user_info(void)
  * @param argc Number of command line arguments
  * @param argv List of command line arguments
  * @param envp Copy of the environment
- * @retval 0 on success
- * @retval 1 on error
+ * @retval 0 Success
+ * @retval 1 Error
  */
 int main(int argc, char *argv[], char *envp[])
 {
diff --git a/mutt/address.c b/mutt/address.c
index 4879a154c..eec2b1f7b 100644
--- a/mutt/address.c
+++ b/mutt/address.c
@@ -779,7 +779,7 @@ struct Address *mutt_addr_append(struct Address **a, struct Address *b, bool pru
 /**
  * mutt_addr_valid_msgid - Is this a valid Message ID?
  * @param msgid Message ID
- * @retval bool True if it is valid
+ * @retval true It is a valid message ID
  *
  * Incomplete. Only used to thwart the APOP MD5 attack (#2846).
  */
diff --git a/mutt/base64.c b/mutt/base64.c
index b94fb1521..901a25aed 100644
--- a/mutt/base64.c
+++ b/mutt/base64.c
@@ -75,7 +75,7 @@ const int Index64[128] = {
  * @param cin  Input  buffer for the raw bytes
  * @param len  Length of the input buffer
  * @param olen Length of the output buffer
- * @retval n Length of the string written to the output buffer
+ * @retval num 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
@@ -119,8 +119,8 @@ size_t mutt_b64_encode(char *out, const char *cin, size_t len, size_t olen)
  * mutt_b64_decode - 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
- * @retval n Number of bytes written on success
- * @retval -1 on error
+ * @retval num Success, bytes written
+ * @retval -1  Error
  *
  * This function performs base64 decoding. The resulting buffer is NOT
  * null-terminated. If the input buffer contains invalid base64 characters,
diff --git a/mutt/buffer.c b/mutt/buffer.c
index 6ef5562a6..51ca49e64 100644
--- a/mutt/buffer.c
+++ b/mutt/buffer.c
@@ -228,7 +228,7 @@ size_t mutt_buffer_addch(struct Buffer *buf, char c)
 /**
  * mutt_buffer_is_empty - Is the Buffer empty?
  * @param buf Buffer to inspect
- * @retval bool True, if Buffer is empty
+ * @retval true Buffer is empty
  */
 bool mutt_buffer_is_empty(const struct Buffer *buf)
 {
diff --git a/mutt/charset.c b/mutt/charset.c
index 23fd6bef9..e01285569 100644
--- a/mutt/charset.c
+++ b/mutt/charset.c
@@ -363,7 +363,8 @@ out:
  * mutt_ch_chscmp - Are the names of two character sets equivalent?
  * @param cs1 First character set
  * @param cs2 Second character set
- * @retval num true if the names are equivalent
+ * @retval 1 Names are equivalent
+ * @retval 0 Names differ 
  *
  * Charsets may have extensions that mutt_ch_canonical_charset() leaves intact;
  * we expect 'cs2' to originate from neomutt code, not user input (i.e. 'cs2'
@@ -432,8 +433,8 @@ char *mutt_ch_get_langinfo_charset(void)
  * @param pat     Pattern to match
  * @param replace Replacement string
  * @param err     Buffer for error message
- * @retval true, lookup added to list
- * @retval false, Regex string was invalid
+ * @retval true  Lookup added to list
+ * @retval false Regex string was invalid
  *
  * Add a regex for a character set and a replacement name.
  */
@@ -514,9 +515,13 @@ const char *mutt_ch_charset_lookup(const char *chs)
  * constant, or some value provided by the user; MUTT_ICONV_HOOK_FROM should be
  * used only when fromcode is unsure, taken from a possibly wrong incoming MIME
  * label, or such. Misusing MUTT_ICONV_HOOK_FROM leads to unwanted interactions
- * in some setups. Note: By design charset-hooks should never be, and are never,
- * applied to tocode. Highlight note: The top-well-named MUTT_ICONV_HOOK_FROM
- * acts on charset-hooks, not at all on iconv-hooks.
+ * in some setups.
+ *
+ * @note By design charset-hooks should never be, and are never, applied
+ * to tocode.
+ *
+ * @note The top-well-named MUTT_ICONV_HOOK_FROM acts on charset-hooks,
+ * not at all on iconv-hooks.
  */
 iconv_t mutt_ch_iconv_open(const char *tocode, const char *fromcode, int flags)
 {
@@ -565,7 +570,7 @@ iconv_t mutt_ch_iconv_open(const char *tocode, const char *fromcode, int flags)
  * @param[in]     inrepls      Input replacement characters
  * @param[in]     outrepl      Output replacement characters
  * @param[out]    iconverrno   Errno if iconv() fails, 0 if it succeeds
- * @retval num Number of characters converted
+ * @retval num Characters converted
  *
  * Like iconv, but keeps going even when the input is invalid
  * If you're supplying inrepls, the source charset should be stateless;
@@ -726,7 +731,7 @@ int mutt_ch_convert_string(char **ps, const char *from, const char *to, int flag
  * mutt_ch_check_charset - Does iconv understand a character set?
  * @param cs     Character set to check
  * @param strict Check strictly by using iconv
- * @retval bool true if character set is valid
+ * @retval true Character set is valid
  *
  * If `strict` is false, then finding a matching character set in
  * #PreferredMimeNames will be enough.
@@ -873,7 +878,7 @@ int mutt_ch_fgetconv(struct FgetConv *fc)
  * @param buf    Buffer for result
  * @param buflen Length of buffer
  * @param fc     FgetConv handle
- * @retval ptr  Result buffer on success
+ * @retval ptr  Success, result buffer
  * @retval NULL Error
  *
  * Read a file into a buffer, converting the character set as it goes.
diff --git a/mutt/date.c b/mutt/date.c
index 9f492c430..c0aa89cb6 100644
--- a/mutt/date.c
+++ b/mutt/date.c
@@ -122,7 +122,7 @@ static const struct Tz TimeZones[] = {
  * compute_tz - Calculate the number of seconds east of UTC
  * @param g   Local time
  * @param utc UTC time
- * @retval number Seconds east of UTC
+ * @retval num Seconds east of UTC
  *
   * returns the seconds east of UTC given 'g' and its corresponding gmtime()
  * representation
@@ -413,7 +413,7 @@ int mutt_date_check_month(const char *s)
 /**
  * mutt_date_is_day_name - Is the string a valid day name
  * @param s String to check
- * @retval boolean
+ * @retval true It's a valid day name
  *
  * @note Only the first three characters are checked
  * @note The comparison is case insensitive
@@ -596,7 +596,7 @@ time_t mutt_date_parse_date(const char *s, struct Tz *tz_out)
  * @param buf       Buffer to store the results
  * @param buflen    Length of buffer
  * @param timestamp Time to format
- * @retval int Number of characters written to buf
+ * @retval num Characters written to buf
  *
  * Caller should provide a buffer of at least 27 bytes.
  */
@@ -617,7 +617,7 @@ int mutt_date_make_imap(char *buf, size_t buflen, time_t timestamp)
  * @param buf       Buffer to store the results
  * @param buflen    Length of buffer
  * @param timestamp Time to format
- * @retval int Number of characters written to buf
+ * @retval num Characters written to buf
  *
  * e.g., Mar 17 16:40:46 2016 UTC. The time is always in UTC.
  *
@@ -634,8 +634,8 @@ int mutt_date_make_tls(char *buf, size_t buflen, time_t timestamp)
 /**
  * mutt_date_parse_imap - Parse date of the form: DD-MMM-YYYY HH:MM:SS +ZZzz
  * @param s Date in string form
- * @retval 0      Error
- * @retval time_t Unix time
+ * @retval num Unix time
+ * @retval 0   Error
  */
 time_t mutt_date_parse_imap(char *s)
 {
diff --git a/mutt/file.c b/mutt/file.c
index 025931522..b58cec6b6 100644
--- a/mutt/file.c
+++ b/mutt/file.c
@@ -64,7 +64,7 @@ static const char safe_chars[] =
  * compare_stat - Compare the struct stat's of two files/dirs
  * @param osb struct stat of the first file/dir
  * @param nsb struct stat of the second file/dir
- * @retval boolean
+ * @retval true They match
  *
  * This compares the device id (st_dev), inode number (st_ino) and special id
  * (st_rdev) of the files/dirs.
@@ -662,7 +662,7 @@ char *mutt_file_read_line(char *s, size_t *size, FILE *fp, int *line, int flags)
  * @param d Buffer for the result
  * @param l Length of buffer
  * @param f String to convert
- * @retval num Number of bytes written to the buffer
+ * @retval num Bytes written to the buffer
  *
  * From the Unix programming FAQ by way of Liviu.
  */
@@ -709,7 +709,7 @@ size_t mutt_file_quote_filename(char *d, size_t l, const char *f)
  * @param fname    Filename
  * @param fnamelen Filename length
  * @retval NULL Error
- * @retval ptr  Pointer to \a dst on success
+ * @retval ptr  Success, pointer to \a dst
  *
  * Write the concatenated pathname (dir + "/" + fname) into dst.
  * The slash is omitted when dir or fname is of 0 length.
@@ -938,7 +938,7 @@ void mutt_file_touch_atime(int f)
  * mutt_file_chmod - Set permissions of a file
  * @param path Filename
  * @param mode the permissions to set
- * @retval int same as chmod(2)
+ * @retval num Same as chmod(2)
  *
  * This is essentially chmod(path, mode), see chmod(2).
  */
@@ -951,7 +951,7 @@ int mutt_file_chmod(const char *path, mode_t mode)
  * mutt_file_chmod_add - Add permissions to a file
  * @param path Filename
  * @param mode the permissions to add
- * @retval int same as chmod(2)
+ * @retval num Same as chmod(2)
  * @see   mutt_file_chmod_add_stat()
  *
  * Adds the given permissions to the file. Permissions not mentioned in mode
@@ -973,7 +973,7 @@ int mutt_file_chmod_add(const char *path, mode_t mode)
  * @param path Filename
  * @param mode the permissions to add
  * @param st   struct stat for the file (optional)
- * @retval int same as chmod(2)
+ * @retval num Same as chmod(2)
  * @see   mutt_file_chmod_add()
  *
  * Same as mutt_file_chmod_add() but saves a system call to stat() if a
@@ -1003,7 +1003,7 @@ int mutt_file_chmod_add_stat(const char *path, mode_t mode, struct stat *st)
  * mutt_file_chmod_rm - Remove permissions from a file
  * @param path Filename
  * @param mode the permissions to remove
- * @retval int same as chmod(2)
+ * @retval num Same as chmod(2)
  * @see   mutt_file_chmod_rm_stat()
  *
  * Removes the given permissions from the file. Permissions not mentioned in
@@ -1025,7 +1025,7 @@ int mutt_file_chmod_rm(const char *path, mode_t mode)
  * @param path Filename
  * @param mode the permissions to remove
  * @param st   struct stat for the file (optional)
- * @retval int same as chmod(2)
+ * @retval num Same as chmod(2)
  * @see   mutt_file_chmod_rm()
  *
  * Same as mutt_file_chmod_rm() but saves a system call to stat() if a non-NULL
@@ -1056,8 +1056,8 @@ int mutt_file_chmod_rm_stat(const char *path, mode_t mode, struct stat *st)
  * @param fd      File descriptor to file
  * @param excl    If set, try to lock exclusively
  * @param timeout Retry after this time
- * @retval 0 on success
- * @retval -1 on failure
+ * @retval  0 Success
+ * @retval -1 Failure
  *
  * The type of file locking depends on how NeoMutt was compiled.
  * It could use fcntl() or flock() to perform the locking.
@@ -1220,7 +1220,7 @@ void mutt_file_unlink_empty(const char *path)
  * @retval 2 New file already exists
  * @retval 3 Some other error
  *
- * note on access(2) use: No dangling symlink problems here due to
+ * @note on access(2) use No dangling symlink problems here due to
  * mutt_file_fopen().
  */
 int mutt_file_rename(char *oldfile, char *newfile)
@@ -1251,10 +1251,11 @@ int mutt_file_rename(char *oldfile, char *newfile)
  * mutt_file_to_absolute_path - Convert relative filepath to an absolute path
  * @param path      Relative path
  * @param reference Absolute path that \a path is relative to
- * @retval true on success
- * @retval false otherwise
+ * @retval true  Success
+ * @retval false Failure
  *
  * Use POSIX functions to convert a path to absolute, relatively to another path
+ *
  * @note \a path should be at least of PATH_MAX length
  */
 int mutt_file_to_absolute_path(char *path, const char *reference)
@@ -1324,9 +1325,9 @@ char *mutt_file_read_keyword(const char *file, char *buffer, size_t buflen)
 /**
  * mutt_file_check_empty - Is the mailbox empty
  * @param path Path to mailbox
- * @retval 1 mailbox is not empty
- * @retval 0 mailbox is empty
- * @retval -1 on error
+ * @retval  1 Mailbox is not empty
+ * @retval  0 Mailbox is empty
+ * @retval -1 Error
  */
 int mutt_file_check_empty(const char *path)
 {
diff --git a/mutt/list.c b/mutt/list.c
index 66ae30737..569cc8a85 100644
--- a/mutt/list.c
+++ b/mutt/list.c
@@ -156,7 +156,7 @@ void mutt_list_clear(struct ListHead *h)
  * mutt_list_match - Is the string in the list (see notes)
  * @param s String to match
  * @param h Head of the List
- * @return true String matches a List item (or List contains "*")
+ * @retval true String matches a List item (or List contains "*")
  *
  * This is a very specific function.  It searches a List of strings looking for
  * a match.  If the list contains a string "*", then it match any input string.
@@ -180,7 +180,7 @@ bool mutt_list_match(const char *s, struct ListHead *h)
  * mutt_list_compare - Compare two string lists
  * @param ah First string list
  * @param bh Second string list
- * @retval bool True if lists are identical
+ * @retval true Lists are identical
  *
  * To be identical, the lists must both be the same length and contain the same
  * strings.  Two empty lists are identical.
diff --git a/mutt/logging.c b/mutt/logging.c
index e3f031dc3..37a8b47cf 100644
--- a/mutt/logging.c
+++ b/mutt/logging.c
@@ -273,7 +273,7 @@ int log_disp_file(time_t stamp, const char *file, int line,
 /**
  * log_queue_add - Add a LogLine to the queue
  * @param ll LogLine to add
- * @retval num Number of entries in the queue
+ * @retval num Entries in the queue
  *
  * If #LogQueueMax is non-zero, the queue will be limited to this many items.
  */
@@ -346,7 +346,7 @@ void log_queue_flush(log_dispatcher_t disp)
 /**
  * log_queue_save - Save the contents of the queue to a temporary file
  * @param fp Open file handle
- * @retval num Number of lines written to the file
+ * @retval num Lines written to the file
  *
  * The queue is written to a temporary file.  The format is:
  * * `[HH:MM:SS]<LEVEL> FORMATTED-MESSAGE`
diff --git a/mutt/mapping.c b/mutt/mapping.c
index 2d539ba76..55fb9b645 100644
--- a/mutt/mapping.c
+++ b/mutt/mapping.c
@@ -35,7 +35,7 @@
  * mutt_map_get_name - Lookup a string for a constant
  * @param val ID to locate in map
  * @param map NULL-terminated map of strings and constants
- * @retval str  String matching ID
+ * @retval ptr  String matching ID
  * @retval NULL Error, or ID not found
  */
 const char *mutt_map_get_name(int val, const struct Mapping *map)
diff --git a/mutt/mbyte.c b/mutt/mbyte.c
index ea5237510..3b2953ec5 100644
--- a/mutt/mbyte.c
+++ b/mutt/mbyte.c
@@ -46,10 +46,10 @@ bool OptLocales; /**< (pseudo) set if user has valid locale definition */
  * mutt_mb_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
- * @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)
+ * @retval num Bytes in the first (multibyte) character of input consumes
+ * @retval <0  Conversion error
+ * @retval =0  End of input
+ * @retval >0  Length (bytes)
  */
 int mutt_mb_charlen(const char *s, int *width)
 {
@@ -73,8 +73,8 @@ int mutt_mb_charlen(const char *s, int *width)
  * @param name   String to be converted
  * @param buf    Buffer for the result
  * @param buflen Size of the buffer
- * @retval 1 on Success
- * @retval 0 on Failure
+ * @retval 1 Success
+ * @retval 0 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
@@ -131,7 +131,7 @@ bool mutt_mb_get_initials(const char *name, char *buf, int buflen)
  * @param str     String to measure
  * @param col     Display column (used for expanding tabs)
  * @param display will this be displayed to the user?
- * @retval int Strings width in screen columns
+ * @retval num Strings width in screen columns
  *
  * This is like wcwidth(), but gets const char* not wchar_t*.
  */
@@ -172,7 +172,7 @@ int mutt_mb_width(const char *str, int col, bool display)
 /**
  * mutt_mb_wcwidth - Measure the screen width of a character
  * @param wc Character to examine
- * @retval int Width in screen columns
+ * @retval num Width in screen columns
  */
 int mutt_mb_wcwidth(wchar_t wc)
 {
@@ -190,7 +190,7 @@ int mutt_mb_wcwidth(wchar_t wc)
  * mutt_mb_wcswidth - Measure the screen width of a string
  * @param s String to measure
  * @param n Length of string in characters
- * @retval int Width in screen columns
+ * @retval num Width in screen columns
  */
 int mutt_mb_wcswidth(const wchar_t *s, size_t n)
 {
@@ -205,7 +205,7 @@ int mutt_mb_wcswidth(const wchar_t *s, size_t n)
  * @param s String being displayed
  * @param n Length of string in characters
  * @param w1 Width limit
- * @retval size_t Number of chars to skip
+ * @retval num Chars to skip
  *
  * Given a string and a width, determine how many characters from the
  * beginning of the string should be skipped so that the string fits.
@@ -280,7 +280,7 @@ void mutt_mb_wcstombs(char *dest, size_t dlen, const wchar_t *src, size_t slen)
  * @param pwbuflen Length of the result buffer
  * @param i        Starting index into the result buffer
  * @param buf      String to convert
- * @retval size_t First character after the result
+ * @retval num First character after the result
  */
 size_t mutt_mb_mbstowcs(wchar_t **pwbuf, size_t *pwbuflen, size_t i, char *buf)
 {
diff --git a/mutt/regex.c b/mutt/regex.c
index 87230e8d7..348059e05 100644
--- a/mutt/regex.c
+++ b/mutt/regex.c
@@ -588,7 +588,7 @@ struct ReplaceList *mutt_replacelist_new(void)
  * mutt_replacelist_remove - Remove a pattern from a list
  * @param rl  ReplaceList to modify
  * @param pat Pattern to remove
- * @retval num Number of matching patterns removed
+ * @retval num Matching patterns removed
  */
 int mutt_replacelist_remove(struct ReplaceList **rl, const char *pat)
 {
diff --git a/mutt/rfc2047.c b/mutt/rfc2047.c
index e9ef6d89f..a11cd4944 100644
--- a/mutt/rfc2047.c
+++ b/mutt/rfc2047.c
@@ -58,7 +58,7 @@ typedef size_t (*encoder_t)(char *str, const char *buf, size_t buflen, const cha
  * @param buf    Buffer for result
  * @param buflen Length of buffer
  * @param tocode Character encoding
- * @retval num Number of bytes written to buffer
+ * @retval num Bytes written to buffer
  */
 static size_t b_encoder(char *str, const char *buf, size_t buflen, const char *tocode)
 {
@@ -96,7 +96,7 @@ static size_t b_encoder(char *str, const char *buf, size_t buflen, const char *t
  * @param buf    Buffer for result
  * @param buflen Length of buffer
  * @param tocode Character encoding
- * @retval num Number of bytes written to buffer
+ * @retval num Bytes written to buffer
  */
 static size_t q_encoder(char *str, const char *buf, size_t buflen, const char *tocode)
 {
@@ -308,7 +308,7 @@ static size_t encode_block(char *str, char *buf, size_t buflen, const char *from
  * @param tocode   New encoding
  * @param encoder  Encoding function
  * @param wlen     Number of characters converted
- * @retval num Number of bytes that can be converted
+ * @retval num Bytes that can be converted
  *
  * Discover how much of the data (d, dlen) can be converted into a single
  * encoded word. Return how much data can be converted, and set the length
diff --git a/mutt/string.c b/mutt/string.c
index 560f9c2d3..85edab6c1 100644
--- a/mutt/string.c
+++ b/mutt/string.c
@@ -217,9 +217,8 @@ int mutt_str_atoi(const char *str, int *dst)
  * @retval -1 Invalid input
  * @retval -2 Input out of range
  *
- * @note
- * This function's return value differs from the other functions.
- * They return -1 if there is input beyond the number.
+ * @note This function's return value differs from the other functions.
+ *       They return -1 if there is input beyond the number.
  */
 int mutt_str_atoui(const char *str, unsigned int *dst)
 {
@@ -248,9 +247,8 @@ int mutt_str_atoui(const char *str, unsigned int *dst)
  * @retval  0 Successful conversion
  * @retval -1 Invalid input
  *
- * @note
- * This function's return value differs from the other functions.
- * They return -1 if there is input beyond the number.
+ * @note This function's return value differs from the other functions.
+ *       They return -1 if there is input beyond the number.
  */
 int mutt_str_atoul(const char *str, unsigned long *dst)
 {
@@ -634,7 +632,7 @@ void mutt_str_remove_trailing_ws(char *s)
  * @param dest  Buffer for the result
  * @param src   String to copy
  * @param dsize Destination buffer size
- * @retval len Destination string length
+ * @retval num Destination string length
  */
 size_t mutt_str_strfcpy(char *dest, const char *src, size_t dsize)
 {
@@ -667,7 +665,7 @@ char *mutt_str_skip_email_wsp(const char *s)
 /**
  * mutt_str_is_email_wsp - Is this a whitespace character (for an email header)
  * @param c Character to test
- * @retval boolean
+ * @retval true It is whitespcae
  */
 bool mutt_str_is_email_wsp(char c)
 {
@@ -680,7 +678,7 @@ bool mutt_str_is_email_wsp(char c)
  * @param src   String to copy
  * @param n     Maximum number of characters to copy
  * @param dsize Destination buffer size
- * @retval len Destination string length
+ * @retval num Destination string length
  */
 size_t mutt_str_strnfcpy(char *dest, const char *src, size_t n, size_t dsize)
 {
@@ -862,7 +860,7 @@ int mutt_str_word_casecmp(const char *a, const char *b)
  * mutt_str_is_ascii - Is a string ASCII (7-bit)?
  * @param p   String to examine
  * @param len Length of string
- * @retval bool True if there are no 8-bit chars
+ * @retval true There are no 8-bit chars
  */
 bool mutt_str_is_ascii(const char *p, size_t len)
 {
diff --git a/mutt_notmuch.c b/mutt_notmuch.c
index 2643fdc45..a87edb285 100644
--- a/mutt_notmuch.c
+++ b/mutt_notmuch.c
@@ -152,7 +152,7 @@ static void free_hdrdata(struct NmHdrData *data)
 
 /**
  * free_ctxdata - Free data attached to the context
- * @param data A mailbox CONTEXT
+ * @param data Notmuch data
  *
  * The nm_ctxdata struct stores global Notmuch data, such as the connection to
  * the database.  This function will close the database, free the resources and
@@ -211,7 +211,7 @@ static struct NmCtxData *new_ctxdata(const char *uri)
 
 /**
  * init_context - Add Notmuch data to the Context
- * @param ctx A mailbox CONTEXT
+ * @param ctx Mailbox
  * @retval  0 Success
  * @retval -1 Error Bad format
  *
@@ -384,17 +384,17 @@ static bool windowed_query_from_query(const char *query, char *buf, size_t bufle
 
 /**
  * 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
- * @retval string Containing a notmuch search query
- * @retval NULL   If none can be generated
+ * @param data   Notmuch data
+ * @param window If true enable application of the window on the search string
+ * @retval ptr  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
  * is valid.
  *
- * As a note, the window parameter here is here to decide contextually whether
- * we want to return a search query with window applied (for the actual search
+ * @note The window parameter here is here to decide contextually whether we
+ * want to return a search query with window applied (for the actual search
  * result in buffy) or not (for the count in the sidebar). It is not aimed at
  * enabling/disabling the feature.
  */
@@ -815,7 +815,7 @@ static void deinit_header(struct Header *h)
 /**
  * nm2mutt_message_id - converts notmuch message Id to neomutt message Id
  * @param id Notmuch ID to convert
- * @retval string NeoMutt message ID
+ * @retval ptr NeoMutt message ID
  *
  * Caller must free the NeoMutt Message ID
  */
@@ -1752,10 +1752,13 @@ void nm_query_window_backward(void)
 
 /**
  * nm_edit_message_tags - Prompt new messages tags
- *
- * @retval -1: error
- * @retval 0: no valid user input
- * @retval 1: buf set
+ * @param ctx    Mailbox
+ * @param tags   Existing tags (UNUSED)
+ * @param buf    Buffer for message tags
+ * @param buflen Length of buffer
+ * @retval -1 Error
+ * @retval 0  No valid user input
+ * @retval 1  Buffer set
  */
 static int nm_edit_message_tags(struct Context *ctx, const char *tags, char *buf, size_t buflen)
 {
@@ -2096,7 +2099,7 @@ done:
 
 /**
  * nm_open_mailbox - Open a notmuch virtual mailbox
- * @param ctx A mailbox CONTEXT
+ * @param ctx Mailbox
  * @retval  0 Success
  * @retval -1 Error
  */
@@ -2150,7 +2153,7 @@ static int nm_open_mailbox(struct Context *ctx)
 
 /**
  * nm_close_mailbox - Close a notmuch virtual mailbox
- * @param ctx A mailbox CONTEXT
+ * @param ctx Mailbox
  * @retval  0 Success
  * @retval -1 Error
  */
@@ -2177,13 +2180,13 @@ static int nm_close_mailbox(struct Context *ctx)
 
 /**
  * nm_check_mailbox - Check a notmuch mailbox for new mail
- * @param ctx         A mailbox CONTEXT
+ * @param ctx         Mailbox
  * @param index_hint  Remember our place in the index
  * @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
+ * @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)
 {
@@ -2305,7 +2308,7 @@ done:
 
 /**
  * nm_sync_mailbox - Sync a notmuch mailbox
- * @param ctx        A mailbox CONTEXT
+ * @param ctx        Mailbox
  * @param index_hint Remember our place in the index
  */
 static int nm_sync_mailbox(struct Context *ctx, int *index_hint)
@@ -2390,7 +2393,7 @@ static int nm_sync_mailbox(struct Context *ctx, int *index_hint)
 
 /**
  * nm_open_message - Open a message from a notmuch mailbox
- * @param ctx   A mailbox CONTEXT
+ * @param ctx   Mailbox
  * @param msg   Message to open
  * @param msgno Index of message to open
  * @retval 0 Success
@@ -2419,7 +2422,7 @@ 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 ctx Mailbox
  * @param msg Message to close
  * @retval 0 Success
  * @retval 1 Error
diff --git a/mutt_window.c b/mutt_window.c
index 0a144e83f..2135d3484 100644
--- a/mutt_window.c
+++ b/mutt_window.c
@@ -200,7 +200,7 @@ int mutt_window_mvaddstr(struct MuttWindow *win, int row, int col, const char *s
  * @param col Column to move to
  * @param fmt printf format string
  * @param ... printf arguments
- * @retval num Success, number of characters written
+ * @retval num Success, characters written
  * @retval ERR Error, move failed
  */
 int mutt_window_mvprintw(struct MuttWindow *win, int row, int col, const char *fmt, ...)
diff --git a/muttlib.c b/muttlib.c
index eaa30c6aa..e4001a047 100644
--- a/muttlib.c
+++ b/muttlib.c
@@ -622,9 +622,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
- * @retval  0 on success
- * @retval -1 on abort
- * @retval  1 on error
+ * @retval  0 Success
+ * @retval -1 Abort
+ * @retval  1 Error
  */
 int mutt_check_overwrite(const char *attname, const char *path, char *fname,
                          size_t flen, int *append, char **directory)
@@ -1486,7 +1486,7 @@ void mutt_get_parent_path(char *output, char *path, size_t olen)
 /**
  * mutt_realpath - resolve path, unraveling symlinks
  * @param buf Buffer containing path
- * @retval len String length of resolved path
+ * @retval num String length of resolved path
  * @retval 0   Error, buf is not overwritten
  *
  * Resolve and overwrite the path in buf.
diff --git a/mx.c b/mx.c
index bcde93804..8d4157ce1 100644
--- a/mx.c
+++ b/mx.c
@@ -116,7 +116,7 @@ static bool mutt_is_spool(const char *str)
 /**
  * mx_is_imap - Is this an IMAP mailbox
  * @param p Mailbox string to test
- * return boolean
+ * @retval true It is an IMAP mailbox
  */
 bool mx_is_imap(const char *p)
 {
@@ -141,7 +141,7 @@ bool mx_is_imap(const char *p)
 /**
  * mx_is_pop - Is this a POP mailbox
  * @param p Mailbox string to test
- * return boolean
+ * @retval true It is a POP mailbox
  */
 bool mx_is_pop(const char *p)
 {
@@ -162,7 +162,7 @@ bool mx_is_pop(const char *p)
 /**
  * mx_is_nntp - Is this an NNTP mailbox
  * @param p Mailbox string to test
- * return boolean
+ * @retval true It is an NNTP mailbox
  */
 bool mx_is_nntp(const char *p)
 {
@@ -181,9 +181,9 @@ bool mx_is_nntp(const char *p)
 
 #ifdef USE_NOTMUCH
 /**
- * mx_is_notmuch - Is this a notmuch mailbox
+ * mx_is_notmuch - Is this a Notmuch mailbox
  * @param p Mailbox string to test
- * return boolean
+ * @retval true It is a Notmuch mailbox
  */
 bool mx_is_notmuch(const char *p)
 {
@@ -203,9 +203,8 @@ bool mx_is_notmuch(const char *p)
 /**
  * mx_get_magic - Identify the type of mailbox
  * @param path Mailbox path to test
- * return
- * * -1 Error, can't identify mailbox
- * * >0 Success, e.g. #MUTT_IMAP
+ * @retval -1 Error, can't identify mailbox
+ * @retval >0 Success, e.g. #MUTT_IMAP
  */
 int mx_get_magic(const char *path)
 {
@@ -524,7 +523,7 @@ void mx_fastclose_mailbox(struct Context *ctx)
   }
 
   /* never announce that a mailbox we've just left has new mail. #3290
-   * XXX: really belongs in mx_close_mailbox, but this is a nice hook point */
+   * TODO: really belongs in mx_close_mailbox, but this is a nice hook point */
   if (!ctx->peekonly)
     mutt_buffy_setnotified(ctx->path);
 
@@ -991,8 +990,8 @@ void mx_update_tables(struct Context *ctx, bool committing)
  * mx_sync_mailbox - Save changes to mailbox
  * @param[in]  ctx        Context
  * @param[out] index_hint Currently selected mailbox
- * @retval 0 on success
- * @retval -1 on error
+ * @retval  0 Success
+ * @retval -1 Error
  */
 int mx_sync_mailbox(struct Context *ctx, int *index_hint)
 {
@@ -1119,10 +1118,9 @@ int mx_sync_mailbox(struct Context *ctx, int *index_hint)
 /**
  * mx_open_new_message - Open a new message
  * @param dest  Destination mailbox
- * @param hdr   Message being copied (required for maildir support, because
- *              the filename depends on the message flags)
+ * @param hdr   Message being copied (required for maildir support, because the filename depends on the message flags)
  * @param flags Flags, e.g. #MUTT_SET_DRAFT
- * @retval ptr new Message
+ * @retval ptr New Message
  */
 struct Message *mx_open_new_message(struct Context *dest, struct Header *hdr, int flags)
 {
@@ -1229,7 +1227,11 @@ int mx_commit_message(struct Message *msg, struct Context *ctx)
 }
 
 /**
- * mx_close_message - close a pointer to a message
+ * mx_close_message - Close a message
+ * @param ctx Mailbox
+ * @param msg Message to close
+ * @retval  0 Success
+ * @retval -1 Failure
  */
 int mx_close_message(struct Context *ctx, struct Message **msg)
 {
diff --git a/ncrypt/crypt.c b/ncrypt/crypt.c
index bb1069a1c..68d6396ad 100644
--- a/ncrypt/crypt.c
+++ b/ncrypt/crypt.c
@@ -1088,13 +1088,11 @@ int mutt_signed_handler(struct Body *a, struct State *s)
 /**
  * crypt_get_fingerprint_or_id - Get the fingerprint or long key ID
  * @param p       String to examine
- * @param pphint  Start of string to be passed to pgp_add_string_to_hints() or
- *                crypt_add_string_to_hints()
+ * @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
+ * @retval ptr  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.
  *
diff --git a/ncrypt/crypt_gpgme.c b/ncrypt/crypt_gpgme.c
index 3c26294fb..c25add136 100644
--- a/ncrypt/crypt_gpgme.c
+++ b/ncrypt/crypt_gpgme.c
@@ -260,8 +260,8 @@ static const char *crypt_fpr(struct CryptKeyInfo *k)
 /**
  * crypt_fpr_or_lkeyid - Find the fingerprint of a key
  * @param k Key to examine
- * @retval string fingerprint if available
- * @retval string otherwise the long keyid
+ * @retval ptr Fingerprint if available
+ * @retval ptr Otherwise the long keyid
  */
 static const char *crypt_fpr_or_lkeyid(struct CryptKeyInfo *k)
 {
@@ -788,7 +788,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
- * @retval 0 on success
+ * @retval 0 Success
  */
 static int set_signer(gpgme_ctx_t ctx, int for_smime)
 {
@@ -1911,7 +1911,7 @@ restart:
 
 /**
  * pgp_gpgme_decrypt_mime - Decrypt a PGP/MIME message
- * @retval 0 on success
+ * @retval 0 Success
  *
  * The message in FPIN and B and return a new body and the stream in CUR and
  * FPOUT.
@@ -2004,7 +2004,7 @@ bail:
 
 /**
  * smime_gpgme_decrypt_mime - Decrypt a S/MIME message
- * @retval 0 on success
+ * @retval 0 Success
  *
  * The message in FPIN and B and return a new body and
  * the stream in CUR and FPOUT.
diff --git a/ncrypt/pgpinvoke.c b/ncrypt/pgpinvoke.c
index e24d3f06c..521fd0c18 100644
--- a/ncrypt/pgpinvoke.c
+++ b/ncrypt/pgpinvoke.c
@@ -326,8 +326,8 @@ pid_t pgp_invoke_verify_key(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpi
  * @param pgperrfd If `pgperr` is NULL and pgperr is not -1 then pgperr will be used as stderr for the command process
  * @param keyring  Keyring type, e.g. #PGP_SECRING
  * @param hints    Match keys to these strings
- * @retval n  pid of the created process
- * @retval -1 on any error creating pipes or forking
+ * @retval num  PID of the created process
+ * @retval -1   Error creating pipes or forking
  */
 pid_t pgp_invoke_list_keys(FILE **pgpin, FILE **pgpout, FILE **pgperr,
                            int pgpinfd, int pgpoutfd, int pgperrfd,
diff --git a/nntp.c b/nntp.c
index 77d844b1b..841fa7b09 100644
--- a/nntp.c
+++ b/nntp.c
@@ -1006,7 +1006,11 @@ static void nntp_parse_xref(struct Context *ctx, struct Header *hdr)
 }
 
 /**
- * fetch_tempfile - Write line to temporarily file
+ * fetch_tempfile - Write line to temporary file
+ * @param line Text to write
+ * @param data FILE pointer
+ * @retval  0 Success
+ * @retval -1 Failure
  */
 static int fetch_tempfile(char *line, void *data)
 {
diff --git a/pattern.c b/pattern.c
index 845e0a63c..e14be5902 100644
--- a/pattern.c
+++ b/pattern.c
@@ -1830,7 +1830,7 @@ 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
  * @retval ptr  Success, email found
- * @retval NULL On error
+ * @retval NULL Error
  */
 static struct MuttThread *top_of_thread(struct Header *h)
 {
diff --git a/pop_lib.c b/pop_lib.c
index 298c28109..47d0507d7 100644
--- a/pop_lib.c
+++ b/pop_lib.c
@@ -557,8 +557,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
- * @retval 0 on success
- * @retval -1 on error
+ * @retval  0 Success
+ * @retval -1 Error
  */
 static int check_uidl(char *line, void *data)
 {
@@ -589,8 +589,8 @@ static int check_uidl(char *line, void *data)
 /**
  * pop_reconnect - reconnect and verify indexes if connection was lost
  * @param ctx Context
- * @retval 0 on success
- * @retval -1 on error
+ * @retval  0 Success
+ * @retval -1 Error
  */
 int pop_reconnect(struct Context *ctx)
 {
diff --git a/postpone.c b/postpone.c
index 2395d5a39..94d4506bb 100644
--- a/postpone.c
+++ b/postpone.c
@@ -69,7 +69,7 @@ static short UpdateNumPostponed = 0;
  * @param force
  * * 0 Use a cached value if costly to get a fresh count (IMAP)
  * * 1 Force check
- * @retval n Number of postponed messages
+ * @retval num Postponed messages
  */
 int mutt_num_postponed(int force)
 {
@@ -254,8 +254,7 @@ static struct Header *select_msg(void)
  * mutt_get_postponed - Recall a postponed message
  * @param ctx     Context info, used when recalling a message to which we reply
  * @param hdr     envelope/attachment info for recalled message
- * @param cur     if message was a reply, `cur' is set to the message
- *                which `hdr' is in reply to
+ * @param cur     if message was a reply, `cur' is set to the message which `hdr' is in reply to
  * @param fcc     fcc for the recalled message
  * @param fcclen  max length of fcc
  * @retval -1         Error/no messages
@@ -528,8 +527,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.
- * @retval 0 on success
- * @retval -1 on error
+ * @retval  0 Success
+ * @retval -1 Error
  */
 int mutt_prepare_template(FILE *fp, struct Context *ctx, struct Header *newhdr,
                           struct Header *hdr, short resend)
diff --git a/rfc1524.c b/rfc1524.c
index b44a9fb47..bd5866107 100644
--- a/rfc1524.c
+++ b/rfc1524.c
@@ -20,7 +20,10 @@
  * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/* RFC1524 defines a format for the Multimedia Mail Configuration, which is the
+/**
+ * @page rfc1524 RFC1524 Mailcap routines
+ *
+ * RFC1524 defines a format for the Multimedia Mail Configuration, which is the
  * standard mailcap file format under Unix which specifies what external
  * programs should be used to view/compose/edit multimedia files based on
  * content type.
@@ -53,9 +56,6 @@
  * by neomutt, and can probably just be done by piping the message to metamail
  * %n is the integer number of sub-parts in the multipart
  * %F is "content-type filename" repeated for each sub-part
- *
- * In addition, this function returns a 0 if the command works on a file,
- * and 1 if the command works on a pipe.
  */
 int rfc1524_expand_command(struct Body *a, char *filename, char *type, char *command, int clen)
 {
@@ -386,8 +386,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
- * @retval 1 on success. If *entry is not NULL it populates it with the mailcap entry
- * @retval 0 if no matching entry is found
+ * @retval 1 Success. If *entry is not NULL it populates it with the mailcap entry
+ * @retval 0 No matching entry is found
  *
  * opt can be one of: #MUTT_EDIT, #MUTT_COMPOSE, #MUTT_PRINT, #MUTT_AUTOVIEW
  *
diff --git a/safe_asprintf.c b/safe_asprintf.c
index c8ea5fca3..fd7aeff5e 100644
--- a/safe_asprintf.c
+++ b/safe_asprintf.c
@@ -25,11 +25,6 @@
 #include <stdio.h>
 #include "mutt/mutt.h"
 
-/* NOTE: Currently there is no check in configure.ac for vasprintf(3).  the
- * undefined behavior of the error condition makes it difficult to write a safe
- * version using it.
- */
-
 /**
  * safe_asprintf - Wrapper for vasprintf()
  */
diff --git a/send.c b/send.c
index df3c6e2f9..e0a090025 100644
--- a/send.c
+++ b/send.c
@@ -821,8 +821,8 @@ static int envelope_defaults(struct Envelope *env, struct Context *ctx,
  * @param flags  compose mode
  * @param ctx    current mailbox
  * @param cur    current message
- * @retval 0 on success
- * @retval -1 on error
+ * @retval  0 Success
+ * @retval -1 Error
  */
 static int generate_body(FILE *tempfp, struct Header *msg, int flags,
                          struct Context *ctx, struct Header *cur)
diff --git a/sendlib.c b/sendlib.c
index c2b042819..556b87384 100644
--- a/sendlib.c
+++ b/sendlib.c
@@ -968,7 +968,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
- * @retval n MIME type, e.g. #TYPEIMAGE
+ * @retval num 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
diff --git a/sidebar.c b/sidebar.c
index aa7982579..8197dde72 100644
--- a/sidebar.c
+++ b/sidebar.c
@@ -674,8 +674,8 @@ static bool prepare_sidebar(int page_size)
  * draw_divider - Draw a line between the sidebar and the rest of neomutt
  * @param num_rows   Height of the Sidebar
  * @param num_cols   Width of the Sidebar
- * @retval 0 Empty string
- * @retval n Character occupies n screen columns
+ * @retval 0   Empty string
+ * @retval num 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.
@@ -1072,7 +1072,7 @@ void mutt_sb_set_buffystats(const struct Context *ctx)
 
 /**
  * mutt_sb_get_highlight - Get the Buffy that's highlighted in the sidebar
- * @retval string Mailbox path
+ * @retval ptr Mailbox path
  *
  * Get the path of the mailbox that's highlighted in the sidebar.
  */
diff --git a/tags.c b/tags.c
index 1c401ea9e..f86552c44 100644
--- a/tags.c
+++ b/tags.c
@@ -163,8 +163,7 @@ char *driver_tags_get_with_hidden(struct TagHead *head)
  * driver_tags_get_transformed_for - Get transformed tag for a tag name from a header
  * @param[in] name Tag to transform
  * @param[in] head List of tags
- *
- * @return string tag
+ * @retval ptr String tag
  *
  * Return a new allocated string containing all tags separated by space even
  * the hiddens.
diff --git a/thread.c b/thread.c
index c0f5e5a07..ecfbd68f3 100644
--- a/thread.c
+++ b/thread.c
@@ -1066,7 +1066,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
- * @retval n Index into the virtual email table
+ * @retval num 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 d2edf40a2..be9775bd4 100644
--- a/version.c
+++ b/version.c
@@ -334,7 +334,7 @@ static void print_compile_options(struct CompileOptions *co)
 /**
  * rstrip_in_place - Strip a trailing carriage return
  * @param s  String to be modified
- * @retval string The modified string
+ * @retval ptr The modified string
  *
  * The string has its last carriage return set to NUL.
  */