From 3bd10b0193e3c56d2cb7bdb11e80b75539565df3 Mon Sep 17 00:00:00 2001
From: Richard Russon <rich@flatcap.org>
Date: Mon, 3 Jan 2022 23:37:04 +0000
Subject: [PATCH] doxy: tidy retvals

---
 alias/array.c       | 4 ++++
 autocrypt/gpgme.c   | 1 +
 autocrypt/schema.c  | 2 ++
 bcache/bcache.c     | 2 ++
 compose/envelope.c  | 3 +++
 config/quad.c       | 1 +
 email/parse.c       | 2 +-
 gui/mutt_window.c   | 1 +
 gui/sbar.c          | 1 +
 hcache/hcache.c     | 1 +
 imap/imap.c         | 2 +-
 imap/mdata.c        | 1 +
 imap/message.c      | 3 +++
 index/dlg_index.c   | 1 +
 index/ibar.c        | 3 +++
 init.c              | 2 ++
 keymap.c            | 1 +
 menu/move.c         | 6 ++++++
 mutt/buffer.c       | 2 ++
 mutt/date.c         | 6 +++---
 mutt/md5.c          | 1 +
 mutt/state.c        | 4 ++--
 mutt_commands.c     | 2 +-
 mutt_mailbox.c      | 2 +-
 mutt_thread.c       | 4 ++--
 ncrypt/pgppacket.c  | 3 ++-
 notmuch/config.c    | 4 ++--
 notmuch/notmuch.c   | 2 +-
 notmuch/query.c     | 4 ++--
 pager/dlg_pager.c   | 1 +
 pager/pbar.c        | 3 +++
 send/send.c         | 2 +-
 sidebar/functions.c | 4 ++--
 sidebar/window.c    | 4 +++-
 34 files changed, 64 insertions(+), 21 deletions(-)

diff --git a/alias/array.c b/alias/array.c
index 8d5efc1f623..fc1883c4e59 100644
--- a/alias/array.c
+++ b/alias/array.c
@@ -38,6 +38,8 @@ struct Alias;
  * alias_array_alias_add - Add an Alias to the AliasViewArray
  * @param ava Array of Aliases
  * @param alias Alias to add
+ * @retval num Size of array
+ * @retval -1  Error
  *
  * @note The Alias is wrapped in an AliasView
  * @note Call alias_array_sort() to sort and reindex the AliasViewArray
@@ -63,6 +65,8 @@ int alias_array_alias_add(struct AliasViewArray *ava, struct Alias *alias)
  * alias_array_alias_delete - Delete an Alias from the AliasViewArray
  * @param ava    Array of Aliases
  * @param alias Alias to remove
+ * @retval num Size of array
+ * @retval -1  Error
  *
  * @note Call alias_array_sort() to sort and reindex the AliasViewArray
  */
diff --git a/autocrypt/gpgme.c b/autocrypt/gpgme.c
index e85746541dd..e9a5c4bd2d1 100644
--- a/autocrypt/gpgme.c
+++ b/autocrypt/gpgme.c
@@ -63,6 +63,7 @@ static int create_gpgme_context(gpgme_ctx_t *ctx)
 
 /**
  * mutt_autocrypt_gpgme_init - Initialise GPGME
+ * @retval 0 Always
  */
 int mutt_autocrypt_gpgme_init(void)
 {
diff --git a/autocrypt/schema.c b/autocrypt/schema.c
index bf8b243082e..022b234ebe1 100644
--- a/autocrypt/schema.c
+++ b/autocrypt/schema.c
@@ -34,6 +34,8 @@
 
 /**
  * mutt_autocrypt_schema_init - Set up an Autocrypt database
+ * @retval  0 Success
+ * @retval -1 Error
  */
 int mutt_autocrypt_schema_init(void)
 {
diff --git a/bcache/bcache.c b/bcache/bcache.c
index 4cf80d59538..8510c7affaa 100644
--- a/bcache/bcache.c
+++ b/bcache/bcache.c
@@ -109,6 +109,8 @@ static int bcache_path(struct ConnAccount *account, const char *mailbox, struct
  * @param bcache Body cache
  * @param id     Per-mailbox unique identifier for the message
  * @param newid  New id for the message
+ * @retval  0 Success
+ * @retval -1 Error
  */
 static int mutt_bcache_move(struct BodyCache *bcache, const char *id, const char *newid)
 {
diff --git a/compose/envelope.c b/compose/envelope.c
index 73052a436ba..21e0837a9d2 100644
--- a/compose/envelope.c
+++ b/compose/envelope.c
@@ -291,6 +291,7 @@ static void draw_header_content(struct MuttWindow *win, int row,
  * @param shared Shared compose data
  * @param edata  Envelope data
  * @param row    Window row to start drawing
+ * @retval num Number of lines used
  */
 static int draw_crypt_lines(struct MuttWindow *win, struct ComposeSharedData *shared,
                             struct ComposeEnvelopeData *edata, int row)
@@ -450,6 +451,7 @@ static void draw_mix_line(struct ListHead *chain, struct MuttWindow *win, int ro
  * @param win       Window
  * @param row       Window row to start drawing
  * @param max_lines How many lines may be used
+ * @retval num Lines used
  */
 static int draw_envelope_addr(int field, struct AddressList *al,
                               struct MuttWindow *win, int row, size_t max_lines)
@@ -557,6 +559,7 @@ static int draw_envelope_addr(int field, struct AddressList *al,
  * @param win    Window to draw on
  * @param shared Shared compose data
  * @param row    Window row to start drawing from
+ * @retval num Rows used
  */
 static int draw_envelope_user_hdrs(struct MuttWindow *win,
                                    struct ComposeSharedData *shared, int row)
diff --git a/config/quad.c b/config/quad.c
index 261c690044b..8860cc2e2f5 100644
--- a/config/quad.c
+++ b/config/quad.c
@@ -181,6 +181,7 @@ static int quad_reset(const struct ConfigSet *cs, void *var,
 /**
  * quad_toggle - Toggle (invert) the value of a quad option
  * @param opt Value to toggle
+ * @retval num New value
  *
  * By toggling the low bit, the following are swapped:
  * - #MUTT_NO    <--> #MUTT_YES
diff --git a/email/parse.c b/email/parse.c
index 0d98eb1394f..7e593b8ba15 100644
--- a/email/parse.c
+++ b/email/parse.c
@@ -592,7 +592,7 @@ static struct AutocryptHeader *parse_autocrypt(struct AutocryptHeader *head, con
 /**
  * rfc2369_first_mailto - Extract the first mailto: URL from a RFC2369 list
  * @param body Body of the header
- * @return First mailto: URL found, or NULL if none was found
+ * @retval ptr First mailto: URL found, or NULL if none was found
  */
 static char *rfc2369_first_mailto(const char *body)
 {
diff --git a/gui/mutt_window.c b/gui/mutt_window.c
index 6bd264a589b..8509b63dd5a 100644
--- a/gui/mutt_window.c
+++ b/gui/mutt_window.c
@@ -454,6 +454,7 @@ void mutt_window_add_child(struct MuttWindow *parent, struct MuttWindow *child)
  * mutt_window_remove_child - Remove a child from a Window
  * @param parent Window to remove from
  * @param child  Window to remove
+ * @retval ptr Child Window
  */
 struct MuttWindow *mutt_window_remove_child(struct MuttWindow *parent, struct MuttWindow *child)
 {
diff --git a/gui/sbar.c b/gui/sbar.c
index 2fe45e485b2..648bfc40c16 100644
--- a/gui/sbar.c
+++ b/gui/sbar.c
@@ -180,6 +180,7 @@ static void sbar_wdata_free(struct MuttWindow *win, void **ptr)
 
 /**
  * sbar_data_new - Free the private data attached to the MuttWindow
+ * @retval ptr New SBar
  */
 static struct SBarPrivateData *sbar_data_new(void)
 {
diff --git a/hcache/hcache.c b/hcache/hcache.c
index d9c32358f38..f80115addbb 100644
--- a/hcache/hcache.c
+++ b/hcache/hcache.c
@@ -64,6 +64,7 @@ static unsigned int hcachever = 0x0;
 
 /**
  * header_size - Compute the size of the header with uuid validity and crc
+ * @retval num Size of the header
  */
 static size_t header_size(void)
 {
diff --git a/imap/imap.c b/imap/imap.c
index 0e6734e1e81..718830ad8dd 100644
--- a/imap/imap.c
+++ b/imap/imap.c
@@ -1101,7 +1101,7 @@ int imap_sync_message_for_copy(struct Mailbox *m, struct Email *e,
  * imap_check_mailbox - Use the NOOP or IDLE command to poll for new mail
  * @param m     Mailbox
  * @param force Don't wait
- * return enum MxStatus
+ * @retval num MxStatus
  */
 enum MxStatus imap_check_mailbox(struct Mailbox *m, bool force)
 {
diff --git a/imap/mdata.c b/imap/mdata.c
index 3d5b496135e..ed2f0781f9e 100644
--- a/imap/mdata.c
+++ b/imap/mdata.c
@@ -55,6 +55,7 @@ void imap_mdata_free(void **ptr)
 /**
  * imap_mdata_get - Get the Mailbox data for this mailbox
  * @param m Mailbox
+ * @retval ptr ImapMboxData
  */
 struct ImapMboxData *imap_mdata_get(struct Mailbox *m)
 {
diff --git a/imap/message.c b/imap/message.c
index 29123435dac..6a7bd0ef3d8 100644
--- a/imap/message.c
+++ b/imap/message.c
@@ -465,6 +465,8 @@ static int msg_fetch_header(struct Mailbox *m, struct ImapHeader *ih, char *buf,
  * @param buf  Buffer containing data
  * @param len  Length of buffer
  * @param conn Network connection
+ * @retval >0 Number of bytes written
+ * @retval -1 Error
  */
 static int flush_buffer(char *buf, size_t *len, struct Connection *conn)
 {
@@ -521,6 +523,7 @@ static void imap_alloc_uid_hash(struct ImapAccountData *adata, unsigned int msn_
  * @param[in]  msn_begin     First Message Sequence Number
  * @param[in]  msn_end       Last Message Sequence Number
  * @param[out] fetch_msn_end Highest Message Sequence Number fetched
+ * @retval num MSN count
  *
  * Generates a more complicated sequence set after using the header cache,
  * in case there are missing MSNs in the middle.
diff --git a/index/dlg_index.c b/index/dlg_index.c
index 51634df8693..d869d102100 100644
--- a/index/dlg_index.c
+++ b/index/dlg_index.c
@@ -694,6 +694,7 @@ void change_folder_mailbox(struct Menu *menu, struct Mailbox *m, int *oldcount,
  * @param oldcount  How many items are currently in the index
  * @param shared    Shared Index data
  * @param read_only Open Mailbox in read-only mode
+ * @retval ptr Mailbox
  */
 struct Mailbox *change_folder_notmuch(struct Menu *menu, char *buf, int buflen, int *oldcount,
                                       struct IndexSharedData *shared, bool read_only)
diff --git a/index/ibar.c b/index/ibar.c
index 07f23471205..270c9eebab3 100644
--- a/index/ibar.c
+++ b/index/ibar.c
@@ -327,6 +327,9 @@ static void ibar_data_free(struct MuttWindow *win, void **ptr)
 
 /**
  * ibar_data_new - Free the private data attached to the MuttWindow
+ * @param shared Shared Index data
+ * @param priv   Private Index data
+ * @retval ptr New IBar
  */
 static struct IBarPrivateData *ibar_data_new(struct IndexSharedData *shared,
                                              struct IndexPrivateData *priv)
diff --git a/init.c b/init.c
index b78f578c557..4b331b093a5 100644
--- a/init.c
+++ b/init.c
@@ -1482,6 +1482,8 @@ bool mutt_nm_tag_complete(char *buf, size_t buflen, int numtabs)
  * @param buf    Buffer for the result
  * @param buflen Length of the buffer
  * @param pos    Cursor position in the buffer
+ * @retval 1 Success
+ * @retval 0 Failure
  */
 int mutt_var_value_complete(char *buf, size_t buflen, int pos)
 {
diff --git a/keymap.c b/keymap.c
index ffab615d5cf..b813a73bda1 100644
--- a/keymap.c
+++ b/keymap.c
@@ -1441,6 +1441,7 @@ enum CommandResult mutt_parse_bind(struct Buffer *buf, struct Buffer *s,
  * @param menus    Array for results
  * @param s        String containing menu-names
  * @param err      Buffer for error messages
+ * @retval NULL Always
  *
  * Expects to see: <menu-string>[,<menu-string>]
  */
diff --git a/menu/move.c b/menu/move.c
index fed8bb30971..77389272288 100644
--- a/menu/move.c
+++ b/menu/move.c
@@ -103,6 +103,7 @@ MenuRedrawFlags menu_set_and_notify(struct Menu *menu, int top, int index)
  * @param menu  Menu
  * @param top   Index of item at the top of the view
  * @param index Current selection
+ * @retval num Top line
  */
 static int menu_drag_view(struct Menu *menu, int top, int index)
 {
@@ -155,6 +156,7 @@ static int menu_drag_view(struct Menu *menu, int top, int index)
  * @param menu  Menu
  * @param top   First entry visible in the view
  * @param index Current selection
+ * @retval num Index
  */
 static int calc_fit_selection_to_view(struct Menu *menu, int top, int index)
 {
@@ -183,6 +185,8 @@ static int calc_fit_selection_to_view(struct Menu *menu, int top, int index)
  * calc_move_view - Move the view
  * @param menu     Menu
  * @param relative Relative number of lines to move
+ * @retval num Top line
+ * @retval   0 Error
  */
 static int calc_move_view(struct Menu *menu, int relative)
 {
@@ -224,6 +228,7 @@ static int calc_move_view(struct Menu *menu, int relative)
  * menu_move_selection - Move the selection, keeping within between [0, menu->max]
  * @param menu  Menu
  * @param index New selection
+ * @retval num #MenuRedrawFlags, e.g. #MENU_REDRAW_CURRENT
  */
 MenuRedrawFlags menu_move_selection(struct Menu *menu, int index)
 {
@@ -241,6 +246,7 @@ MenuRedrawFlags menu_move_selection(struct Menu *menu, int index)
  * menu_move_view_relative - Move the view relatively
  * @param menu     Menu
  * @param relative Relative number of lines to move
+ * @retval num #MenuRedrawFlags, e.g. #MENU_REDRAW_CURRENT
  */
 MenuRedrawFlags menu_move_view_relative(struct Menu *menu, int relative)
 {
diff --git a/mutt/buffer.c b/mutt/buffer.c
index 954e1ffddc0..fcc1d6c4b8f 100644
--- a/mutt/buffer.c
+++ b/mutt/buffer.c
@@ -441,6 +441,8 @@ char *mutt_buffer_strdup(const struct Buffer *buf)
  * mutt_buffer_copy - Copy a Buffer's contents to another Buffer
  * @param dst Buffer for result
  * @param src Buffer to copy
+ * @retval num Bytes written to Buffer
+ * @retval 0   Error
  */
 size_t mutt_buffer_copy(struct Buffer *dst, const struct Buffer *src)
 {
diff --git a/mutt/date.c b/mutt/date.c
index 9329a6d5a21..120df37dca8 100644
--- a/mutt/date.c
+++ b/mutt/date.c
@@ -154,7 +154,7 @@ static time_t compute_tz(time_t g, struct tm *utc)
  * @param w True if west of UTC, false if east
  * @param h Number of hours in the timezone
  * @param m Number of minutes in the timezone
- * @retval Timezone offset in seconds
+ * @retval num Timezone offset in seconds
  */
 static time_t add_tz_offset(time_t t, bool w, time_t h, time_t m)
 {
@@ -422,7 +422,7 @@ int mutt_date_check_month(const char *s)
 
 /**
  * mutt_date_epoch - Return the number of seconds since the Unix epoch
- * @retval s The number of s since the Unix epoch, or 0 on failure
+ * @retval num Number of seconds since the Unix epoch, or 0 on failure
  */
 time_t mutt_date_epoch(void)
 {
@@ -686,7 +686,7 @@ struct tm mutt_date_gmtime(time_t t)
  * @param buflen Buffer size
  * @param format Format to apply
  * @param t      Time to format
- * @retval num   Number of Bytes added to buffer, excluding null byte.
+ * @retval num   Number of Bytes added to buffer, excluding NUL byte
  */
 size_t mutt_date_localtime_format(char *buf, size_t buflen, const char *format, time_t t)
 {
diff --git a/mutt/md5.c b/mutt/md5.c
index 1426d5ae162..71310c1ba56 100644
--- a/mutt/md5.c
+++ b/mutt/md5.c
@@ -313,6 +313,7 @@ void *mutt_md5_finish_ctx(struct Md5Ctx *md5ctx, void *resbuf)
  * mutt_md5 - Calculate the MD5 hash of a NULL-terminated string
  * @param str String to hash
  * @param buf Buffer for result
+ * @retval ptr Results buffer
  */
 void *mutt_md5(const char *str, void *buf)
 {
diff --git a/mutt/state.c b/mutt/state.c
index ec96aec2de2..7b77bc3845c 100644
--- a/mutt/state.c
+++ b/mutt/state.c
@@ -38,7 +38,7 @@
 
 /**
  * state_attachment_marker - Get a unique (per-run) ANSI string to mark PGP messages in an email
- * @retval s Marker
+ * @retval ptr Marker
  */
 const char *state_attachment_marker(void)
 {
@@ -52,7 +52,7 @@ const char *state_attachment_marker(void)
 
 /**
  * state_protected_header_marker - Get a unique (per-run) ANSI string to mark protected headers in an email
- * @retval s Marker
+ * @retval ptr Marker
  */
 const char *state_protected_header_marker(void)
 {
diff --git a/mutt_commands.c b/mutt_commands.c
index 40d7bd9c9c5..ea7c45caea5 100644
--- a/mutt_commands.c
+++ b/mutt_commands.c
@@ -174,7 +174,7 @@ void mutt_commands_free(void)
 /**
  * mutt_commands_array - Get Commands array
  * @param first Set to first element of Commands array
- * @retval size_t Size of Commands array
+ * @retval num Size of Commands array
  */
 size_t mutt_commands_array(struct Command **first)
 {
diff --git a/mutt_mailbox.c b/mutt_mailbox.c
index d96ccfe50b6..50af9a1e352 100644
--- a/mutt_mailbox.c
+++ b/mutt_mailbox.c
@@ -332,7 +332,7 @@ void mutt_mailbox_set_notified(struct Mailbox *m)
 /**
  * find_next_mailbox - Find the next mailbox with new or unread mail.
  * @param s         Buffer containing name of current mailbox
- * @param find_new  Boolean controlling new or unread check.
+ * @param find_new  Boolean controlling new or unread check
  * @retval ptr Mailbox
  *
  * Given a folder name, find the next incoming folder with new or unread mail.
diff --git a/mutt_thread.c b/mutt_thread.c
index 545adfb5986..d1b4ef00f5c 100644
--- a/mutt_thread.c
+++ b/mutt_thread.c
@@ -103,7 +103,7 @@ enum UseThreads mutt_thread_style(void)
 /**
  * get_use_threads_str - Convert UseThreads enum to string
  * @param value Value to convert
- * @retval string form of value
+ * @retval ptr String form of value
  */
 const char *get_use_threads_str(enum UseThreads value)
 {
@@ -351,7 +351,7 @@ static void calculate_visibility(struct MuttThread *tree, int *max_depth)
 /**
  * mutt_thread_ctx_init - Initialize a threading context
  * @param m     Current mailbox
- * @retval tctx Threading context
+ * @retval ptr Threading context
  */
 struct ThreadsContext *mutt_thread_ctx_init(struct Mailbox *m)
 {
diff --git a/ncrypt/pgppacket.c b/ncrypt/pgppacket.c
index 72aa8ac2b6b..04ee17cbef8 100644
--- a/ncrypt/pgppacket.c
+++ b/ncrypt/pgppacket.c
@@ -35,7 +35,7 @@
 
 #define CHUNK_SIZE 1024 ///< Amount of data to read at once
 
-static unsigned char *pbuf = NULL; ///< Cache PGP data packet
+static unsigned char *pbuf = NULL; ///< Cached PGP data packet
 static size_t plen = 0;            ///< Length of cached packet
 
 /**
@@ -78,6 +78,7 @@ static int read_material(size_t material, size_t *used, FILE *fp)
  * pgp_read_packet - Read a PGP packet from a file
  * @param[in]  fp  File to read from
  * @param[out] len Number of bytes read
+ * @retval ptr PGP data packet
  *
  * This function uses a cache to store the data: #pbuf, #plen.
  */
diff --git a/notmuch/config.c b/notmuch/config.c
index 34c70216655..e4de9dc2035 100644
--- a/notmuch/config.c
+++ b/notmuch/config.c
@@ -38,8 +38,8 @@
 #ifdef USE_NOTMUCH
 /**
  * is_valid_notmuch_url - Checks that a URL is in required form.
- * @retval true url in form notmuch://[absolute path]
- * @retval false url is not in required form.
+ * @retval true  url in form notmuch://[absolute path]
+ * @retval false url is not in required form
  */
 static bool is_valid_notmuch_url(const char *url)
 {
diff --git a/notmuch/notmuch.c b/notmuch/notmuch.c
index 901f1994a9c..7fa665590d8 100644
--- a/notmuch/notmuch.c
+++ b/notmuch/notmuch.c
@@ -1860,7 +1860,7 @@ static enum MxStatus nm_mbox_check_stats(struct Mailbox *m, uint8_t flags)
 
 /**
  * get_default_mailbox - Get Mailbox for notmuch without any parameters.
- * @retval ptr Mailbox pointer.
+ * @retval ptr Mailbox pointer
  */
 static struct Mailbox *get_default_mailbox(void)
 {
diff --git a/notmuch/query.c b/notmuch/query.c
index 054cbfcf1db..cb2efc6b1cc 100644
--- a/notmuch/query.c
+++ b/notmuch/query.c
@@ -38,8 +38,8 @@
 /**
  * nm_parse_type_from_query - Parse a query type out of a query
  * @param buf   Buffer for URL
- * @param fallback Fallback query type if buf doesn't contain a type= statement.
- * @retval Notmuch query type.
+ * @param fallback Fallback query type if buf doesn't contain a type= statement
+ * @retval num Notmuch query type, #NmQueryType
  *
  * If a user writes a query for a vfolder and includes a type= statement, that
  * type= will be encoded, which Notmuch will treat as part of the query=
diff --git a/pager/dlg_pager.c b/pager/dlg_pager.c
index e5cff30197e..7f65fcbd283 100644
--- a/pager/dlg_pager.c
+++ b/pager/dlg_pager.c
@@ -343,6 +343,7 @@ static void pager_custom_redraw(struct PagerPrivateData *priv)
  * pager_resolve_help_mapping - Determine help mapping based on pager mode and mailbox type
  * @param mode pager mode
  * @param type mailbox type
+ * @retval ptr Help Mapping
  */
 static const struct Mapping *pager_resolve_help_mapping(enum PagerMode mode, enum MailboxType type)
 {
diff --git a/pager/pbar.c b/pager/pbar.c
index 9ce75a35867..cfb8ab5682f 100644
--- a/pager/pbar.c
+++ b/pager/pbar.c
@@ -312,6 +312,9 @@ static void pbar_data_free(struct MuttWindow *win, void **ptr)
 
 /**
  * pbar_data_new - Free the private data attached to the MuttWindow
+ * @param shared Shared Index data
+ * @param priv   Private Index data
+ * @retval ptr New PBar
  */
 static struct PBarPrivateData *pbar_data_new(struct IndexSharedData *shared,
                                              struct PagerPrivateData *priv)
diff --git a/send/send.c b/send/send.c
index cf1903dfd4a..0b2fd11da43 100644
--- a/send/send.c
+++ b/send/send.c
@@ -652,7 +652,7 @@ void mutt_make_attribution(struct Email *e, FILE *fp_out, struct ConfigSubset *s
 }
 
 /**
- * greeting_string - Format a greetings string
+ * greeting_string - Format a greetings string - Implements ::format_t - @ingroup expando_api
  *
  * | Expando | Description
  * |:--------|:-----------------------------------------------------------------
diff --git a/sidebar/functions.c b/sidebar/functions.c
index 6b07dbb1dd1..e8e0ea41a20 100644
--- a/sidebar/functions.c
+++ b/sidebar/functions.c
@@ -65,7 +65,7 @@ bool select_next(struct SidebarWindowData *wdata)
  * @param wdata Sidebar data
  * @param begin Starting index for searching
  * @param end   Ending index for searching
- * @retval sbe  Pointer to the first entry with new messages
+ * @retval ptr  Pointer to the first entry with new messages
  * @retval NULL None could be found
  */
 static struct SbEntry **next_new(struct SidebarWindowData *wdata, size_t begin, size_t end)
@@ -136,7 +136,7 @@ bool select_prev(struct SidebarWindowData *wdata)
  * @param wdata Sidebar data
  * @param begin Starting index for searching
  * @param end   Ending index for searching
- * @retval sbe  Pointer to the first entry with new messages
+ * @retval ptr  Pointer to the first entry with new messages
  * @retval NULL None could be found
  */
 static struct SbEntry **prev_new(struct SidebarWindowData *wdata, size_t begin, size_t end)
diff --git a/sidebar/window.c b/sidebar/window.c
index 508c17bc7c0..2ee8985d224 100644
--- a/sidebar/window.c
+++ b/sidebar/window.c
@@ -191,6 +191,7 @@ static const char *abbrev_folder(const char *mbox, const char *folder, enum Mail
  * abbrev_url - Abbreviate a url-style Mailbox path
  * @param mbox Mailbox path to shorten
  * @param type Mailbox type
+ * @retval ptr mbox unchanged
  *
  * Use heuristics to shorten a non-local Mailbox path.
  * Strip the host part (or database part for Notmuch).
@@ -226,7 +227,7 @@ static const char *abbrev_url(const char *mbox, enum MailboxType type)
  * @param buf    Output buffer
  * @param buflen Size of output buffer
  * @param sbe    Sidebar entry
- * @retval Number of bytes written
+ * @retval num Bytes written
  */
 static size_t add_indent(char *buf, size_t buflen, const struct SbEntry *sbe)
 {
@@ -284,6 +285,7 @@ static enum ColorId calc_color(const struct Mailbox *m, bool current, bool highl
  * @param[in]  mbox      Mailbox path to examine
  * @param[in]  delims    Delimiter characters
  * @param[out] last_part Last path component
+ * @retval num Depth
  */
 static int calc_path_depth(const char *mbox, const char *delims, const char **last_part)
 {