From: Richard Russon <rich@flatcap.org>
Date: Fri, 26 Apr 2019 22:28:37 +0000 (+0100)
Subject: doxy: tidy/standardise lots of comments
X-Git-Tag: 2019-10-25~234^2~5
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f3ff7a77cb94c048d891d7c0a62c1db277f9c72a;p=neomutt

doxy: tidy/standardise lots of comments
---

diff --git a/address/group.c b/address/group.c
index de8a9c749..847433ca3 100644
--- a/address/group.c
+++ b/address/group.c
@@ -36,7 +36,7 @@
 static struct Hash *Groups = NULL;
 
 /**
- * mutt_grouplist_init - Initialize the GroupList singleton.
+ * mutt_grouplist_init - Initialize the GroupList singleton
  *
  * This is called once from init.c when initializing the global structures.
  */
@@ -46,7 +46,7 @@ void mutt_grouplist_init(void)
 }
 
 /**
- * mutt_grouplist_free - Free GroupList singleton resource.
+ * mutt_grouplist_free - Free GroupList singleton resource
  *
  * This is called once from init.c when deinitializing the global resources.
  */
diff --git a/address/idna.c b/address/idna.c
index b6b06d7f4..eeb372115 100644
--- a/address/idna.c
+++ b/address/idna.c
@@ -304,7 +304,7 @@ cleanup:
 
 /**
  * mutt_idna_print_version - Create an IDN version string
- * @retval str Version string
+ * @retval ptr Version string
  *
  * @note This is a static string and must not be freed.
  */
diff --git a/color.c b/color.c
index 3a8111555..d025c3ca9 100644
--- a/color.c
+++ b/color.c
@@ -624,7 +624,7 @@ static void do_uncolor(struct Buffer *buf, struct Buffer *s,
  * @param data          Flags associated with the command
  * @param err           Buffer for error messages
  * @param parse_uncolor If true, 'uncolor', else 'unmono'
- * @retval enum e.g. #MUTT_CMD_SUCCESS
+ * @retval #CommandResult Result e.g. #MUTT_CMD_SUCCESS
  *
  * usage:
  * * uncolor index pattern [pattern...]
@@ -752,7 +752,7 @@ enum CommandResult mutt_parse_unmono(struct Buffer *buf, struct Buffer *s,
  * @param err       Buffer for error messages
  * @param is_index  true of this is for the index
  * @param match     Number of regex subexpression to match (0 for entire pattern)
- * @retval enum e.g. #MUTT_CMD_SUCCESS
+ * @retval #CommandResult Result e.g. #MUTT_CMD_SUCCESS
  */
 static enum CommandResult add_pattern(struct ColorLineHead *top, const char *s,
                                       bool sensitive, uint32_t fg, uint32_t bg, int attr,
@@ -1047,7 +1047,7 @@ static int fgbgattr_to_color(int fg, int bg, int attr)
  * @param callback Function to handle command - Implements ::parser_callback_t
  * @param dry_run  If true, test the command, but don't apply it
  * @param color    If true "color", else "mono"
- * @retval enum e.g. #MUTT_CMD_SUCCESS
+ * @retval #CommandResult Result e.g. #MUTT_CMD_SUCCESS
  *
  * usage: color OBJECT FG BG [ REGEX ]
  *        mono  OBJECT ATTR [ REGEX ]
diff --git a/config/bool.c b/config/bool.c
index 028d220b1..f583e79af 100644
--- a/config/bool.c
+++ b/config/bool.c
@@ -204,7 +204,7 @@ void bool_init(struct ConfigSet *cs)
  * @param cs  Config items
  * @param he  HashElem representing config item
  * @param err Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int bool_he_toggle(struct ConfigSet *cs, struct HashElem *he, struct Buffer *err)
 {
@@ -235,7 +235,7 @@ int bool_he_toggle(struct ConfigSet *cs, struct HashElem *he, struct Buffer *err
  * @param cs   Config items
  * @param name Name of config item
  * @param err  Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int bool_str_toggle(struct ConfigSet *cs, const char *name, struct Buffer *err)
 {
diff --git a/config/cfgaccount.c b/config/cfgaccount.c
index 6f5f17e21..99516fb54 100644
--- a/config/cfgaccount.c
+++ b/config/cfgaccount.c
@@ -124,7 +124,7 @@ void ac_free(const struct ConfigSet *cs, struct CfgAccount **ac)
  * @param vid   Value ID (index into CfgAccount's HashElem's)
  * @param value Native pointer/value to set
  * @param err   Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int ac_set_value(const struct CfgAccount *ac, size_t vid, intptr_t value, struct Buffer *err)
 {
@@ -142,7 +142,7 @@ int ac_set_value(const struct CfgAccount *ac, size_t vid, intptr_t value, struct
  * @param ac     Account-specific config items
  * @param vid    Value ID (index into CfgAccount's HashElem's)
  * @param result Buffer for results or error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int ac_get_value(const struct CfgAccount *ac, size_t vid, struct Buffer *result)
 {
diff --git a/config/command.c b/config/command.c
index 54582deb8..4b21c516f 100644
--- a/config/command.c
+++ b/config/command.c
@@ -66,7 +66,7 @@ static void command_destroy(const struct ConfigSet *cs, void *var, const struct
  * @param cdef  Variable definition
  * @param value Value to set
  * @param err   Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  *
  * If var is NULL, then the config item's initial value will be set.
  */
@@ -131,7 +131,7 @@ static int command_string_set(const struct ConfigSet *cs, void *var, struct Conf
  * @param var    Variable to get
  * @param cdef   Variable definition
  * @param result Buffer for results or error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  *
  * If var is NULL, then the config item's initial value will be returned.
  */
@@ -162,7 +162,7 @@ static int command_string_get(const struct ConfigSet *cs, void *var,
  * @param cdef  Variable definition
  * @param value Native pointer/value to set
  * @param err   Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 static int command_native_set(const struct ConfigSet *cs, void *var,
                               const struct ConfigDef *cdef, intptr_t value,
@@ -214,6 +214,7 @@ static int command_native_set(const struct ConfigSet *cs, void *var,
  * @param cdef Variable definition
  * @param err  Buffer for error messages
  * @retval intptr_t Command string
+ * @retval INT_MIN  Error
  */
 static intptr_t command_native_get(const struct ConfigSet *cs, void *var,
                                    const struct ConfigDef *cdef, struct Buffer *err)
@@ -232,7 +233,7 @@ static intptr_t command_native_get(const struct ConfigSet *cs, void *var,
  * @param var  Variable to reset
  * @param cdef Variable definition
  * @param err  Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 static int command_reset(const struct ConfigSet *cs, void *var,
                          const struct ConfigDef *cdef, struct Buffer *err)
diff --git a/config/quad.c b/config/quad.c
index 1ab8d28e8..b0a68bddf 100644
--- a/config/quad.c
+++ b/config/quad.c
@@ -218,7 +218,7 @@ static int quad_toggle(int opt)
  * @param cs  Config items
  * @param he  HashElem representing config item
  * @param err Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  *
  * @sa quad_toggle()
  */
diff --git a/config/set.c b/config/set.c
index 57c1f2e38..7a6f042e1 100644
--- a/config/set.c
+++ b/config/set.c
@@ -384,7 +384,7 @@ void cs_notify_listeners(const struct ConfigSet *cs, struct HashElem *he,
  * @param cs   Config items
  * @param he   HashElem representing config item
  * @param err  Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int cs_he_reset(const struct ConfigSet *cs, struct HashElem *he, struct Buffer *err)
 {
@@ -431,7 +431,7 @@ int cs_he_reset(const struct ConfigSet *cs, struct HashElem *he, struct Buffer *
  * @param cs   Config items
  * @param name Name of config item
  * @param err  Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int cs_str_reset(const struct ConfigSet *cs, const char *name, struct Buffer *err)
 {
@@ -454,7 +454,7 @@ int cs_str_reset(const struct ConfigSet *cs, const char *name, struct Buffer *er
  * @param he    HashElem representing config item
  * @param value Value to set
  * @param err   Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int cs_he_initial_set(const struct ConfigSet *cs, struct HashElem *he,
                       const char *value, struct Buffer *err)
@@ -495,7 +495,7 @@ int cs_he_initial_set(const struct ConfigSet *cs, struct HashElem *he,
  * @param name  Name of config item
  * @param value Value to set
  * @param err   Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int cs_str_initial_set(const struct ConfigSet *cs, const char *name,
                        const char *value, struct Buffer *err)
@@ -518,7 +518,7 @@ int cs_str_initial_set(const struct ConfigSet *cs, const char *name,
  * @param cs     Config items
  * @param he     HashElem representing config item
  * @param result Buffer for results or error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  *
  * If a config item is inherited from another, then this will get the parent's
  * value.  Otherwise, it will get the config item's initial value.
@@ -559,7 +559,7 @@ int cs_he_initial_get(const struct ConfigSet *cs, struct HashElem *he, struct Bu
  * @param cs     Config items
  * @param name   Name of config item
  * @param result Buffer for results or error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  *
  * If a config item is inherited from another, then this will get the parent's
  * value.  Otherwise, it will get the config item's initial value.
@@ -585,7 +585,7 @@ int cs_str_initial_get(const struct ConfigSet *cs, const char *name, struct Buff
  * @param he    HashElem representing config item
  * @param value Value to set
  * @param err   Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int cs_he_string_set(const struct ConfigSet *cs, struct HashElem *he,
                      const char *value, struct Buffer *err)
@@ -640,7 +640,7 @@ int cs_he_string_set(const struct ConfigSet *cs, struct HashElem *he,
  * @param name  Name of config item
  * @param value Value to set
  * @param err   Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int cs_str_string_set(const struct ConfigSet *cs, const char *name,
                       const char *value, struct Buffer *err)
@@ -663,7 +663,7 @@ int cs_str_string_set(const struct ConfigSet *cs, const char *name,
  * @param cs     Config items
  * @param he     HashElem representing config item
  * @param result Buffer for results or error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int cs_he_string_get(const struct ConfigSet *cs, struct HashElem *he, struct Buffer *result)
 {
@@ -711,7 +711,7 @@ int cs_he_string_get(const struct ConfigSet *cs, struct HashElem *he, struct Buf
  * @param cs     Config items
  * @param name   Name of config item
  * @param result Buffer for results or error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int cs_str_string_get(const struct ConfigSet *cs, const char *name, struct Buffer *result)
 {
@@ -734,7 +734,7 @@ int cs_str_string_get(const struct ConfigSet *cs, const char *name, struct Buffe
  * @param he    HashElem representing config item
  * @param value Native pointer/value to set
  * @param err   Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int cs_he_native_set(const struct ConfigSet *cs, struct HashElem *he,
                      intptr_t value, struct Buffer *err)
@@ -784,7 +784,7 @@ int cs_he_native_set(const struct ConfigSet *cs, struct HashElem *he,
  * @param name  Name of config item
  * @param value Native pointer/value to set
  * @param err   Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 int cs_str_native_set(const struct ConfigSet *cs, const char *name,
                       intptr_t value, struct Buffer *err)
@@ -838,6 +838,7 @@ int cs_str_native_set(const struct ConfigSet *cs, const char *name,
  * @param he  HashElem representing config item
  * @param err Buffer for results or error messages
  * @retval intptr_t Native pointer/value
+ * @retval INT_MIN  Error
  */
 intptr_t cs_he_native_get(const struct ConfigSet *cs, struct HashElem *he, struct Buffer *err)
 {
@@ -885,6 +886,7 @@ intptr_t cs_he_native_get(const struct ConfigSet *cs, struct HashElem *he, struc
  * @param name Name of config item
  * @param err  Buffer for error messages
  * @retval intptr_t Native pointer/value
+ * @retval INT_MIN  Error
  */
 intptr_t cs_str_native_get(const struct ConfigSet *cs, const char *name, struct Buffer *err)
 {
diff --git a/config/set.h b/config/set.h
index d884cc07d..74e07d625 100644
--- a/config/set.h
+++ b/config/set.h
@@ -96,7 +96,7 @@ typedef int     (*cs_validator)  (const struct ConfigSet *cs, const struct Confi
  * @param cdef  Variable definition
  * @param value Value to set
  * @param err   Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  *
  * If var is NULL, then the config item's initial value will be set.
  */
@@ -107,7 +107,7 @@ typedef int     (*cst_string_set)(const struct ConfigSet *cs, void *var,       s
  * @param var    Variable to get
  * @param cdef   Variable definition
  * @param result Buffer for results or error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  *
  * If var is NULL, then the config item's initial value will be returned.
  */
@@ -119,7 +119,7 @@ typedef int     (*cst_string_get)(const struct ConfigSet *cs, void *var, const s
  * @param cdef  Variable definition
  * @param value Native pointer/value to set
  * @param err   Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 typedef int     (*cst_native_set)(const struct ConfigSet *cs, void *var, const struct ConfigDef *cdef, intptr_t value,    struct Buffer *err);
 /**
@@ -129,6 +129,7 @@ typedef int     (*cst_native_set)(const struct ConfigSet *cs, void *var, const s
  * @param cdef Variable definition
  * @param err  Buffer for error messages
  * @retval intptr_t Config item string
+ * @retval INT_MIN  Error
  */
 typedef intptr_t(*cst_native_get)(const struct ConfigSet *cs, void *var, const struct ConfigDef *cdef,                    struct Buffer *err);
 
@@ -138,7 +139,7 @@ typedef intptr_t(*cst_native_get)(const struct ConfigSet *cs, void *var, const s
  * @param var  Variable to reset
  * @param cdef Variable definition
  * @param err  Buffer for error messages
- * @retval int Result, e.g. #CSR_SUCCESS
+ * @retval num Result, e.g. #CSR_SUCCESS
  */
 typedef int     (*cst_reset)     (const struct ConfigSet *cs, void *var, const struct ConfigDef *cdef, struct Buffer *err);
 /**
diff --git a/format_flags.h b/format_flags.h
index 2fa62f163..170a97383 100644
--- a/format_flags.h
+++ b/format_flags.h
@@ -50,7 +50,7 @@ typedef uint8_t MuttFormatFlags;         ///< Flags for mutt_expando_format(), e
  * @param[in]  else_str Otherwise, display this string
  * @param[in]  data     Pointer to the mailbox Context
  * @param[in]  flags    Flags, see #MuttFormatFlags
- * @retval src (unchanged)
+ * @retval ptr src (unchanged)
  *
  * Each callback function implements some expandos, e.g.
  *
diff --git a/help.c b/help.c
index f22ecb79c..c089bf394 100644
--- a/help.c
+++ b/help.c
@@ -250,8 +250,8 @@ static int get_wrapped_width(const char *t, size_t wid)
  * @param fp  File to write to
  * @param col Current screen column
  * @param i   Screen column to pad until
- * @retval col Padding was added
- * @retval i   Content was already wider than col
+ * @retval i   Padding was added
+ * @retval col Content was already wider than col
  */
 static int pad(FILE *fp, int col, int i)
 {
diff --git a/icommands.h b/icommands.h
index f3ae5079c..80193d9cd 100644
--- a/icommands.h
+++ b/icommands.h
@@ -34,7 +34,7 @@ struct Buffer;
  * @param s    Entire command line
  * @param data Private data to pass to parse function
  * @param err  Buffer for error messages
- * @retval enum e.g. #MUTT_CMD_SUCCESS
+ * @retval #CommandResult Result, e.g. #MUTT_CMD_SUCCESS
  */
 typedef enum CommandResult icommand_t(struct Buffer *buf, struct Buffer *s, unsigned long data, struct Buffer *err);
 
diff --git a/imap/auth_anon.c b/imap/auth_anon.c
index c49223ca6..8e5815bf9 100644
--- a/imap/auth_anon.c
+++ b/imap/auth_anon.c
@@ -38,7 +38,7 @@
  * imap_auth_anon - Authenticate anonymously
  * @param adata Imap Account data
  * @param method Name of this authentication method
- * @retval enum Result, e.g. #IMAP_AUTH_SUCCESS
+ * @retval #ImapAuthRes Result, e.g. #IMAP_AUTH_SUCCESS
  *
  * this is basically a stripped-down version of the cram-md5 method.
  */
diff --git a/imap/auth_cram.c b/imap/auth_cram.c
index 61f4e815f..6af3afedc 100644
--- a/imap/auth_cram.c
+++ b/imap/auth_cram.c
@@ -93,7 +93,7 @@ static void hmac_md5(const char *password, char *challenge, unsigned char *respo
  * imap_auth_cram_md5 - Authenticate using CRAM-MD5
  * @param adata Imap Account data
  * @param method Name of this authentication method
- * @retval enum Result, e.g. #IMAP_AUTH_SUCCESS
+ * @retval #ImapAuthRes Result, e.g. #IMAP_AUTH_SUCCESS
  */
 enum ImapAuthRes imap_auth_cram_md5(struct ImapAccountData *adata, const char *method)
 {
diff --git a/imap/auth_gss.c b/imap/auth_gss.c
index b85f484ab..70368dc51 100644
--- a/imap/auth_gss.c
+++ b/imap/auth_gss.c
@@ -102,7 +102,7 @@ static void print_gss_error(OM_uint32 err_maj, OM_uint32 err_min)
  * imap_auth_gss - GSS Authentication support
  * @param adata Imap Account data
  * @param method Name of this authentication method
- * @retval enum Result, e.g. #IMAP_AUTH_SUCCESS
+ * @retval #ImapAuthRes Result, e.g. #IMAP_AUTH_SUCCESS
  */
 enum ImapAuthRes imap_auth_gss(struct ImapAccountData *adata, const char *method)
 {
diff --git a/imap/auth_login.c b/imap/auth_login.c
index 8bd523a4f..bcd94bbd8 100644
--- a/imap/auth_login.c
+++ b/imap/auth_login.c
@@ -40,7 +40,7 @@
  * imap_auth_login - Plain LOGIN support
  * @param adata Imap Account data
  * @param method Name of this authentication method
- * @retval enum Result, e.g. #IMAP_AUTH_SUCCESS
+ * @retval #ImapAuthRes Result, e.g. #IMAP_AUTH_SUCCESS
  */
 enum ImapAuthRes imap_auth_login(struct ImapAccountData *adata, const char *method)
 {
diff --git a/imap/auth_plain.c b/imap/auth_plain.c
index 7baa4c15b..9866597c3 100644
--- a/imap/auth_plain.c
+++ b/imap/auth_plain.c
@@ -40,7 +40,7 @@
  * imap_auth_plain - SASL PLAIN support
  * @param adata Imap Account data
  * @param method Name of this authentication method
- * @retval enum Result, e.g. #IMAP_AUTH_SUCCESS
+ * @retval #ImapAuthRes Result, e.g. #IMAP_AUTH_SUCCESS
  */
 enum ImapAuthRes imap_auth_plain(struct ImapAccountData *adata, const char *method)
 {
diff --git a/imap/auth_sasl.c b/imap/auth_sasl.c
index a7aafb6c2..f3ecbc394 100644
--- a/imap/auth_sasl.c
+++ b/imap/auth_sasl.c
@@ -44,7 +44,7 @@
  * imap_auth_sasl - Default authenticator if available
  * @param adata Imap Account data
  * @param method Name of this authentication method
- * @retval enum Result, e.g. #IMAP_AUTH_SUCCESS
+ * @retval #ImapAuthRes Result, e.g. #IMAP_AUTH_SUCCESS
  */
 enum ImapAuthRes imap_auth_sasl(struct ImapAccountData *adata, const char *method)
 {
diff --git a/imap/util.c b/imap/util.c
index f4c9eb25e..ad6756e0e 100644
--- a/imap/util.c
+++ b/imap/util.c
@@ -744,7 +744,7 @@ fallback:
  * imap_continue - display a message and ask the user if they want to go on
  * @param msg  Location of the error
  * @param resp Message for user
- * @retval enum Result, See #QuadOption
+ * @retval #QuadOption Result, e.g. #MUTT_NO
  */
 enum QuadOption imap_continue(const char *msg, const char *resp)
 {
diff --git a/init.c b/init.c
index 37ce5ebbe..a22e01d24 100644
--- a/init.c
+++ b/init.c
@@ -459,7 +459,7 @@ static bool get_hostname(void)
  * @param s    Buffer containing the attachments command
  * @param head List of AttachMatch to add to
  * @param err  Buffer for error messages
- * @retval enum e.g. #MUTT_CMD_SUCCESS
+ * @retval #CommandResult Result e.g. #MUTT_CMD_SUCCESS
  */
 static enum CommandResult parse_attach_list(struct Buffer *buf, struct Buffer *s,
                                             struct ListHead *head, struct Buffer *err)
@@ -3243,7 +3243,7 @@ int mutt_init(bool skip_sys_rc, struct ListHead *commands)
  * @param line  config line to read
  * @param token scratch buffer to be used by parser
  * @param err   where to write error messages
- * @retval enum e.g. #MUTT_CMD_SUCCESS
+ * @retval #CommandResult Result e.g. #MUTT_CMD_SUCCESS
  *
  * Caller should free token->data when finished.  the reason for this variable
  * is to avoid having to allocate and deallocate a lot of memory if we are
@@ -3358,7 +3358,7 @@ int mutt_query_variables(struct ListHead *queries)
  * query_quadoption - Ask the user a quad-question
  * @param opt    Option to use
  * @param prompt Message to show to the user
- * @retval enum Result, see #QuadOption
+ * @retval #QuadOption Result, e.g. #MUTT_NO
  */
 enum QuadOption query_quadoption(enum QuadOption opt, const char *prompt)
 {
diff --git a/keymap.c b/keymap.c
index fabeae33a..ae262122e 100644
--- a/keymap.c
+++ b/keymap.c
@@ -279,7 +279,7 @@ static size_t parsekeys(const char *str, keycode_t *d, size_t max)
  * @param macro Macro string
  * @param desc Description of macro (OPTIONAL)
  * @param err   Buffer for error message
- * @retval enum e.g. #MUTT_CMD_SUCCESS
+ * @retval #CommandResult Result e.g. #MUTT_CMD_SUCCESS
  *
  * Insert a key sequence into the specified map.
  * The map is sorted by ASCII value (lowest to highest)
@@ -387,7 +387,7 @@ static enum CommandResult km_bind_err(const char *s, int menu, int op,
  * @param op    Operation, e.g. OP_DELETE
  * @param macro Macro string
  * @param desc Description of macro (OPTIONAL)
- * @retval enum e.g. #MUTT_CMD_SUCCESS
+ * @retval #CommandResult Result e.g. #MUTT_CMD_SUCCESS
  */
 enum CommandResult km_bind(char *s, int menu, int op, char *macro, char *desc)
 {
@@ -400,7 +400,7 @@ enum CommandResult km_bind(char *s, int menu, int op, char *macro, char *desc)
  * @param menu Menu id, e.g. #MENU_PAGER
  * @param op   Operation, e.g. OP_DELETE
  * @param err  Buffer for error message
- * @retval enum e.g. #MUTT_CMD_SUCCESS
+ * @retval #CommandResult Result e.g. #MUTT_CMD_SUCCESS
  */
 static enum CommandResult km_bindkey_err(const char *s, int menu, int op, struct Buffer *err)
 {
@@ -412,7 +412,7 @@ static enum CommandResult km_bindkey_err(const char *s, int menu, int op, struct
  * @param s    Key string
  * @param menu Menu id, e.g. #MENU_PAGER
  * @param op   Operation, e.g. OP_DELETE
- * @retval enum e.g. #MUTT_CMD_SUCCESS
+ * @retval #CommandResult Result e.g. #MUTT_CMD_SUCCESS
  */
 static enum CommandResult km_bindkey(const char *s, int menu, int op)
 {
@@ -1176,7 +1176,7 @@ error:
  * @param func     Function name
  * @param bindings Key bindings table
  * @param err      Buffer for error message
- * @retval enum e.g. #MUTT_CMD_SUCCESS
+ * @retval #CommandResult Result e.g. #MUTT_CMD_SUCCESS
  */
 static enum CommandResult try_bind(char *key, int menu, char *func,
                                    const struct Binding *bindings, struct Buffer *err)
diff --git a/maildir/shared.c b/maildir/shared.c
index 851e907bb..f17d55bfa 100644
--- a/maildir/shared.c
+++ b/maildir/shared.c
@@ -467,7 +467,7 @@ int maildir_move_to_mailbox(struct Mailbox *m, struct Maildir **ptr)
 /**
  * maildir_hcache_keylen - Calculate the length of the Maildir path
  * @param fn File name
- * @retval size_t Length in bytes
+ * @retval num Length in bytes
  *
  * @note This length excludes the flags, which will vary
  */
diff --git a/mutt/date.c b/mutt/date.c
index 62d20820e..82d25c873 100644
--- a/mutt/date.c
+++ b/mutt/date.c
@@ -696,9 +696,9 @@ time_t mutt_date_add_timeout(time_t now, long timeout)
 }
 
 /**
- * mutt_date_localtime - Converts calendar time to a broken-down time structure expressed in user timezone.
+ * mutt_date_localtime - Converts calendar time to a broken-down time structure expressed in user timezone
  * @param  t  Time
- * @retval tm Broken-down time representation
+ * @retval obj Broken-down time representation
  *
  * Uses current time if t is #MUTT_DATE_NOW
  */
@@ -714,9 +714,9 @@ struct tm mutt_date_localtime(time_t t)
 }
 
 /**
- * mutt_date_gmtime - Converts calendar time to a broken-down time structure expressed in UTC timezone.
+ * mutt_date_gmtime - Converts calendar time to a broken-down time structure expressed in UTC timezone
  * @param  t  Time
- * @retval tm Broken-down time representation
+ * @retval obj Broken-down time representation
  *
  * Uses current time if t is #MUTT_DATE_NOW
  */
diff --git a/mutt/file.c b/mutt/file.c
index ede1aa395..a19081b7b 100644
--- a/mutt/file.c
+++ b/mutt/file.c
@@ -615,8 +615,8 @@ int mutt_file_sanitize_regex(struct Buffer *dest, const char *src)
  * @param[in]  flags    Flags, e.g. #MUTT_CONT
  * @retval ptr          The allocated string
  *
- * Read a line from "fp" into the dynamically allocated "s", increasing
- * "s" if necessary. The ending "\n" or "\r\n" is removed.  If a line ends
+ * Read a line from "fp" into the dynamically allocated "line", increasing
+ * "line" if necessary. The ending "\n" or "\r\n" is removed.  If a line ends
  * with "\", this char and the linefeed is removed, and the next line is read
  * too.
  */
diff --git a/mutt/string.c b/mutt/string.c
index 87c83fa18..f4cf69098 100644
--- a/mutt/string.c
+++ b/mutt/string.c
@@ -124,7 +124,7 @@ const char *mutt_str_sysexit(int err_num)
  * char_cmp_identity - Compare two characters
  * @param a First character to compare
  * @param b Second character to compare
- * @retval a == b
+ * @retval true If (a == b)
  */
 static inline bool char_cmp_identity(char a, char b)
 {
@@ -135,7 +135,7 @@ static inline bool char_cmp_identity(char a, char b)
  * char_cmp_lower - Compare two characters ignoring case
  * @param a First character to compare
  * @param b Second character to compare
- * @retval a == b, ignoring case
+ * @retval true If (a == b), ignoring case
  */
 static inline bool char_cmp_lower(char a, char b)
 {
@@ -148,9 +148,9 @@ static inline bool char_cmp_lower(char a, char b)
 typedef bool (*char_cmp)(char, char);
 
 /**
- * get_char_cmp - Retrieve the correct function to compare characters according to a case sensitivity setting.
+ * get_char_cmp - Retrieve the correct function to compare characters according to a case sensitivity setting
  * @param cs Case sensitivity setting
- * @retval A char_cmp function pointer
+ * @retval ptr char_cmp function pointer
  */
 static char_cmp get_char_cmp(enum CaseSensitivity cs)
 {
@@ -158,11 +158,11 @@ static char_cmp get_char_cmp(enum CaseSensitivity cs)
 }
 
 /**
- * mutt_str_startswith - Check whether a string starts with a prefix.
+ * mutt_str_startswith - Check whether a string starts with a prefix
  * @param str String to check
  * @param prefix Prefix to match
  * @param cs Case sensitivity setting
- * @retval Length of prefix if str starts with prefix
+ * @retval num Length of prefix if str starts with prefix
  * @retval 0 if str does not start with prefix
  */
 size_t mutt_str_startswith(const char *str, const char *prefix, enum CaseSensitivity cs)
diff --git a/mutt_commands.h b/mutt_commands.h
index 3e39de2c6..e1f451b90 100644
--- a/mutt_commands.h
+++ b/mutt_commands.h
@@ -42,7 +42,7 @@ enum CommandResult
  * @param s    Buffer containing string to be parsed
  * @param data Flags associated with the command
  * @param err  Buffer for error messages
- * @retval enum e.g. #MUTT_CMD_SUCCESS
+ * @retval #CommandResult Result e.g. #MUTT_CMD_SUCCESS
  */
 typedef enum CommandResult (*command_t)(struct Buffer *buf, struct Buffer *s, unsigned long data, struct Buffer *err);
 
diff --git a/ncrypt/crypt_gpgme.c b/ncrypt/crypt_gpgme.c
index da1794427..d339986c5 100644
--- a/ncrypt/crypt_gpgme.c
+++ b/ncrypt/crypt_gpgme.c
@@ -264,7 +264,7 @@ static const char *parse_version_number(const char *s, int *number)
  * @param major Version MAJOR.x.x
  * @param minor Version x.MINOR.x
  * @param micro Version x.x.MICRO
- * @retval str  Patch level
+ * @retval ptr  Patch level string
  * @retval NULL If there are fewer parts
  *
  * Break up the complete string-representation of the version number S, which
@@ -762,7 +762,7 @@ static gpgme_data_t create_gpgme_data(void)
 /**
  * have_gpg_version - Do we have a sufficent GPG version
  * @param version Minimum version
- * @retval bool ZZZ
+ * @retval true If minimum version is available
  *
  * Return true if the OpenPGP engine's version is at least VERSION.
  */
@@ -1549,7 +1549,7 @@ struct Body *smime_gpgme_build_smime_entity(struct Body *a, char *keylist)
  * @param s   State to use
  * @param sig GPGME signature
  * @retval 0 Success
- * @retval 1 There is is a severe warning
+ * @retval 1 There is a severe warning
  *
  * Display the common attributes of the signature summary SUM.
  */
diff --git a/ncrypt/gnupgparse.c b/ncrypt/gnupgparse.c
index 96180dcf8..58352fa49 100644
--- a/ncrypt/gnupgparse.c
+++ b/ncrypt/gnupgparse.c
@@ -61,7 +61,7 @@
  *   - trust info
  *   - key length
  *   - pubkey algo
- *   - 16 hex digits with the long keyid.
+ *   - 16 hex digits with the long keyid
  *   - timestamp (1998-02-28)
  *   - Local id
  *   - ownertrust
diff --git a/ncrypt/smime.c b/ncrypt/smime.c
index 5a5d1d9b3..eb2653031 100644
--- a/ncrypt/smime.c
+++ b/ncrypt/smime.c
@@ -1473,9 +1473,7 @@ int smime_class_verify_sender(struct Email *e)
   return rc;
 }
 
-/*
- *    Creating S/MIME - bodies.
- */
+/* Creating S/MIME - bodies */
 
 /**
  * smime_invoke_encrypt - Use SMIME to encrypt a file
@@ -1820,9 +1818,7 @@ struct Body *smime_class_sign_message(struct Body *a)
   return a;
 }
 
-/*
- *    Handling S/MIME - bodies.
- */
+/* Handling S/MIME - bodies */
 
 /**
  * smime_invoke_verify - Use SMIME to verify a file
diff --git a/notmuch/mutt_notmuch.c b/notmuch/mutt_notmuch.c
index b76bd5cc6..4d1cc42e8 100644
--- a/notmuch/mutt_notmuch.c
+++ b/notmuch/mutt_notmuch.c
@@ -1066,7 +1066,7 @@ static void append_thread(header_cache_t *h, struct Mailbox *m,
 /**
  * get_messages - load messages for a query
  * @param query Notmuch query
- * @retval msgs Messages matching query
+ * @retval ptr  Messages matching query
  * @retval NULL Error occurred
  *
  * This helper method is to be the single point for retrieving messages. It
@@ -1136,7 +1136,7 @@ static bool read_mesgs_query(struct Mailbox *m, notmuch_query_t *q, bool dedup)
 /**
  * get_threads - load threads for a query
  * @param query Notmuch query
- * @retval msgs Threads matching query
+ * @retval ptr Threads matching query
  * @retval NULL Error occurred
  *
  * This helper method is to be the single point for retrieving messages. It
diff --git a/rfc3676.c b/rfc3676.c
index 82d9ae866..62d554d65 100644
--- a/rfc3676.c
+++ b/rfc3676.c
@@ -184,7 +184,7 @@ static void flush_par(struct State *s, struct FlowedState *fst)
  * quote_width - Calculate the paragraph width based upon the quote level
  * @param s  State to use
  * @param ql Quote level
- * @retval int Paragraph width
+ * @retval num Paragraph width
  *
  * The start of a quoted line will be ">>> ", so we need to subtract the space
  * required for the prefix from the terminal width.