* @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
*
/**
* 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)
{
/**
* 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)
{
* 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
* 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);
* 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
* 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);
* 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);
* 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);
* @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
}
/**
- * 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)
{
/**
* 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)
{
/**
* 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)
{
/**
* 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.
/**
* 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)
{
* 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.
* 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.
*/
/**
* 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
*
/**
* 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)
{
* @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
*/
* @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)
{
/**
* 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).
*/
* @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)
{
* @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)
{
/**
* 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.
*/
* @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
* @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,
* @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)
/**
* 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.
* 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)
{
* @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
/**
* 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)
{
* 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.
*/
* 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.
*/
# 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
* 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>
/**
* 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
/**
* 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)
{
}
/**
- * 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
FREE(esp);
}
-/*
- * TODO:
- * very narrow screen might crash it
- * sort out the input side
- * unprintable chars
- */
* @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
/**
* 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)
{
}
/**
- * 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)
{
#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)
{
/**
* 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
* @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);
* @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);
* @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);
/**
* 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);
* @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);
* @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.
*/
* @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
/**
* 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().
*/
* @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);
* @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);
* @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);
* @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.
*/
/**
* 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
* @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)
{
}
/**
- * delete_hook - XXX
+ * delete_hook - Delete a Hook
+ * @param h Hook to delete
*/
static void delete_hook(struct Hook *h)
{
}
/**
- * 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)
{
* @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)
* @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.
*/
* @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)
* @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
*
* 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,
/**
* 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
* 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)
{
* 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)
{
* @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)
{
/**
* 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)
/**
* 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)
{
* @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[])
{
/**
* 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).
*/
* @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
* 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,
/**
* 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)
{
* 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'
* @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.
*/
* 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)
{
* @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;
* 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.
* @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.
* 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
/**
* 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
* @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.
*/
* @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.
*
/**
* 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)
{
* 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.
* @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.
*/
* @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.
* 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).
*/
* 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
* @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
* 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
* @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
* @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.
* @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)
* 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)
/**
* 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)
{
* 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.
* 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.
/**
* 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.
*/
/**
* 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`
* 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)
* 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)
{
* @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
* @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*.
*/
/**
* 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)
{
* 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)
{
* @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.
* @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)
{
* 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)
{
* @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)
{
* @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)
{
* @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
* @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)
{
* @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)
{
* @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)
{
/**
* 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)
{
* @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)
{
* 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)
{
/**
* 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
/**
* init_context - Add Notmuch data to the Context
- * @param ctx A mailbox CONTEXT
+ * @param ctx Mailbox
* @retval 0 Success
* @retval -1 Error Bad format
*
/**
* 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.
*/
/**
* 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
*/
/**
* 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)
{
/**
* nm_open_mailbox - Open a notmuch virtual mailbox
- * @param ctx A mailbox CONTEXT
+ * @param ctx Mailbox
* @retval 0 Success
* @retval -1 Error
*/
/**
* nm_close_mailbox - Close a notmuch virtual mailbox
- * @param ctx A mailbox CONTEXT
+ * @param ctx Mailbox
* @retval 0 Success
* @retval -1 Error
*/
/**
* 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)
{
/**
* 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)
/**
* 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
/**
* 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
* @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, ...)
/**
* 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)
/**
* 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.
/**
* 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)
{
/**
* 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)
{
/**
* 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)
{
#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)
{
/**
* 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)
{
}
/* 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);
* 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)
{
/**
* 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)
{
}
/**
- * 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)
{
/**
* 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.
*
/**
* 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)
{
/**
* 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)
{
/**
* 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.
/**
* 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.
* @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,
}
/**
- * 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)
{
* 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)
{
* 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)
{
/**
* 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)
{
* @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)
{
* 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
* @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)
* 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.
* 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)
{
* @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
*
#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()
*/
* @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)
* 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
* 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.
/**
* 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.
*/
* 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.
* @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)
{
/**
* 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.
*/
projects / neomutt / commitdiff