doxy: tidy retvals

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
  */

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)
 {

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)
 {

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)
 {

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)

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

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)
 {

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)
 {

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)
 {

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)
 {

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)
 {

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)
 {

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.

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)

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)

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)
 {

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>]
  */

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)
 {

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)
 {

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)
 {

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)
 {

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)
 {

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)
 {

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.

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)
 {

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.
  */

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)
 {

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)
 {

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=

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)
 {

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)

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
  * |:--------|:-----------------------------------------------------------------