From: Richard Russon Date: Thu, 13 Jul 2017 01:28:05 +0000 (+0100) Subject: doxygen: tidy existing comments X-Git-Tag: neomutt-20170714~9 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=248186a37ff8652f941b38f6b2e6518a5bf96e32;p=neomutt doxygen: tidy existing comments --- diff --git a/address.h b/address.h index f2e052d4d..78304567e 100644 --- a/address.h +++ b/address.h @@ -22,9 +22,9 @@ struct Address { - char *personal; /* real name of address */ - char *mailbox; /* mailbox and host address */ - int group; /* group mailbox? */ + char *personal; /**< real name of address */ + char *mailbox; /**< mailbox and host address */ + int group; /**< group mailbox? */ struct Address *next; bool is_intl : 1; bool intl_checked : 1; diff --git a/attach.h b/attach.h index 6a40bd0e1..3c10e2685 100644 --- a/attach.h +++ b/attach.h @@ -34,7 +34,7 @@ struct AttachPtr char *tree; int level; int num; - bool unowned : 1; /* don't unlink on detach */ + bool unowned : 1; /**< don't unlink on detach */ }; struct AttachPtr **mutt_gen_attach_list(struct Body *m, int parent_type, struct AttachPtr **idx, diff --git a/base64.c b/base64.c index 10d6eadf9..a82b35fba 100644 --- a/base64.c +++ b/base64.c @@ -18,7 +18,6 @@ * these routines. These routines were written because IMAP's * AUTHENTICATE protocol required them, and base64 handling * elsewhere wasn't sufficiently generic. - * */ /* @@ -31,7 +30,6 @@ * S. Raymond. Portions are also copyrighted by Carl Harris, 1993 * and 1995. Copyright retained for the purpose of protecting free * redistribution of source. - * */ #include "config.h" @@ -49,13 +47,12 @@ static const char B64Chars[64] = { }; /** - * mutt_to_base64 - convert raw bytes to null-terminated base64 string. - * - * @param out Output buffer for the base64 encoded string. - * @param cin Input buffer for the raw bytes. - * @param len Length of the input buffer. - * @param olen Length of the output buffer. - * @return The length of the string written to the output buffer. + * mutt_to_base64 - convert raw bytes to null-terminated base64 string + * @param out Output buffer for the base64 encoded string + * @param cin Input buffer for the raw bytes + * @param len Length of the input buffer + * @param olen Length of the output buffer + * @return The 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 @@ -95,11 +92,10 @@ size_t mutt_to_base64(char *out, const char *cin, size_t len, size_t olen) } /** - * mutt_from_base64 - convert null-terminated base64 string to raw bytes. - * - * @param out Output buffer for the raw bytes. - * @param cin Input buffer for the null-terminated base64-encoded string - * @return The number of bytes written on success, -1 on error. + * mutt_from_base64 - 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 + * @return The number of bytes written on success, -1 on error * * This function performs base64 decoding. The resulting buffer is NOT * null-terminated. If the input buffer contains invalid base64 characters, diff --git a/body.h b/body.h index bc9d918de..5e2bc039d 100644 --- a/body.h +++ b/body.h @@ -24,77 +24,68 @@ struct Body { - char *xtype; /* content-type if x-unknown */ - char *subtype; /* content-type subtype */ - struct Parameter *parameter; /* parameters of the content-type */ - char *description; /* content-description */ - char *form_name; /* Content-Disposition form-data name param */ - long hdr_offset; /* offset in stream where the headers begin. - * this info is used when invoking metamail, - * where we need to send the headers of the - * attachment - */ - LOFF_T offset; /* offset where the actual data begins */ - LOFF_T length; /* length (in bytes) of attachment */ - char *filename; /* when sending a message, this is the file - * to which this structure refers - */ - char *d_filename; /* filename to be used for the - * content-disposition header. - * If NULL, filename is used - * instead. - */ - char *charset; /* charset of attached file */ - struct Content *content; /* structure used to store detailed info about - * the content of the attachment. this is used - * to determine what content-transfer-encoding - * is required when sending mail. - */ - struct Body *next; /* next attachment in the list */ - struct Body *parts; /* parts of a multipart or message/rfc822 */ - struct Header *hdr; /* header information for message/rfc822 */ + char *xtype; /**< content-type if x-unknown */ + char *subtype; /**< content-type subtype */ + struct Parameter *parameter; /**< parameters of the content-type */ + char *description; /**< content-description */ + char *form_name; /**< Content-Disposition form-data name param */ + long hdr_offset; /**< offset in stream where the headers begin. + * this info is used when invoking metamail, + * where we need to send the headers of the + * attachment */ + LOFF_T offset; /**< offset where the actual data begins */ + LOFF_T length; /**< length (in bytes) of attachment */ + char *filename; /**< when sending a message, this is the file + * to which this structure refers */ + char *d_filename; /**< filename to be used for the + * content-disposition header. + * If NULL, filename is used + * instead. */ + char *charset; /**< charset of attached file */ + struct Content *content; /**< structure used to store detailed info about + * the content of the attachment. this is used + * to determine what content-transfer-encoding + * is required when sending mail. */ + struct Body *next; /**< next attachment in the list */ + struct Body *parts; /**< parts of a multipart or message/rfc822 */ + struct Header *hdr; /**< header information for message/rfc822 */ - struct AttachPtr *aptr; /* Menu information, used in recvattach.c */ + struct AttachPtr *aptr; /**< Menu information, used in recvattach.c */ signed short attach_count; - time_t stamp; /* time stamp of last - * encoding update. - */ + time_t stamp; /**< time stamp of last encoding update. */ - unsigned int type : 4; /* content-type primary type */ - unsigned int encoding : 3; /* content-transfer-encoding */ - unsigned int disposition : 2; /* content-disposition */ - bool use_disp : 1; /* Content-Disposition uses filename= ? */ - bool unlink : 1; /* flag to indicate the file named by + unsigned int type : 4; /**< content-type primary type */ + unsigned int encoding : 3; /**< content-transfer-encoding */ + unsigned int disposition : 2; /**< content-disposition */ + bool use_disp : 1; /**< Content-Disposition uses filename= ? */ + bool unlink : 1; /**< flag to indicate the file named by * "filename" should be unlink()ed before - * free()ing this structure - */ + * free()ing this structure */ bool tagged : 1; - bool deleted : 1; /* attachment marked for deletion */ + bool deleted : 1; /**< attachment marked for deletion */ - bool noconv : 1; /* don't do character set conversion */ + bool noconv : 1; /**< don't do character set conversion */ bool force_charset : 1; - /* send mode: don't adjust the character + /**< send mode: don't adjust the character * set when in send-mode. */ - bool is_signed_data : 1; /* A lot of MUAs don't indicate - S/MIME signed-data correctly, - e.g. they use foo.p7m even for - the name of signed data. This - flag is used to keep track of - the actual message type. It - gets set during the verification - (which is done if the encryption - try failed) and check by the - function to figure the type of - the message. */ + bool is_signed_data : 1; /**< A lot of MUAs don't indicate S/MIME + * signed-data correctly, e.g. they use foo.p7m + * even for the name of signed data. This flag + * is used to keep track of the actual message + * type. It gets set during the verification + * (which is done if the encryption try failed) + * and check by the function to figure the type + * of the message. */ - bool goodsig : 1; /* good cryptographic signature */ - bool warnsig : 1; /* maybe good signature */ - bool badsig : 1; /* bad cryptographic signature (needed to check encrypted s/mime-signatures) */ + bool goodsig : 1; /**< good cryptographic signature */ + bool warnsig : 1; /**< maybe good signature */ + bool badsig : 1; /**< bad cryptographic signature (needed to + * check encrypted s/mime-signatures) */ - bool collapsed : 1; /* used by recvattach */ + bool collapsed : 1; /**< used by recvattach */ bool attach_qualifies : 1; }; diff --git a/browser.h b/browser.h index 075a21d3d..8a5443daf 100644 --- a/browser.h +++ b/browser.h @@ -34,9 +34,9 @@ struct FolderFile char *name; char *desc; - bool new; /* true if mailbox has "new mail" */ - int msg_count; /* total number of messages */ - int msg_unread; /* number of unread messages */ + bool new; /**< true if mailbox has "new mail" */ + int msg_count; /**< total number of messages */ + int msg_unread; /**< number of unread messages */ #ifdef USE_IMAP char delim; @@ -49,15 +49,15 @@ struct FolderFile #ifdef USE_NNTP struct NntpData *nd; #endif - bool local : 1; /* folder is on local filesystem */ + bool local : 1; /**< folder is on local filesystem */ bool tagged : 1; }; struct BrowserState { struct FolderFile *entry; - unsigned int entrylen; /* number of real entries */ - unsigned int entrymax; /* max entry */ + unsigned int entrylen; /**< number of real entries */ + unsigned int entrymax; /**< max entry */ #ifdef USE_IMAP bool imap_browse; char *folder; diff --git a/buffer.h b/buffer.h index 57d57c0b0..1d088047d 100644 --- a/buffer.h +++ b/buffer.h @@ -20,10 +20,10 @@ struct Buffer { - char *data; /* pointer to data */ - char *dptr; /* current read/write position */ - size_t dsize; /* length of data */ - int destroy; /* destroy `data' when done? */ + char *data; /**< pointer to data */ + char *dptr; /**< current read/write position */ + size_t dsize; /**< length of data */ + int destroy; /**< destroy `data' when done? */ }; /* flags for mutt_extract_token() */ diff --git a/buffy.h b/buffy.h index e27645a37..a4b0ff7ea 100644 --- a/buffy.h +++ b/buffy.h @@ -33,23 +33,23 @@ struct stat; struct Buffy { char path[_POSIX_PATH_MAX]; - char realpath[_POSIX_PATH_MAX]; /* used for duplicate detection, context comparison, - and the sidebar */ + char realpath[_POSIX_PATH_MAX]; /**< used for duplicate detection, context + * comparison, and the sidebar */ char *desc; off_t size; struct Buffy *next; - bool new; /* mailbox has new mail */ + bool new; /**< mailbox has new mail */ /* These next three are only set when OPTMAILCHECKSTATS is set */ - int msg_count; /* total number of messages */ - int msg_unread; /* number of unread messages */ - int msg_flagged; /* number of flagged messages */ + int msg_count; /**< total number of messages */ + int msg_unread; /**< number of unread messages */ + int msg_flagged; /**< number of flagged messages */ - bool notified; /* user has been notified */ - short magic; /* mailbox type */ - bool newly_created; /* mbox or mmdf just popped into existence */ - time_t last_visited; /* time of last exit from this mailbox */ - time_t stats_last_checked; /* mtime of mailbox the last time stats where checked. */ + bool notified; /**< user has been notified */ + short magic; /**< mailbox type */ + bool newly_created; /**< mbox or mmdf just popped into existence */ + time_t last_visited; /**< time of last exit from this mailbox */ + time_t stats_last_checked; /**< mtime of mailbox the last time stats where checked. */ }; WHERE struct Buffy *Incoming INITVAL(0); diff --git a/compose.c b/compose.c index 74f86fc37..4b5287fe0 100644 --- a/compose.c +++ b/compose.c @@ -581,7 +581,6 @@ static void compose_menu_redraw(struct Menu *menu) * Returns the total number of bytes used by the attachments in the * attachment list _after_ content-transfer-encodings have been * applied. - * */ static unsigned long cum_attachs_size(struct Menu *menu) { diff --git a/compress.c b/compress.c index afad69623..48ed1bd34 100644 --- a/compress.c +++ b/compress.c @@ -49,28 +49,27 @@ struct Header; */ struct CompressInfo { - const char *append; /* append-hook command */ - const char *close; /* close-hook command */ - const char *open; /* open-hook command */ - off_t size; /* size of the compressed file */ - struct MxOps *child_ops; /* callbacks of de-compressed file */ - int locked; /* if realpath is locked */ - FILE *lockfp; /* fp used for locking */ + const char *append; /**< append-hook command */ + const char *close; /**< close-hook command */ + const char *open; /**< open-hook command */ + off_t size; /**< size of the compressed file */ + struct MxOps *child_ops; /**< callbacks of de-compressed file */ + int locked; /**< if realpath is locked */ + FILE *lockfp; /**< fp used for locking */ }; /** * lock_realpath - Try to lock the ctx->realpath - * @ctx: Mailbox to lock - * @excl: Lock exclusively? + * @param ctx Mailbox to lock + * @param excl Lock exclusively? + * @return + * * 1: Success (locked or readonly) + * * 0: Error (can't lock the file) * * Try to (exclusively) lock the mailbox. If we succeed, then we mark the * mailbox as locked. If we fail, but we didn't want exclusive rights, then * the mailbox will be marked readonly. - * - * Returns: - * 1: Success (locked or readonly) - * 0: Error (can't lock the file) */ static int lock_realpath(struct Context *ctx, int excl) { @@ -110,7 +109,7 @@ static int lock_realpath(struct Context *ctx, int excl) /** * unlock_realpath - Unlock the ctx->realpath - * @ctx: Mailbox to unlock + * @param ctx Mailbox to unlock * * Unlock a mailbox previously locked by lock_mailbox(). */ @@ -134,15 +133,14 @@ static void unlock_realpath(struct Context *ctx) /** * setup_paths - Set the mailbox paths - * @ctx: Mailbox to modify + * @param ctx Mailbox to modify + * @return + * * 0: Success + * * -1: Error * * Save the compressed filename in ctx->realpath. * Create a temporary filename and put its name in ctx->path. * The temporary file is created to prevent symlink attacks. - * - * Returns: - * 0: Success - * -1: Error */ static int setup_paths(struct Context *ctx) { @@ -169,11 +167,10 @@ static int setup_paths(struct Context *ctx) /** * get_size - Get the size of a file - * @path: File to measure - * - * Returns: - * number: Size in bytes - * 0: On error + * @param path File to measure + * @return + * * number: Size in bytes + * * 0: On error */ static int get_size(const char *path) { @@ -189,7 +186,7 @@ static int get_size(const char *path) /** * store_size - Save the size of the compressed file - * @ctx: Mailbox + * @param ctx Mailbox * * Save the compressed file size in the compress_info struct. */ @@ -207,8 +204,11 @@ static void store_size(const struct Context *ctx) /** * find_hook - Find a hook to match a path - * @type: Type of hook, e.g. MUTT_CLOSEHOOK - * @path: Filename to test + * @param type Type of hook, e.g. MUTT_CLOSEHOOK + * @param path Filename to test + * @return + * * string: Matching hook command + * * NULL: No matches * * Each hook has a type and a pattern. * Find a command that matches the type and path supplied. e.g. @@ -218,10 +218,6 @@ static void store_size(const struct Context *ctx) * * Call: * find_hook (MUTT_OPENHOOK, "myfile.gz"); - * - * Returns: - * string: Matching hook command - * NULL: No matches */ static const char *find_hook(int type, const char *path) { @@ -237,13 +233,12 @@ static const char *find_hook(int type, const char *path) /** * set_compress_info - Find the compress hooks for a mailbox - * @ctx: Mailbox to examine + * @param ctx Mailbox to examine + * @return + * * CompressInfo: Hook info for the mailbox's path + * * NULL: On error * * When a mailbox is opened, we check if there are any matching hooks. - * - * Returns: - * CompressInfo: Hook info for the mailbox's path - * NULL: On error */ static struct CompressInfo *set_compress_info(struct Context *ctx) { @@ -272,8 +267,8 @@ static struct CompressInfo *set_compress_info(struct Context *ctx) } /** - * free_compress_info - Frees the compress info members and structure. - * @ctx: Mailbox to free compress_info for. + * free_compress_info - Frees the compress info members and structure + * @param ctx Mailbox to free compress_info for */ static void free_compress_info(struct Context *ctx) { @@ -293,10 +288,9 @@ static void free_compress_info(struct Context *ctx) } /** - * escape_path - Escapes single quotes in a path for a command string. - * @src - the path to escape. - * - * Returns: a pointer to the escaped string. + * escape_path - Escapes single quotes in a path for a command string + * @param src the path to escape + * @return a pointer to the escaped string */ static char *escape_path(char *src) { @@ -336,22 +330,21 @@ static char *escape_path(char *src) /** * cb_format_str - Expand the filenames in the command string - * @dest: Buffer in which to save string - * @destlen: Buffer length - * @col: Starting column, UNUSED - * @cols: Number of screen columns, UNUSED - * @op: printf-like operator, e.g. 't' - * @src: printf-like format string - * @fmt: Field formatting string, UNUSED - * @ifstring: If condition is met, display this string, UNUSED - * @elsestring: Otherwise, display this string, UNUSED - * @data: Pointer to the mailbox Context - * @flags: Format flags, UNUSED + * @param dest Buffer in which to save string + * @param destlen Buffer length + * @param col Starting column, UNUSED + * @param cols Number of screen columns, UNUSED + * @param op printf-like operator, e.g. 't' + * @param src printf-like format string + * @param fmt Field formatting string, UNUSED + * @param ifstring If condition is met, display this string, UNUSED + * @param elsestring Otherwise, display this string, UNUSED + * @param data Pointer to the mailbox Context + * @param flags Format flags, UNUSED + * @return src (unchanged) * * cb_format_str is a callback function for mutt_FormatString. It understands * two operators. '%f' : 'from' filename, '%t' : 'to' filename. - * - * Returns: src (unchanged) */ static const char *cb_format_str(char *dest, size_t destlen, size_t col, int cols, char op, const char *src, const char *fmt, @@ -379,9 +372,10 @@ static const char *cb_format_str(char *dest, size_t destlen, size_t col, int col /** * expand_command_str - Expand placeholders in command string - * @ctx: Mailbox for paths - * @buf: Buffer to store the command - * @buflen: Size of the buffer + * @param ctx Mailbox for paths + * @param cmd Template command to be expanded + * @param buf Buffer to store the command + * @param buflen Size of the buffer * * This function takes a hook command and expands the filename placeholders * within it. The function calls mutt_FormatString() to do the replacement @@ -403,16 +397,15 @@ static void expand_command_str(const struct Context *ctx, const char *cmd, char /** * execute_command - Run a system command - * @ctx: Mailbox to work with - * @command: Command string to execute - * @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 + * @return + * * 1: Success + * * 0: Failure * * Run the supplied command, taking care of all the Mutt requirements, * such as locking files and blocking signals. - * - * Returns: - * 1: Success - * 0: Failure */ static int execute_command(struct Context *ctx, const char *command, const char *progress) { @@ -445,7 +438,7 @@ static int execute_command(struct Context *ctx, const char *command, const char /** * comp_open_mailbox - Open a compressed mailbox - * @ctx: Mailbox to open + * @param ctx Mailbox to open * * Set up a compressed mailbox to be read. * Decompress the mailbox and set up the paths and hooks needed. @@ -506,15 +499,14 @@ or_fail: /** * comp_open_append_mailbox - Open a compressed mailbox for appending - * @ctx: Mailbox to open - * @flags: e.g. Does the file already exist? + * @param ctx Mailbox to open + * @param flags e.g. Does the file already exist? + * @return + * * 0: Success + * * -1: Failure * * To append to a compressed mailbox we need an append-hook (or both open- and * close-hooks). - * - * Returns: - * 0: Success - * -1: Failure */ static int comp_open_append_mailbox(struct Context *ctx, int flags) { @@ -589,14 +581,13 @@ oa_fail1: /** * comp_close_mailbox - Close a compressed mailbox - * @ctx: Mailbox to close + * @param ctx Mailbox to close + * @return + * * 0: Success + * * -1: Failure * * If the mailbox has been changed then re-compress the tmp file. * Then delete the tmp file. - * - * Returns: - * 0: Success - * -1: Failure */ static int comp_close_mailbox(struct Context *ctx) { @@ -665,7 +656,12 @@ static int comp_close_mailbox(struct Context *ctx) /** * comp_check_mailbox - Check for changes in the compressed file - * @ctx: Mailbox + * @param ctx Mailbox + * @param index_hint Currently selected mailbox + * @return + * * 0: Mailbox OK + * * MUTT_REOPENED: The mailbox was closed and reopened + * * -1: Mailbox bad * * If the compressed file changes in size but the mailbox hasn't been changed * in Mutt, then we can close and reopen the mailbox. @@ -673,11 +669,6 @@ static int comp_close_mailbox(struct Context *ctx) * If the mailbox has been changed in Mutt, warn the user. * * The return codes are picked to match mx_check_mailbox(). - * - * Returns: - * 0: Mailbox OK - * MUTT_REOPENED: The mailbox was closed and reopened - * -1: Mailbox bad */ static int comp_check_mailbox(struct Context *ctx, int *index_hint) { @@ -795,16 +786,15 @@ static int comp_open_new_message(struct Message *msg, struct Context *ctx, struc /** * mutt_comp_can_append - Can we append to this path? - * @path: pathname of file to be tested + * @param ctx Mailbox + * @return + * * true: Yes, we can append to the file + * * false: No, appending isn't possible * * To append to a file we can either use an 'append-hook' or a combination of * 'open-hook' and 'close-hook'. * * A match means it's our responsibility to append to the file. - * - * Returns: - * true: Yes, we can append to the file - * false: No, appending isn't possible */ bool mutt_comp_can_append(struct Context *ctx) { @@ -827,15 +817,14 @@ bool mutt_comp_can_append(struct Context *ctx) /** * mutt_comp_can_read - Can we read from this file? - * @path: Pathname of file to be tested + * @param path Pathname of file to be tested + * @return + * * true: Yes, we can read the file + * * false: No, we cannot read the file * * Search for an 'open-hook' with a regex that matches the path. * * A match means it's our responsibility to open the file. - * - * Returns: - * true: Yes, we can read the file - * false: No, we cannot read the file */ bool mutt_comp_can_read(const char *path) { @@ -850,14 +839,14 @@ bool mutt_comp_can_read(const char *path) /** * comp_sync_mailbox - Save changes to the compressed mailbox file - * @ctx: Mailbox to sync + * @param ctx Mailbox to sync + * @param index_hint Currently selected mailbox + * @return + * * 0: Success + * * -1: Failure * * Changes in Mutt only affect the tmp file. Calling comp_sync_mailbox() * will commit them to the compressed file. - * - * Returns: - * 0: Success - * -1: Failure */ static int comp_sync_mailbox(struct Context *ctx, int *index_hint) { @@ -909,14 +898,13 @@ sync_cleanup: /** * mutt_comp_valid_command - Is this command string allowed? - * @cmd: Command string + * @param cmd Command string + * @return + * * 1: Valid command + * * 0: "%f" and/or "%t" is missing * * A valid command string must have both "%f" (from file) and "%t" (to file). * We don't check if we can actually run the command. - * - * Returns: - * 1: Valid command - * 0: "%f" and/or "%t" is missing */ int mutt_comp_valid_command(const char *cmd) { diff --git a/content.h b/content.h index 4cf5928f4..68fde9937 100644 --- a/content.h +++ b/content.h @@ -23,16 +23,16 @@ /* Information that helps in determining the Content-* of an attachment */ struct Content { - long hibin; /* 8-bit characters */ - long lobin; /* unprintable 7-bit chars (eg., control chars) */ - long crlf; /* '\r' and '\n' characters */ - long ascii; /* number of ascii chars */ - long linemax; /* length of the longest line in the file */ - bool space : 1; /* whitespace at the end of lines? */ - bool binary : 1; /* long lines, or CR not in CRLF pair */ - bool from : 1; /* has a line beginning with "From "? */ - bool dot : 1; /* has a line consisting of a single dot? */ - bool cr : 1; /* has CR, even when in a CRLF pair */ + long hibin; /**< 8-bit characters */ + long lobin; /**< unprintable 7-bit chars (eg., control chars) */ + long crlf; /**< `\r` and `\n` characters */ + long ascii; /**< number of ascii chars */ + long linemax; /**< length of the longest line in the file */ + bool space : 1; /**< whitespace at the end of lines? */ + bool binary : 1; /**< long lines, or CR not in CRLF pair */ + bool from : 1; /**< has a line beginning with "From "? */ + bool dot : 1; /**< has a line consisting of a single dot? */ + bool cr : 1; /**< has CR, even when in a CRLF pair */ }; #endif /* _MUTT_CONTENT_H */ diff --git a/context.h b/context.h index bb49a59c5..a13988520 100644 --- a/context.h +++ b/context.h @@ -44,54 +44,54 @@ enum AclRights struct Context { char *path; - char *realpath; /* used for buffy comparison and the sidebar */ + char *realpath; /**< used for buffy comparison and the sidebar */ FILE *fp; time_t atime; time_t mtime; off_t size; off_t vsize; - char *pattern; /* limit pattern string */ - struct Pattern *limit_pattern; /* compiled limit pattern */ + char *pattern; /**< limit pattern string */ + struct Pattern *limit_pattern; /**< compiled limit pattern */ struct Header **hdrs; - struct Header *last_tag; /* last tagged msg. used to link threads */ - struct MuttThread *tree; /* top of thread tree */ - struct Hash *id_hash; /* hash table by msg id */ - struct Hash *subj_hash; /* hash table by subject */ - struct Hash *thread_hash; /* hash table for threading */ - struct Hash *label_hash; /* hash table for x-labels */ - int *v2r; /* mapping from virtual to real msgno */ - int hdrmax; /* number of pointers in hdrs */ - int msgcount; /* number of messages in the mailbox */ - int vcount; /* the number of virtual messages */ - int tagged; /* how many messages are tagged? */ - int new; /* how many new messages? */ - int unread; /* how many unread messages? */ - int deleted; /* how many deleted messages */ - int flagged; /* how many flagged messages */ - int msgnotreadyet; /* which msg "new" in pager, -1 if none */ + struct Header *last_tag; /**< last tagged msg. used to link threads */ + struct MuttThread *tree; /**< top of thread tree */ + struct Hash *id_hash; /**< hash table by msg id */ + struct Hash *subj_hash; /**< hash table by subject */ + struct Hash *thread_hash; /**< hash table for threading */ + struct Hash *label_hash; /**< hash table for x-labels */ + int *v2r; /**< mapping from virtual to real msgno */ + int hdrmax; /**< number of pointers in hdrs */ + int msgcount; /**< number of messages in the mailbox */ + int vcount; /**< the number of virtual messages */ + int tagged; /**< how many messages are tagged? */ + int new; /**< how many new messages? */ + int unread; /**< how many unread messages? */ + int deleted; /**< how many deleted messages */ + int flagged; /**< how many flagged messages */ + int msgnotreadyet; /**< which msg "new" in pager, -1 if none */ - struct Menu *menu; /* needed for pattern compilation */ + struct Menu *menu; /**< needed for pattern compilation */ - short magic; /* mailbox type */ + short magic; /**< mailbox type */ - unsigned char rights[(RIGHTSMAX + 7) / 8]; /* ACL bits */ + unsigned char rights[(RIGHTSMAX + 7) / 8]; /**< ACL bits */ - bool locked : 1; /* is the mailbox locked? */ - bool changed : 1; /* mailbox has been modified */ - bool readonly : 1; /* don't allow changes to the mailbox */ - bool dontwrite : 1; /* don't write the mailbox on close */ - bool append : 1; /* mailbox is opened in append mode */ - bool quiet : 1; /* inhibit status messages? */ - bool collapsed : 1; /* are all threads collapsed? */ - bool closing : 1; /* mailbox is being closed */ - bool peekonly : 1; /* just taking a glance, revert atime */ + bool locked : 1; /**< is the mailbox locked? */ + bool changed : 1; /**< mailbox has been modified */ + bool readonly : 1; /**< don't allow changes to the mailbox */ + bool dontwrite : 1; /**< don't write the mailbox on close */ + bool append : 1; /**< mailbox is opened in append mode */ + bool quiet : 1; /**< inhibit status messages? */ + bool collapsed : 1; /**< are all threads collapsed? */ + bool closing : 1; /**< mailbox is being closed */ + bool peekonly : 1; /**< just taking a glance, revert atime */ #ifdef USE_COMPRESSED - void *compress_info; /* compressed mbox module private data */ -#endif /* USE_COMPRESSED */ + void *compress_info; /**< compressed mbox module private data */ +#endif /**< USE_COMPRESSED */ /* driver hooks */ - void *data; /* driver specific data */ + void *data; /**< driver specific data */ struct MxOps *mx_ops; }; diff --git a/curs_lib.c b/curs_lib.c index b39808e84..bdc82c71f 100644 --- a/curs_lib.c +++ b/curs_lib.c @@ -473,9 +473,9 @@ void mutt_progress_init(struct Progress *progress, const char *msg, /** * message_bar - Draw a colourful progress bar - * @percent: %age complete - * @fmt: printf(1)-like formatting string - * @...: Arguments to formatting string + * @param percent %age complete + * @param fmt printf(1)-like formatting string + * @param ... Arguments to formatting string */ static void message_bar(int percent, const char *fmt, ...) { diff --git a/curs_main.c b/curs_main.c index b9b6f725c..67c11cecb 100644 --- a/curs_main.c +++ b/curs_main.c @@ -150,9 +150,9 @@ static char *fsl = "\007"; * @param toggle toggle collapsed state * * This function is called by the OP_MAIN_COLLAPSE_ALL command and on folder - * enter if the OPTCOLLAPSEALL option is set. In the first case, the @toggle + * enter if the OPTCOLLAPSEALL option is set. In the first case, the @a toggle * parameter is 1 to actually toggle collapsed/uncollapsed state on all - * threads. In the second case, the @toggle parameter is 0, actually turning + * threads. In the second case, the @a toggle parameter is 0, actually turning * this function into a one-way collapse. */ static void collapse_all(struct Menu *menu, int toggle) @@ -668,8 +668,9 @@ int index_color(int index_no) /** * mutt_draw_statusline - Draw a highlighted status bar - * @cols: Maximum number of screen columns - * @buf: Message to be displayed + * @param cols Maximum number of screen columns + * @param buf Message to be displayed + * @param buflen Length of the buffer * * Users configure the highlighting of the status bar, e.g. * color status red default "[0-9][0-9]:[0-9][0-9]" diff --git a/enter.c b/enter.c index a9a27876a..4aa053207 100644 --- a/enter.c +++ b/enter.c @@ -37,8 +37,8 @@ /* redraw flags for mutt_enter_string() */ enum RedrawFlags { - MUTT_REDRAW_INIT = 1, /* go to end of line and redraw */ - MUTT_REDRAW_LINE /* redraw entire line */ + MUTT_REDRAW_INIT = 1, /**< go to end of line and redraw */ + MUTT_REDRAW_LINE /**< redraw entire line */ }; static int my_wcwidth(wchar_t wc) diff --git a/envelope.h b/envelope.h index 07dced0ba..6f585b995 100644 --- a/envelope.h +++ b/envelope.h @@ -32,10 +32,10 @@ struct Envelope struct Address *reply_to; struct Address *mail_followup_to; struct Address *x_original_to; - char *list_post; /* this stores a mailto URL, or nothing */ + char *list_post; /**< this stores a mailto URL, or nothing */ char *subject; - char *real_subj; /* offset of the real subject */ - char *disp_subj; /* display subject (modified copy of subject) */ + char *real_subj; /**< offset of the real subject */ + char *disp_subj; /**< display subject (modified copy of subject) */ char *message_id; char *supersedes; char *date; @@ -48,13 +48,13 @@ struct Envelope char *x_comment_to; #endif struct Buffer *spam; - struct List *references; /* message references (in reverse order) */ - struct List *in_reply_to; /* in-reply-to header content */ - struct List *userhdrs; /* user defined headers */ + struct List *references; /**< message references (in reverse order) */ + struct List *in_reply_to; /**< in-reply-to header content */ + struct List *userhdrs; /**< user defined headers */ int kwtypes; - bool irt_changed : 1; /* In-Reply-To changed to link/break threads */ - bool refs_changed : 1; /* References changed to break thread */ + bool irt_changed : 1; /**< In-Reply-To changed to link/break threads */ + bool refs_changed : 1; /**< References changed to break thread */ }; static inline struct Envelope *mutt_new_envelope(void) diff --git a/format_flags.h b/format_flags.h index 74c6d6dcd..9166ea48f 100644 --- a/format_flags.h +++ b/format_flags.h @@ -23,14 +23,14 @@ /* flags for mutt_FormatString() */ enum FormatFlag { - MUTT_FORMAT_FORCESUBJ = (1 << 0), /* print the subject even if unchanged */ - MUTT_FORMAT_TREE = (1 << 1), /* draw the thread tree */ - MUTT_FORMAT_MAKEPRINT = (1 << 2), /* make sure that all chars are printable */ + MUTT_FORMAT_FORCESUBJ = (1 << 0), /**< print the subject even if unchanged */ + MUTT_FORMAT_TREE = (1 << 1), /**< draw the thread tree */ + MUTT_FORMAT_MAKEPRINT = (1 << 2), /**< make sure that all chars are printable */ MUTT_FORMAT_OPTIONAL = (1 << 3), - MUTT_FORMAT_STAT_FILE = (1 << 4), /* used by mutt_attach_fmt */ - MUTT_FORMAT_ARROWCURSOR = (1 << 5), /* reserve space for arrow_cursor */ - MUTT_FORMAT_INDEX = (1 << 6), /* this is a main index entry */ - MUTT_FORMAT_NOFILTER = (1 << 7) /* do not allow filtering on this pass */ + MUTT_FORMAT_STAT_FILE = (1 << 4), /**< used by mutt_attach_fmt */ + MUTT_FORMAT_ARROWCURSOR = (1 << 5), /**< reserve space for arrow_cursor */ + MUTT_FORMAT_INDEX = (1 << 6), /**< this is a main index entry */ + MUTT_FORMAT_NOFILTER = (1 << 7) /**< do not allow filtering on this pass */ }; typedef const char *format_t(char *dest, size_t destlen, size_t col, int cols, diff --git a/functions.h b/functions.h index 7338ee20d..11c915d52 100644 --- a/functions.h +++ b/functions.h @@ -29,7 +29,6 @@ * * - The magic "map:" comments define how the map will be called in the * manual. Lines starting with "**" will be included in the manual. - * */ #ifdef _MAKEDOC diff --git a/handler.c b/handler.c index 11b8b0923..c78b55581 100644 --- a/handler.c +++ b/handler.c @@ -262,7 +262,6 @@ static void qp_decode_line(char *dest, char *src, size_t *l, int last) * * Just to make sure that I didn't make some off-by-one error * above, we just use STRING*2 for the target buffer's size. - * */ static void decode_quoted(struct State *s, long len, int istext, iconv_t cd) { diff --git a/hash.h b/hash.h index d72dbb1f0..b4114ba3f 100644 --- a/hash.h +++ b/hash.h @@ -35,8 +35,8 @@ struct HashElem struct Hash { int nelem, curnelem; - bool strdup_keys : 1; /* if set, the key->strkey is strdup'ed */ - bool allow_dups : 1; /* if set, duplicate keys are allowed */ + bool strdup_keys : 1; /**< if set, the key->strkey is strdup'ed */ + bool allow_dups : 1; /**< if set, duplicate keys are allowed */ struct HashElem **table; unsigned int (*gen_hash)(union HashKey, unsigned int); int (*cmp_key)(union HashKey, union HashKey); diff --git a/hcache/backend.h b/hcache/backend.h index 36d0b9a85..a84c29d11 100644 --- a/hcache/backend.h +++ b/hcache/backend.h @@ -24,10 +24,9 @@ #include /** - * hcache_open_t - backend-specific routing to open the header cache database. - * - * @param path The path to the database file. - * @return Pointer to backend-specific context on success, NULL otherwise. + * hcache_open_t - backend-specific routing to open the header cache database + * @param path The path to the database file + * @return Pointer to backend-specific context on success, 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 @@ -38,61 +37,56 @@ typedef void *(*hcache_open_t)(const char *path); /** - * hcache_fetch_t - backend-specific routine to fetch a message's headers. - * - * @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. - * @return Pointer to the message's headers on success, NULL otherwise. + * hcache_fetch_t - backend-specific routine to fetch a message's headers + * @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 + * @return Pointer to the message's headers on success, NULL otherwise */ typedef void *(*hcache_fetch_t)(void *ctx, const char *key, size_t keylen); /** - * hcache_free_t - backend-specific routine to free fetched data. - * - * @param ctx The backend-specific context retrieved via hcache_open. + * hcache_free_t - backend-specific routine to free fetched data + * @param ctx The backend-specific context retrieved via hcache_open * @param data A pointer to the data got with hcache_fetch or hcache_fetch_raw */ typedef void (*hcache_free_t)(void *ctx, void **data); /** - * hcache_store_t - backend-specific routine to store a message's headers. - * - * @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. - * @param data The message headers data. - * @param datalen The length of the string pointed to by data. - * @return 0 on success, a backend-specific error code otherwise. + * hcache_store_t - backend-specific routine to store a message's headers + * @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 + * @param data The message headers data + * @param datalen The length of the string pointed to by data + * @return 0 on success, a backend-specific error code otherwise */ typedef int (*hcache_store_t)(void *ctx, const char *key, size_t keylen, void *data, size_t datalen); /** - * hcache_delete_t - backend-specific routine to delete a message's headers. - * - * @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. - * @return 0 on success, a backend-specific error code otherwise. + * hcache_delete_t - backend-specific routine to delete a message's headers + * @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 + * @return 0 on success, a backend-specific error code otherwise */ typedef int (*hcache_delete_t)(void *ctx, const char *key, size_t keylen); /** - * hcache_close_t - backend-specific routine to close a context. - * - * @param ctx The backend-specific context retrieved via hcache_open. + * hcache_close_t - backend-specific routine to close a context + * @param ctx The backend-specific context retrieved via hcache_open * * Backend code is responsible for freeing any resources associated with the - * @ctx parameter. For this reason, backend code is passed a pointer-to-pointer + * @a ctx parameter. For this reason, backend code is passed a pointer-to-pointer * to the context, so that FREE can be invoked on it. */ typedef void (*hcache_close_t)(void **ctx); /** - * hcache_backend_t - backend-specific identification string. + * hcache_backend_t - backend-specific identification string * - * @return String describing the currently used hcache backend. + * @return String describing the currently used hcache backend */ typedef const char *(*hcache_backend_t)(void); diff --git a/hcache/hcache.c b/hcache/hcache.c index 5443f5a45..34d7fee08 100644 --- a/hcache/hcache.c +++ b/hcache/hcache.c @@ -526,10 +526,10 @@ static int crc_matches(const char *d, unsigned int crc) /** * create_hcache_dir - Create parent dirs for the hcache database - * @path: Database filename - * - * @retval true Success - * @retval false Failure (errno set) + * @param path Database filename + * @return + * * true Success + * * false Failure (errno set) */ static bool create_hcache_dir(const char *path) { @@ -557,25 +557,24 @@ static bool create_hcache_dir(const char *path) * @param path Base directory, from $header_cache * @param folder Mailbox name (including protocol) * @param namer Callback to generate database filename - * * @return Full pathname to the database (to be generated) * (path must be freed by the caller) * * Generate the pathname for the hcache database, it will be of the form: * BASE/FOLDER/NAME-SUFFIX * - * BASE : Base directory (@path) - * FOLDER: Mailbox name (@folder) - * NAME: Create by @namer, or md5sum of @folder + * BASE : Base directory (@a path) + * FOLDER: Mailbox name (@a folder) + * NAME: Create by @a namer, or md5sum of @a folder * SUFFIX: Character set (if ICONV isn't being used) * * This function will create any parent directories needed, so the caller just * needs to create the database file. * - * If @path exists and is a directory, it is used. - * If @path has a trailing '/' it is assumed to be a directory. + * If @a path exists and is a directory, it is used. + * If @a path has a trailing '/' it is assumed to be a directory. * If ICONV isn't being used, then a suffix is added to the path, e.g. '-utf-8'. - * Otherise @path is assumed to be a file. + * Otherise @a path is assumed to be a file. */ static const char *hcache_per_folder(const char *path, const char *folder, hcache_namer_t namer) { diff --git a/hcache/hcache.h b/hcache/hcache.h index a2622c1d2..df82464ad 100644 --- a/hcache/hcache.h +++ b/hcache/hcache.h @@ -29,119 +29,110 @@ typedef struct HeaderCache header_cache_t; typedef int (*hcache_namer_t)(const char *path, char *dest, size_t dlen); /** - * mutt_hcache_open - open the connection to the header cache. - * - * @param path Location of the header cache (often as specified by the user). - * @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. - * @return Pointer to a header_cache_t struct on success, NULL otherwise. + * mutt_hcache_open - open the connection to the header cache + * @param path Location of the header cache (often as specified by the user) + * @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. + * @return Pointer to a header_cache_t struct on success, NULL otherwise */ header_cache_t *mutt_hcache_open(const char *path, const char *folder, hcache_namer_t namer); /** - * mutt_hcache_close - close the connection to the header cache. - * - * @param h Pointer to the header_cache_t structure got by mutt_hcache_open. + * mutt_hcache_close - close the connection to the header cache + * @param h Pointer to the header_cache_t structure got by mutt_hcache_open */ void mutt_hcache_close(header_cache_t *h); /** - * mutt_hcache_fetch - fetch and validate a message's header from the cache. - * - * @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. - * @return Pointer to the data if found and valid, NULL otherwise. + * mutt_hcache_fetch - fetch and validate a message's header from the cache + * @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 + * @return Pointer to the data if found and valid, 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. + * 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. + * must be done before closing the header cache with mutt_hcache_close. */ void *mutt_hcache_fetch(header_cache_t *h, const char *key, size_t keylen); /** - * mutt_hcache_fetch_raw - fetch a message's header from the cache. - * - * @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. - * @return Pointer to the data if found, NULL otherwise. + * mutt_hcache_fetch_raw - fetch a message's header from the cache + * @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 + * @return Pointer to the data if found, NULL otherwise * @note This function does not perform any check on the validity of the data - * found. + * found. * @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. + * must be done before closing the header cache with mutt_hcache_close. */ void *mutt_hcache_fetch_raw(header_cache_t *h, const char *key, size_t keylen); /** - * mutt_hcache_free - free previously fetched data. - * - * @param h Pointer to the header_cache_t structure got by mutt_hcache_open. - * @param data Pointer to the data got using hcache_fetch or hcache_fetch_raw. + * mutt_hcache_free - free previously fetched data + * @param h Pointer to the header_cache_t structure got by mutt_hcache_open + * @param data Pointer to the data got using hcache_fetch or hcache_fetch_raw */ void mutt_hcache_free(header_cache_t *h, void **data); /** - * mutt_hcache_restore - restore a Header from data retrieved from the cache. - * - * @param d Data retrieved using mutt_hcache_fetch or mutt_hcache_fetch_raw. - * @return Pointer to the restored header (cannot be NULL). + * 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 + * @return Pointer to the restored header (cannot be NULL) * @note The returned Header must be free'd by caller code with - * mutt_free_header. + * mutt_free_header. */ struct Header *mutt_hcache_restore(const unsigned char *d); /** - * mutt_hcache_store - store a Header along with a validity datum. + * mutt_hcache_store - store a Header along with a validity datum * - * @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. - * @param header Message header to store. - * @param uidvalidity IMAP-specific UIDVALIDITY value, or 0 to use the current - * time. - * @return 0 on success, -1 otherwise. + * @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 + * @param header Message header to store + * @param uidvalidity IMAP-specific UIDVALIDITY value, or 0 to use the current time. + * @return 0 on success, -1 otherwise */ int mutt_hcache_store(header_cache_t *h, const char *key, size_t keylen, struct Header *header, unsigned int uidvalidity); /** - * mutt_hcache_store_raw - store a key / data pair. - * - * @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. - * @param data Payload to associate with key. - * @param dlen Length of the buffer pointed to by the @data parameter. - * @return 0 on success, -1 otherwise. + * mutt_hcache_store_raw - store a key / data pair + * @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 + * @param data Payload to associate with key + * @param dlen Length of the buffer pointed to by the @a data parameter + * @return 0 on success, -1 otherwise */ int mutt_hcache_store_raw(header_cache_t *h, const char *key, size_t keylen, void *data, size_t dlen); /** - * mutt_hcache_delete - delete a key / data pair. - * - * @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. - * @return 0 on success, -1 otherwise. + * mutt_hcache_delete - delete a key / data pair + * @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 + * @return 0 on success, -1 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. + * mutt_hcache_backend_list - get a list of backend identification strings * - * @return Comma separated string describing the compiled-in backends. - * @note The returned string must be free'd by the caller. + * @return 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); /** * mutt_hcache_is_valid_backend * - * @param s String identifying a backend. - * @return 1 if s is recognized as a valid backend, 0 otherwise. + * @param s String identifying a backend + * @return 1 if s is recognized as a valid backend, 0 otherwise */ int mutt_hcache_is_valid_backend(const char *s); diff --git a/hdrline.c b/hdrline.c index fd87c65f2..7db047e97 100644 --- a/hdrline.c +++ b/hdrline.c @@ -175,9 +175,9 @@ enum FieldType /** * get_nth_wchar - Extract one char from a multi-byte table - * @table: Multi-byte table - * @index: Select this character - * @return: String pointer to the character + * @param table Multi-byte table + * @param index Select this character + * @return String pointer to the character * * Extract one multi-byte character from a string table. * If the index is invalid, then a space character will be returned. @@ -196,8 +196,8 @@ static char *get_nth_wchar(struct MbCharTable *table, int index) /** * make_from_prefix - Create a prefix for an author field - * @disp: Type of field - * @return: Prefix string (do not free it) + * @param disp Type of field + * @return 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 @@ -223,10 +223,10 @@ static const char *make_from_prefix(enum FieldType disp) /** * make_from - Generate a From: field (with optional prefix) - * @env: Envelope of the email - * @buf: Buffer to store the result - * @len: Size of the buffer - * @do_lists: Should we check for mailing lists? + * @param env Envelope of the email + * @param buf Buffer to store the result + * @param len Size of the buffer + * @param do_lists Should we check for mailing lists? * * Generate the %F or %L field in $index_format. * This is the author, or recipient of the email. @@ -358,10 +358,10 @@ static int user_is_recipient(struct Header *h) /** * get_initials - Turn a name into initials - * @name: String to be converted - * @buf: Buffer for the result - * @buflen: Size of the buffer - * @return: 1 on Success, 0 on Failure + * @param name String to be converted + * @param buf Buffer for the result + * @param buflen Size of the buffer + * @return 1 on Success, 0 on 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 diff --git a/header.h b/header.h index f2804c565..8ec185959 100644 --- a/header.h +++ b/header.h @@ -25,32 +25,32 @@ struct Header { - unsigned int security : 12; /* bit 0-8: flags, bit 9,10: application. + unsigned int security : 12; /**< bit 0-8: flags, bit 9,10: application. see: mutt_crypt.h pgplib.h, smime.h */ - bool mime : 1; /* has a MIME-Version header? */ - bool flagged : 1; /* marked important? */ + bool mime : 1; /**< has a MIME-Version header? */ + bool flagged : 1; /**< marked important? */ bool tagged : 1; bool deleted : 1; - bool purge : 1; /* skip trash folder when deleting */ - bool quasi_deleted : 1; /* deleted from mutt, but not modified on disk */ + bool purge : 1; /**< skip trash folder when deleting */ + bool quasi_deleted : 1; /**< deleted from mutt, but not modified on disk */ bool changed : 1; - bool attach_del : 1; /* has an attachment marked for deletion */ + bool attach_del : 1; /**< has an attachment marked for deletion */ bool old : 1; bool read : 1; - bool expired : 1; /* already expired? */ - bool superseded : 1; /* got superseded? */ + bool expired : 1; /**< already expired? */ + bool superseded : 1; /**< got superseded? */ bool replied : 1; - bool subject_changed : 1; /* used for threading */ - bool threaded : 1; /* used for threading */ - bool display_subject : 1; /* used for threading */ - bool recip_valid : 1; /* is_recipient is valid */ - bool active : 1; /* message is not to be removed */ - bool trash : 1; /* message is marked as trashed on disk. + bool subject_changed : 1; /**< used for threading */ + bool threaded : 1; /**< used for threading */ + bool display_subject : 1; /**< used for threading */ + bool recip_valid : 1; /**< is_recipient is valid */ + bool active : 1; /**< message is not to be removed */ + bool trash : 1; /**< message is marked as trashed on disk. * This flag is used by the maildir_trash * option. */ - bool xlabel_changed : 1; /* editable - used for syncing */ + bool xlabel_changed : 1; /**< editable - used for syncing */ /* timezone of the sender of this message */ unsigned int zhours : 5; @@ -65,27 +65,27 @@ struct Header bool attach_valid : 1; /* the following are used to support collapsing threads */ - bool collapsed : 1; /* is this message part of a collapsed thread? */ - bool limited : 1; /* is this message in a limited view? */ - size_t num_hidden; /* number of hidden messages in this view */ + bool collapsed : 1; /**< is this message part of a collapsed thread? */ + bool limited : 1; /**< is this message in a limited view? */ + size_t num_hidden; /**< number of hidden messages in this view */ - short recipient; /* user_is_recipient()'s return value, cached */ + short recipient; /**< user_is_recipient()'s return value, cached */ - int pair; /* color-pair to use when displaying in the index */ + int pair; /**< color-pair to use when displaying in the index */ - time_t date_sent; /* time when the message was sent (UTC) */ - time_t received; /* time when the message was placed in the mailbox */ - LOFF_T offset; /* where in the stream does this message begin? */ - int lines; /* how many lines in the body of this message? */ - int index; /* the absolute (unsorted) message number */ - int msgno; /* number displayed to the user */ - int virtual; /* virtual message number */ + time_t date_sent; /**< time when the message was sent (UTC) */ + time_t received; /**< time when the message was placed in the mailbox */ + LOFF_T offset; /**< where in the stream does this message begin? */ + int lines; /**< how many lines in the body of this message? */ + int index; /**< the absolute (unsorted) message number */ + int msgno; /**< number displayed to the user */ + int virtual; /**< virtual message number */ int score; - struct Envelope *env; /* envelope information */ - struct Body *content; /* list of MIME parts */ + struct Envelope *env; /**< envelope information */ + struct Body *content; /**< list of MIME parts */ char *path; - char *tree; /* character string to print thread tree */ + char *tree; /**< character string to print thread tree */ struct MuttThread *thread; /* Number of qualifying attachments in message, if attach_valid */ @@ -96,15 +96,15 @@ struct Header #endif #ifdef USE_POP - int refno; /* message number on server */ + int refno; /**< message number on server */ #endif #if defined(USE_POP) || defined(USE_IMAP) || defined(USE_NNTP) || defined(USE_NOTMUCH) - void *data; /* driver-specific data */ - void (*free_cb)(struct Header *); /* driver-specific data free function */ + void *data; /**< driver-specific data */ + void (*free_cb)(struct Header *); /**< driver-specific data free function */ #endif - char *maildir_flags; /* unknown maildir flags */ + char *maildir_flags; /**< unknown maildir flags */ }; static inline struct Header *mutt_new_header(void) diff --git a/hook.c b/hook.c index 529780af6..a8f205e9a 100644 --- a/hook.c +++ b/hook.c @@ -44,10 +44,10 @@ struct Hook { - int type; /* hook type */ - struct Regex rx; /* regular expression */ - char *command; /* filename, command or pattern to execute */ - struct Pattern *pattern; /* used for fcc,save,send-hook */ + int type; /**< hook type */ + struct Regex rx; /**< regular expression */ + char *command; /**< filename, command or pattern to execute */ + struct Pattern *pattern; /**< used for fcc,save,send-hook */ struct Hook *next; }; @@ -625,7 +625,7 @@ void mutt_timeout_hook(void) /** * mutt_startup_shutdown_hook - Execute any startup/shutdown hooks - * @type: Hook type: MUTT_STARTUPHOOK or MUTT_SHUTDOWNHOOK + * @param type Hook type: MUTT_STARTUPHOOK or MUTT_SHUTDOWNHOOK * * The user can configure hooks to be run on startup/shutdown. * This function finds all the matching hooks and executes them. diff --git a/imap/imap_private.h b/imap/imap_private.h index b40b2f45d..71d439343 100644 --- a/imap/imap_private.h +++ b/imap/imap_private.h @@ -153,9 +153,7 @@ struct ImapStatus struct ImapList { char *name; - char delim; - /* if we end up storing a lot of these we could turn this into a bitfield */ bool noselect; bool noinferiors; }; @@ -192,7 +190,7 @@ struct ImapData char *capstr; unsigned char capabilities[(CAPMAX + 7) / 8]; unsigned int seqno; - time_t lastread; /* last time we read a command for the server */ + time_t lastread; /**< last time we read a command for the server */ char *buf; unsigned int blen; @@ -221,14 +219,14 @@ struct ImapData char *mailbox; unsigned short check_status; unsigned char reopen; - unsigned int new_mail_count; /* Set when EXISTS notifies of new mail */ + unsigned int new_mail_count; /**< Set when EXISTS notifies of new mail */ struct ImapCache cache[IMAP_CACHE_LEN]; struct Hash *uid_hash; unsigned int uid_validity; unsigned int uidnext; - struct Header **msn_index; /* look up headers by (MSN-1) */ - unsigned int msn_index_size; /* allocation size */ - unsigned int max_msn; /* the largest MSN fetched so far */ + struct Header **msn_index; /**< look up headers by (MSN-1) */ + unsigned int msn_index_size; /**< allocation size */ + unsigned int max_msn; /**< the largest MSN fetched so far */ struct BodyCache *bcache; /* all folder flags - system flags AND keywords */ diff --git a/imap/message.h b/imap/message.h index f96942297..8a83371c9 100644 --- a/imap/message.h +++ b/imap/message.h @@ -38,8 +38,8 @@ struct ImapHeaderData bool parsed : 1; - unsigned int uid; /* 32-bit Message UID */ - unsigned int msn; /* Message Sequence Number */ + unsigned int uid; /**< 32-bit Message UID */ + unsigned int msn; /**< Message Sequence Number */ struct List *keywords; }; diff --git a/imap/util.c b/imap/util.c index 01347a5b8..5922d168e 100644 --- a/imap/util.c +++ b/imap/util.c @@ -840,7 +840,6 @@ int imap_wordcasecmp(const char *a, const char *b) /* * Imap keepalive: poll the current folder to keep the * connection alive. - * */ static void alrm_handler(int sig) diff --git a/init.c b/init.c index 837623d88..cc8a05585 100644 --- a/init.c +++ b/init.c @@ -785,16 +785,15 @@ static void remove_from_list(struct List **l, const char *str) /** * finish_source - 'finish' command: stop processing current config file - * @tmp: Temporary space shared by all command handlers - * @s: Current line of the config file - * @data: data field from init.h:struct Command - * @err: Buffer for any error message + * @param tmp Temporary space shared by all command handlers + * @param s Current line of the config file + * @param data data field from init.h:struct Command + * @param err Buffer for any error message + * @return + * * 1 Stop processing the current file + * * -1 Failed * * If the 'finish' command is found, we should stop reading the current file. - * - * Returns: - * 1 Stop processing the current file - * -1 Failed */ static int finish_source(struct Buffer *tmp, struct Buffer *s, unsigned long data, struct Buffer *err) @@ -810,10 +809,13 @@ static int finish_source(struct Buffer *tmp, struct Buffer *s, /** * parse_ifdef - 'ifdef' command: conditional config - * @tmp: Temporary space shared by all command handlers - * @s: Current line of the config file - * @data: data field from init.h:struct Command - * @err: Buffer for any error message + * @param tmp Temporary space shared by all command handlers + * @param s Current line of the config file + * @param data data field from init.h:struct Command + * @param err Buffer for any error message + * @return + * * 0 Success + * * -1 Failed * * The 'ifdef' command allows conditional elements in the config file. * If a given variable, function, command or compile-time symbol exists, then @@ -824,10 +826,6 @@ static int finish_source(struct Buffer *tmp, struct Buffer *s, * If (data == 1) then it means use the 'ifndef' (if-not-defined) command. * e.g. * ifndef imap finish - * - * Returns: - * 0 Success - * -1 Failed */ static int parse_ifdef(struct Buffer *tmp, struct Buffer *s, unsigned long data, struct Buffer *err) @@ -2240,13 +2238,13 @@ static void restart_debug(void) } #endif -/* Helper function for parse_setenv(). +/* mutt_envlist_set - Helper function for parse_setenv() + * @param name Name of the environment variable + * @param value Value the envionment variable should have + * @param overwrite Whether the environment variable should be overwritten + * * It's broken out because some other parts of mutt (filter.c) need * to set/overwrite environment variables in envlist before execing. - * - * @param name pointer to the name of the environment variable - * @param value pointer to the value the envionment variable should have - * @param overwrite whether the environment variable should be overwritten */ void mutt_envlist_set(const char *name, const char *value, bool overwrite) { diff --git a/keymap.h b/keymap.h index abefd6d91..02e598383 100644 --- a/keymap.h +++ b/keymap.h @@ -35,13 +35,13 @@ void init_extended_keys(void); /* entry in the keymap tree */ struct Keymap { - char *macro; /* macro expansion (op == OP_MACRO) */ - char *descr; /* description of a macro for the help menu */ - struct Keymap *next; /* next key in map */ - short op; /* operation to perform */ - short eq; /* number of leading keys equal to next entry */ - short len; /* length of key sequence (unit: sizeof (keycode_t)) */ - keycode_t *keys; /* key sequence */ + char *macro; /**< macro expansion (op == OP_MACRO) */ + char *descr; /**< description of a macro for the help menu */ + struct Keymap *next; /**< next key in map */ + short op; /**< operation to perform */ + short eq; /**< number of leading keys equal to next entry */ + short len; /**< length of key sequence (unit: sizeof (keycode_t)) */ + keycode_t *keys; /**< key sequence */ }; int km_expand_key(char *s, size_t len, struct Keymap *map); @@ -89,9 +89,9 @@ extern const struct Mapping Menus[]; struct Binding { - char *name; /* name of the function */ - int op; /* function id number */ - char *seq; /* default key binding */ + char *name; /**< name of the function */ + int op; /**< function id number */ + char *seq; /**< default key binding */ }; const struct Binding *km_get_table(int menu); diff --git a/lib.c b/lib.c index 7b85b2054..a90279df8 100644 --- a/lib.c +++ b/lib.c @@ -296,9 +296,9 @@ char *mutt_strlower(char *s) /** * mutt_strchrnul - find first occurrence of character in string - * @param s Haystack. - * @param c Needle. - * @return Pointer to the first occurrence if found or to the NULL character. + * @param s Haystack + * @param c Needle + * @return Pointer to the first occurrence if found or to the NULL character * * This function is like GNU's strchrnul, which is similar to the standard * strchr function: it looks for the c character in the NULL-terminated string @@ -1094,12 +1094,9 @@ int mutt_atoi(const char *str, int *dst) } /** - * mutt_inbox_cmp - check whether two folders share the same path and one is - * an inbox. - * - * @param a First path. - * @param b Second path. - * + * mutt_inbox_cmp - do two folders share the same path and one is an inbox + * @param a First path + * @param b Second path * @return -1 if a is INBOX of b, 0 if none is INBOX, 1 if b is INBOX for a * * This function compares two folder paths. It first looks for the position of @@ -1111,10 +1108,10 @@ int mutt_atoi(const char *str, int *dst) * paths are considered equivalent and this function returns 0. * * Examples: - * mutt_inbox_cmp("/foo/bar", "/foo/baz") --> 0 - * mutt_inbox_cmp("/foo/bar/", "/foo/bar/inbox") --> 0 - * mutt_inbox_cmp("/foo/bar/sent", "/foo/bar/inbox") --> 1 - * mutt_inbox_cmp("=INBOX", "=Drafts") --> -1 + * * mutt_inbox_cmp("/foo/bar", "/foo/baz") --> 0 + * * mutt_inbox_cmp("/foo/bar/", "/foo/bar/inbox") --> 0 + * * mutt_inbox_cmp("/foo/bar/sent", "/foo/bar/inbox") --> 1 + * * mutt_inbox_cmp("=INBOX", "=Drafts") --> -1 */ int mutt_inbox_cmp(const char *a, const char *b) { @@ -1166,15 +1163,15 @@ char *strfcpy(char *dest, const char *src, size_t dlen) /** * mutt_mkdir - Recursively create directories - * @path: Directories to create - * @mode: Permissions for final directory - * @return: + * @param path Directories to create + * @param mode Permissions for final directory + * @return * * 0 Success * * -1 Error (errno set) * * Create a directory, creating the parents if necessary. (like mkdir -p) * - * Note: The permissions are only set on the final directory. + * @note The permissions are only set on the final directory. * The permissions of any parent directories are determined by the umask. * (This is how "mkdir -p" behaves) */ diff --git a/mailbox.h b/mailbox.h index f8810c620..dab8d4539 100644 --- a/mailbox.h +++ b/mailbox.h @@ -52,10 +52,10 @@ enum MxCheckReturns struct Message { - FILE *fp; /* pointer to the message data */ - char *path; /* path to temp file */ - char *commited_path; /* the final path generated by mx_commit_message() */ - bool write; /* nonzero if message is open for writing */ + FILE *fp; /**< pointer to the message data */ + char *path; /**< path to temp file */ + char *commited_path; /**< the final path generated by mx_commit_message() */ + bool write; /**< nonzero if message is open for writing */ struct { bool read : 1; @@ -63,7 +63,7 @@ struct Message bool replied : 1; bool draft : 1; } flags; - time_t received; /* the time at which this message was received */ + time_t received; /**< the time at which this message was received */ }; struct Context *mx_open_mailbox(const char *path, int flags, struct Context *pctx); diff --git a/mbyte_table.h b/mbyte_table.h index b7f8d6192..5de5d343a 100644 --- a/mbyte_table.h +++ b/mbyte_table.h @@ -24,9 +24,9 @@ * option types. */ struct MbCharTable { - int len; /* number of characters */ - char **chars; /* the array of multibyte character strings */ - char *segmented_str; /* each chars entry points inside this string */ + int len; /**< number of characters */ + char **chars; /**< the array of multibyte character strings */ + char *segmented_str; /**< each chars entry points inside this string */ char *orig_str; }; diff --git a/mh.c b/mh.c index b04842e22..f7d4435e4 100644 --- a/mh.c +++ b/mh.c @@ -1445,7 +1445,6 @@ static int mh_close_message(struct Context *ctx, struct Message *msg) * * Note that this uses _almost_ the maildir file name format, but * with a {cur,new} prefix. - * */ static int maildir_open_new_message(struct Message *msg, struct Context *dest, struct Header *hdr) @@ -1529,7 +1528,6 @@ static int maildir_open_new_message(struct Message *msg, struct Context *dest, * tmp/{cur,new}.mutt-HOSTNAME-PID-COUNTER:flags * * See also maildir_open_new_message(). - * */ static int _maildir_commit_message(struct Context *ctx, struct Message *msg, struct Header *hdr) { @@ -1615,7 +1613,6 @@ static int maildir_commit_message(struct Context *ctx, struct Message *msg) /* * commit a message to an MH folder. - * */ @@ -2137,7 +2134,6 @@ static int maildir_check_mailbox(struct Context *ctx, int *index_hint) * * Don't change this code unless you _really_ understand what * happens. - * */ static int mh_check_mailbox(struct Context *ctx, int *index_hint) { diff --git a/mutt_curses.h b/mutt_curses.h index cf35b1bfd..7d0bcda48 100644 --- a/mutt_curses.h +++ b/mutt_curses.h @@ -99,8 +99,8 @@ void mutt_curs_set(int cursor); struct Event { - int ch; /* raw key pressed */ - int op; /* function op */ + int ch; /**< raw key pressed */ + int op; /**< function op */ }; struct Event mutt_getch(void); @@ -180,9 +180,9 @@ enum ColorId struct ColorLine { regex_t rx; - int match; /* which substringmap 0 for old behaviour */ + int match; /**< which substringmap 0 for old behaviour */ char *pattern; - struct Pattern *color_pattern; /* compiled pattern to speed up index color + struct Pattern *color_pattern; /**< compiled pattern to speed up index color calculation */ short fg; short bg; diff --git a/mutt_menu.h b/mutt_menu.h index 263da3d46..0082af35d 100644 --- a/mutt_menu.h +++ b/mutt_menu.h @@ -42,15 +42,15 @@ struct Menu { - char *title; /* the title of this menu */ - char *help; /* quickref for the current menu */ - void *data; /* extra data for the current menu */ - int current; /* current entry */ - int max; /* the number of entries in the menu */ - int redraw; /* when to redraw the screen */ - int menu; /* menu definition for keymap entries. */ - int offset; /* row offset within the window to start the index */ - int pagelen; /* number of entries per screen */ + char *title; /**< the title of this menu */ + char *help; /**< quickref for the current menu */ + void *data; /**< extra data for the current menu */ + int current; /**< current entry */ + int max; /**< the number of entries in the menu */ + int redraw; /**< when to redraw the screen */ + int menu; /**< menu definition for keymap entries. */ + int offset; /**< row offset within the window to start the index */ + int pagelen; /**< number of entries per screen */ int tagprefix; int is_mailbox_list; struct MuttWindow *indexwin; @@ -63,9 +63,9 @@ struct Menu * normal menu movement keys. This can cause problems with scrolling, if * prompt keys override movement keys. */ - char **dialog; /* dialog lines themselves */ - char *prompt; /* prompt for user, similar to mutt_multi_choice */ - char *keys; /* keys used in the prompt */ + char **dialog; /**< dialog lines themselves */ + char *prompt; /**< prompt for user, similar to mutt_multi_choice */ + char *keys; /**< keys used in the prompt */ /* callback to generate an index line for the requested element */ void (*make_entry)(char *, size_t, struct Menu *, int); @@ -85,10 +85,10 @@ struct Menu int (*color)(int i); /* the following are used only by mutt_menu_loop() */ - int top; /* entry that is the top of the current page */ - int oldcurrent; /* for driver use only. */ - int search_dir; /* direction of search */ - int tagged; /* number of tagged entries */ + int top; /**< entry that is the top of the current page */ + int oldcurrent; /**< for driver use only. */ + int search_dir; /**< direction of search */ + int tagged; /**< number of tagged entries */ }; void mutt_menu_init(void); diff --git a/mutt_notmuch.c b/mutt_notmuch.c index 60dba5d60..a987265bf 100644 --- a/mutt_notmuch.c +++ b/mutt_notmuch.c @@ -222,16 +222,16 @@ static void url_free_tags(struct UriTag *tags) * @param[in] url URI to parse * @param[out] filename Save the filename * @param[out] tags Save the list of tags - * - * @retval true Success - * @retval false Error: Bad format + * @return + * * true Success + * * false Error: Bad format * * Parse a NotMuch URI, such as: * * notmuch:///path/to/db?query=tag:lkml&limit=1000 * * notmuch://?query=neomutt * * Extract the database filename (optional) and any search parameters (tags). - * The tags will be saved in a linked list (#uri_tag). + * The tags will be saved in a linked list (#UriTag). */ static bool url_parse_query(const char *url, char **filename, struct UriTag **tags) { @@ -428,14 +428,12 @@ static int string_to_query_type(const char *str) /** * query_window_check_timebase - Checks if a given timebase string is valid * @param[in] timebase: string containing a time base - * * @return true if the given time base is valid * - * this function returns whether a given timebase string is valid or not, + * This function returns whether a given timebase string is valid or not, * which is used to validate the user settable configuration setting: * * nm_query_window_timebase - * */ static bool query_window_check_timebase(const char *timebase) { @@ -466,9 +464,8 @@ static void query_window_reset(void) * @param[in] query vfolder search string * @param[out] buf allocated string buffer to receive the modified search query * @param[in] bufsz allocated maximum size of the buf string buffer - * * @return boolean value set to true if a transformed search query is available as - * a string in buf, otherwise if the search query shall not be transformed. + * a string in buf, otherwise if the search query shall not be transformed. * * This is where the magic of windowed queries happens. Taking a vfolder search * query string as parameter, it will use the following two user settings: @@ -543,9 +540,8 @@ static bool windowed_query_from_query(const char *query, char *buf, size_t bufsz * 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 - * * @return string containing a notmuch search query, or a NULL pointer - * if none can be generated. + * 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 @@ -1780,9 +1776,9 @@ char *nm_uri_from_query(struct Context *ctx, char *buf, size_t bufsz) * @param new_uri allocated string receiving the reformatted URI * @param orig_uri original URI to be parsed * @param new_uri_sz size of the allocated new_uri string - * - * @return false if orig_uri contains an invalid query, true if new_uri contains a - * normalized version of the query. + * @return + * * true if new_uri contains a normalized version of the query + * * false if orig_uri contains an invalid query * * This function aims at making notmuch searches URI representations deterministic, * so that when comparing two equivalent searches they will be the same. It works diff --git a/mutt_options.h b/mutt_options.h index e9ca4ba09..e56ba0f89 100644 --- a/mutt_options.h +++ b/mutt_options.h @@ -52,7 +52,7 @@ struct Option short type; short flags; unsigned long data; - unsigned long init; /* initial value */ + unsigned long init; /**< initial value */ }; int mutt_option_to_string(const struct Option *opt, char *val, size_t len); diff --git a/mutt_regex.h b/mutt_regex.h index 1ffb4e994..d20599264 100644 --- a/mutt_regex.h +++ b/mutt_regex.h @@ -37,9 +37,9 @@ struct Regex { - char *pattern; /* printable version */ - regex_t *rx; /* compiled expression */ - int not; /* do not match */ + char *pattern; /**< printable version */ + regex_t *rx; /**< compiled expression */ + int not; /**< do not match */ }; struct RxList diff --git a/mutt_sasl_plain.h b/mutt_sasl_plain.h index 5f2d48f05..93750633e 100644 --- a/mutt_sasl_plain.h +++ b/mutt_sasl_plain.h @@ -22,14 +22,13 @@ /** * mutt_sasl_plain_msg - construct a base64 encoded SASL PLAIN message - * @param buf Destination buffer. - * @param buflen Available space in the destination buffer. - * @param cmd Protocol-specific string the prepend to the PLAIN message. - * @param authz Authorization identity. - * @param user Authentication identity (username). - * @param pass Password. - * - * @return The number of bytes written to buf. + * @param buf Destination buffer + * @param buflen Available space in the destination buffer + * @param cmd Protocol-specific string the prepend to the PLAIN message + * @param authz Authorization identity + * @param user Authentication identity (username) + * @param pass Password + * @return The number of 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 @@ -37,7 +36,6 @@ * authz\0user\0pass using base64 encoding, and stores the result in buf. * * Example usages for IMAP and SMTP, respectively: - * */ size_t mutt_sasl_plain_msg(char *buf, size_t buflen, const char *cmd, const char *authz, const char *user, const char *pass); diff --git a/ncrypt/crypt_gpgme.c b/ncrypt/crypt_gpgme.c index c73bac045..22eb01e1a 100644 --- a/ncrypt/crypt_gpgme.c +++ b/ncrypt/crypt_gpgme.c @@ -98,10 +98,10 @@ struct CryptKeyInfo { struct CryptKeyInfo *next; gpgme_key_t kobj; - int idx; /* and the user ID at this index */ - const char *uid; /* and for convenience point to this user ID */ - unsigned int flags; /* global and per uid flags (for convenience) */ - gpgme_validity_t validity; /* uid validity (cached for convenience) */ + int idx; /**< and the user ID at this index */ + const char *uid; /**< and for convenience point to this user ID */ + unsigned int flags; /**< global and per uid flags (for convenience) */ + gpgme_validity_t validity; /**< uid validity (cached for convenience) */ }; struct CryptEntry diff --git a/ncrypt/crypt_mod.h b/ncrypt/crypt_mod.h index 85ec55a60..46e55f75f 100644 --- a/ncrypt/crypt_mod.h +++ b/ncrypt/crypt_mod.h @@ -103,7 +103,7 @@ typedef struct CryptModuleFunctions */ typedef struct CryptModuleSpecs { - int identifier; /* Identifying bit. */ + int identifier; /**< Identifying bit */ crypt_module_functions_t functions; } * crypt_module_specs_t; diff --git a/ncrypt/gnupgparse.c b/ncrypt/gnupgparse.c index e9fee7ccb..b830075ea 100644 --- a/ncrypt/gnupgparse.c +++ b/ncrypt/gnupgparse.c @@ -23,7 +23,6 @@ * * Nowadays, we are using an external pubring lister with PGP which mimics * gpg's output format. - * */ #include "config.h" diff --git a/ncrypt/pgpinvoke.c b/ncrypt/pgpinvoke.c index 34b5af78d..fa86b9383 100644 --- a/ncrypt/pgpinvoke.c +++ b/ncrypt/pgpinvoke.c @@ -45,11 +45,11 @@ struct PgpCommandContext { - short need_passphrase; /* %p */ - const char *fname; /* %f */ - const char *sig_fname; /* %s */ - const char *signas; /* %a */ - const char *ids; /* %r */ + short need_passphrase; /**< %p */ + const char *fname; /**< %f */ + const char *sig_fname; /**< %s */ + const char *signas; /**< %a */ + const char *ids; /**< %r */ }; static const char *_mutt_fmt_pgp_command(char *dest, size_t destlen, size_t col, @@ -178,7 +178,6 @@ static pid_t pgp_invoke(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd, * The exported interface. * * This is historic and may be removed at some point. - * */ pid_t pgp_invoke_decode(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd, diff --git a/ncrypt/pgppacket.h b/ncrypt/pgppacket.h index 4faf5c621..557e7c1e3 100644 --- a/ncrypt/pgppacket.h +++ b/ncrypt/pgppacket.h @@ -27,23 +27,23 @@ enum PacketTags { - PT_RES0 = 0, /* reserved */ - PT_ESK, /* Encrypted Session Key */ - PT_SIG, /* Signature Packet */ - PT_CESK, /* Conventionally Encrypted Session Key Packet */ - PT_OPS, /* One-Pass Signature Packet */ - PT_SECKEY, /* Secret Key Packet */ - PT_PUBKEY, /* Public Key Packet */ - PT_SUBSECKEY, /* Secret Subkey Packet */ - PT_COMPRESSED, /* Compressed Data Packet */ - PT_SKE, /* Symmetrically Encrypted Data Packet */ - PT_MARKER, /* Marker Packet */ - PT_LITERAL, /* Literal Data Packet */ - PT_TRUST, /* Trust Packet */ - PT_NAME, /* Name Packet */ - PT_SUBKEY, /* Subkey Packet */ - PT_RES15, /* Reserved */ - PT_COMMENT /* Comment Packet */ + PT_RES0 = 0, /**< reserved */ + PT_ESK, /**< Encrypted Session Key */ + PT_SIG, /**< Signature Packet */ + PT_CESK, /**< Conventionally Encrypted Session Key Packet */ + PT_OPS, /**< One-Pass Signature Packet */ + PT_SECKEY, /**< Secret Key Packet */ + PT_PUBKEY, /**< Public Key Packet */ + PT_SUBSECKEY, /**< Secret Subkey Packet */ + PT_COMPRESSED, /**< Compressed Data Packet */ + PT_SKE, /**< Symmetrically Encrypted Data Packet */ + PT_MARKER, /**< Marker Packet */ + PT_LITERAL, /**< Literal Data Packet */ + PT_TRUST, /**< Trust Packet */ + PT_NAME, /**< Name Packet */ + PT_SUBKEY, /**< Subkey Packet */ + PT_RES15, /**< Reserved */ + PT_COMMENT /**< Comment Packet */ }; unsigned char *pgp_read_packet(FILE *fp, size_t *len); diff --git a/ncrypt/smime.c b/ncrypt/smime.c index 24f7f4ca0..cfb22c35c 100644 --- a/ncrypt/smime.c +++ b/ncrypt/smime.c @@ -53,13 +53,13 @@ struct SmimeCommandContext { - const char *key; /* %k */ - const char *cryptalg; /* %a */ - const char *digestalg; /* %d */ - const char *fname; /* %f */ - const char *sig_fname; /* %s */ - const char *certificates; /* %c */ - const char *intermediates; /* %i */ + const char *key; /**< %k */ + const char *cryptalg; /**< %a */ + const char *digestalg; /**< %d */ + const char *fname; /**< %f */ + const char *sig_fname; /**< %s */ + const char *certificates; /**< %c */ + const char *intermediates; /**< %i */ }; char SmimePass[STRING]; diff --git a/ncrypt/smime.h b/ncrypt/smime.h index 58de45ee7..50986f93d 100644 --- a/ncrypt/smime.h +++ b/ncrypt/smime.h @@ -35,7 +35,7 @@ struct SmimeKey char *hash; char *label; char *issuer; - char trust; /* i=Invalid r=revoked e=expired u=unverified v=verified t=trusted */ + char trust; /**< i=Invalid r=revoked e=expired u=unverified v=verified t=trusted */ int flags; struct SmimeKey *next; }; diff --git a/pager.c b/pager.c index 210ce62d7..d69ea55d8 100644 --- a/pager.c +++ b/pager.c @@ -136,7 +136,7 @@ struct Line struct Syntax *syntax; struct Syntax *search; struct QClass *quote; - unsigned int is_cont_hdr; /* this line is a continuation of the previous header line */ + unsigned int is_cont_hdr; /**< this line is a continuation of the previous header line */ }; #define ANSI_OFF (1 << 0) @@ -1659,7 +1659,7 @@ struct PagerRedrawData int flags; struct Pager *extra; int indexlen; - int indicator; /* the indicator line of the PI */ + int indicator; /**< the indicator line of the PI */ int oldtopline; int lines; int max_line; @@ -1677,7 +1677,7 @@ struct PagerRedrawData struct MuttWindow *index_window; struct MuttWindow *pager_status_window; struct MuttWindow *pager_window; - struct Menu *index; /* the Pager Index (PI) */ + struct Menu *index; /**< the Pager Index (PI) */ regex_t search_re; int search_compiled; int search_flag; diff --git a/pager.h b/pager.h index 81759c3ba..7e87e7ccb 100644 --- a/pager.h +++ b/pager.h @@ -43,11 +43,11 @@ struct Menu; struct Pager { - struct Context *ctx; /* current mailbox */ - struct Header *hdr; /* current message */ - struct Body *bdy; /* current attachment */ - FILE *fp; /* source stream */ - struct AttachPtr **idx; /* attachment information */ + struct Context *ctx; /**< current mailbox */ + struct Header *hdr; /**< current message */ + struct Body *bdy; /**< current attachment */ + FILE *fp; /**< source stream */ + struct AttachPtr **idx; /**< attachment information */ short idxlen; }; diff --git a/parse.c b/parse.c index e754940f9..522a04eeb 100644 --- a/parse.c +++ b/parse.c @@ -699,7 +699,7 @@ static const struct Tz char tzname[5]; unsigned char zhours; unsigned char zminutes; - bool zoccident; /* west of UTC? */ + bool zoccident; /**< west of UTC? */ } TimeZones[] = { { "aat", 1, 0, true }, /* Atlantic Africa Time */ { "adt", 4, 0, false }, /* Arabia DST */ diff --git a/pattern.c b/pattern.c index 3d4f0b405..3df3598cf 100644 --- a/pattern.c +++ b/pattern.c @@ -216,11 +216,11 @@ static const char *get_date(const char *s, struct tm *t, struct Buffer *err) struct RangeRegex { - const char *raw; /* regexp as string */ - int lgrp; /* paren group matching the left side */ - int rgrp; /* paren group matching the right side */ - int ready; /* compiled yet? */ - regex_t cooked; /* compiled form */ + const char *raw; /**< regexp as string */ + int lgrp; /**< paren group matching the left side */ + int rgrp; /**< paren group matching the right side */ + int ready; /**< compiled yet? */ + regex_t cooked; /**< compiled form */ }; enum @@ -801,8 +801,8 @@ static bool eat_message_range(struct Pattern *pat, struct Buffer *s, struct Buff static const struct PatternFlags { - int tag; /* character used to represent this op */ - int op; /* operation to perform */ + int tag; /**< character used to represent this op */ + int op; /**< operation to perform */ int class; bool (*eat_arg)(struct Pattern *, struct Buffer *, struct Buffer *); } Flags[] = { @@ -1778,11 +1778,10 @@ void mutt_check_simple(char *s, size_t len, const char *simple) /** * top_of_thread - Find the first email in the current thread - * @h: Header of current email - * - * Returns: - * MuttThread*: success, email found - * NULL: on error + * @param h Header of current email + * @return + * * MuttThread*: success, email found + * * NULL: on error */ static struct MuttThread *top_of_thread(struct Header *h) { @@ -1801,11 +1800,10 @@ static struct MuttThread *top_of_thread(struct Header *h) /** * mutt_limit_current_thread - Limit the email view to the current thread - * @h: Header of current email - * - * Returns: - * true: Success - * false: Failure + * @param h Header of current email + * @return + * * true: Success + * * false: Failure */ bool mutt_limit_current_thread(struct Header *h) { diff --git a/pattern.h b/pattern.h index a6213b1b1..a7c1461a8 100644 --- a/pattern.h +++ b/pattern.h @@ -35,12 +35,12 @@ struct Pattern bool alladdr : 1; bool stringmatch : 1; bool groupmatch : 1; - bool ign_case : 1; /* ignore case for local stringmatch searches */ + bool ign_case : 1; /**< ignore case for local stringmatch searches */ bool isalias : 1; int min; int max; struct Pattern *next; - struct Pattern *child; /* arguments to logical op */ + struct Pattern *child; /**< arguments to logical op */ union { regex_t *rx; struct Group *g; @@ -60,14 +60,14 @@ enum PatternExecFlag */ struct PatternCache { - int list_all; /* ^~l */ - int list_one; /* ~l */ - int sub_all; /* ^~u */ - int sub_one; /* ~u */ - int pers_recip_all; /* ^~p */ - int pers_recip_one; /* ~p */ - int pers_from_all; /* ^~P */ - int pers_from_one; /* ~P */ + int list_all; /**< ^~l */ + int list_one; /**< ~l */ + int sub_all; /**< ^~u */ + int sub_one; /**< ~u */ + int pers_recip_all; /**< ^~p */ + int pers_recip_one; /**< ~p */ + int pers_from_all; /**< ^~P */ + int pers_from_one; /**< ~P */ }; static inline struct Pattern *new_pattern(void) diff --git a/pgpewrap.c b/pgpewrap.c index 408b571fd..ec3e998de 100644 --- a/pgpewrap.c +++ b/pgpewrap.c @@ -2,7 +2,6 @@ * C version by Wessel Dankers * * This code is in the public domain. - * */ #include "config.h" diff --git a/pgppubring.c b/pgppubring.c index a5ec752d8..4a1c4cb96 100644 --- a/pgppubring.c +++ b/pgppubring.c @@ -27,7 +27,6 @@ * * You can actually use this to put together some fairly general * PGP key management applications. - * */ #include "config.h" diff --git a/pop.h b/pop.h index 3a4d50c39..a73cff6f5 100644 --- a/pop.h +++ b/pop.h @@ -64,20 +64,20 @@ struct PopData unsigned int status : 2; bool capabilities : 1; unsigned int use_stls : 2; - bool cmd_capa : 1; /* optional command CAPA */ - bool cmd_stls : 1; /* optional command STLS */ - unsigned int cmd_user : 2; /* optional command USER */ - unsigned int cmd_uidl : 2; /* optional command UIDL */ - unsigned int cmd_top : 2; /* optional command TOP */ - bool resp_codes : 1; /* server supports extended response codes */ - bool expire : 1; /* expire is greater than 0 */ + bool cmd_capa : 1; /**< optional command CAPA */ + bool cmd_stls : 1; /**< optional command STLS */ + unsigned int cmd_user : 2; /**< optional command USER */ + unsigned int cmd_uidl : 2; /**< optional command UIDL */ + unsigned int cmd_top : 2; /**< optional command TOP */ + bool resp_codes : 1; /**< server supports extended response codes */ + bool expire : 1; /**< expire is greater than 0 */ bool clear_cache : 1; size_t size; time_t check_time; - time_t login_delay; /* minimal login delay capability */ - char *auth_list; /* list of auth mechanisms */ + time_t login_delay; /**< minimal login delay capability */ + char *auth_list; /**< list of auth mechanisms */ char *timestamp; - struct BodyCache *bcache; /* body cache */ + struct BodyCache *bcache; /**< body cache */ char err_msg[POP_CMD_RESPONSE]; struct PopCache cache[POP_CACHE_LEN]; }; diff --git a/remailer.c b/remailer.c index 6d1c5944c..5fc8c6f06 100644 --- a/remailer.c +++ b/remailer.c @@ -346,7 +346,6 @@ static const char *mix_format_caps(struct Remailer *r) * %c capabilities * %s short name * %a address - * */ static const char *mix_entry_fmt(char *dest, size_t destlen, size_t col, int cols, char op, const char *src, const char *prefix, diff --git a/rfc1524.h b/rfc1524.h index 6d4f58639..41e80f6e5 100644 --- a/rfc1524.h +++ b/rfc1524.h @@ -33,8 +33,8 @@ struct Rfc1524MailcapEntry char *printcommand; char *nametemplate; char *convert; - bool needsterminal : 1; /* endwin() and system */ - bool copiousoutput : 1; /* needs pager, basically */ + bool needsterminal : 1; /**< endwin() and system */ + bool copiousoutput : 1; /**< needs pager, basically */ }; struct Rfc1524MailcapEntry *rfc1524_new_entry(void); diff --git a/rfc2231.c b/rfc2231.c index 4c61e5771..224dd1191 100644 --- a/rfc2231.c +++ b/rfc2231.c @@ -22,7 +22,6 @@ * * Additionally, continuations and encoding are mixed in an, errrm, * interesting manner. - * */ #include "config.h" diff --git a/score.c b/score.c index 9ef26f93c..e2b410739 100644 --- a/score.c +++ b/score.c @@ -36,7 +36,7 @@ struct Score char *str; struct Pattern *pat; int val; - int exact; /* if this rule matches, don't evaluate any more */ + int exact; /**< if this rule matches, don't evaluate any more */ struct Score *next; }; diff --git a/sendlib.c b/sendlib.c index 2a2d168ac..ab2bd1b2e 100644 --- a/sendlib.c +++ b/sendlib.c @@ -1950,7 +1950,6 @@ out: * privacy != 0 => will omit any headers which may identify the user. * Output generated is suitable for being sent through * anonymous remailer chains. - * */ diff --git a/sidebar.c b/sidebar.c index b7075d947..dd66fe2eb 100644 --- a/sidebar.c +++ b/sidebar.c @@ -49,7 +49,7 @@ static short PreviousSort = SORT_ORDER; /* sidebar_sort_method */ */ struct SbEntry { - char box[STRING]; /* formatted mailbox name */ + char box[STRING]; /**< formatted mailbox name */ struct Buffy *buffy; bool is_hidden; }; @@ -79,24 +79,24 @@ enum SidebarSrc /** * cb_format_str - Create the string to show in the sidebar - * @dest: Buffer in which to save string - * @destlen: Buffer length - * @col: Starting column, UNUSED - * @op: printf-like operator, e.g. 'B' - * @src: printf-like format string - * @prefix: Field formatting string, UNUSED - * @ifstring: If condition is met, display this string - * @elsestring: Otherwise, display this string - * @data: Pointer to our sidebar_entry - * @flags: Format flags, e.g. MUTT_FORMAT_OPTIONAL + * @param dest Buffer in which to save string + * @param destlen Buffer length + * @param col Starting column, UNUSED + * @param cols Maximum columns, UNUSED + * @param op printf-like operator, e.g. 'B' + * @param src printf-like format string + * @param prefix Field formatting string, UNUSED + * @param ifstring If condition is met, display this string + * @param elsestring Otherwise, display this string + * @param data Pointer to our sidebar_entry + * @param flags Format flags, e.g. MUTT_FORMAT_OPTIONAL + * @return src (unchanged) * * cb_format_str is a callback function for mutt_FormatString. It understands * six operators. '%B' : Mailbox name, '%F' : Number of flagged messages, * '%N' : Number of new messages, '%S' : Size (total number of messages), * '%!' : Icon denoting number of flagged messages. * '%n' : N if folder has new mail, blank otherwise. - * - * Returns: src (unchanged) */ static const char *cb_format_str(char *dest, size_t destlen, size_t col, int cols, char op, const char *src, const char *prefix, @@ -224,11 +224,11 @@ static const char *cb_format_str(char *dest, size_t destlen, size_t col, int col /** * make_sidebar_entry - Turn mailbox data into a sidebar string - * @buf: Buffer in which to save string - * @buflen: Buffer length - * @width: Desired width in screen cells - * @box: Mailbox name - * @sbe: Mailbox object + * @param buf Buffer in which to save string + * @param buflen Buffer length + * @param width Desired width in screen cells + * @param box Mailbox name + * @param sbe Mailbox object * * Take all the relevant mailbox data and the desired screen width and then get * mutt_FormatString to do the actual work. mutt_FormatString will callback to @@ -265,13 +265,12 @@ static void make_sidebar_entry(char *buf, unsigned int buflen, int width, /** * cb_qsort_sbe - qsort callback to sort SBENTRYs - * @a: First SbEntry to compare - * @b: Second SbEntry to compare - * - * Returns: - * -1: a precedes b - * 0: a and b are identical - * 1: b precedes a + * @param a First SbEntry to compare + * @param b Second SbEntry to compare + * @return + * * -1: a precedes b + * * 0: a and b are identical + * * 1: b precedes a */ static int cb_qsort_sbe(const void *a, const void *b) { @@ -399,7 +398,7 @@ static void unsort_entries(void) } /** - * sort_entries - Sort Entries array. + * sort_entries - Sort Entries array * * Sort the Entries array according to the current sort config * option "sidebar_sort_method". This calls qsort to do the work which calls our @@ -584,17 +583,16 @@ static int select_page_up(void) /** * prepare_sidebar - Prepare the list of SBENTRYs for the sidebar display - * @page_size: The number of lines on a page + * @param page_size The number of lines on a page + * @return + * * false: No, don't draw the sidebar + * * true: Yes, draw the sidebar * * Before painting the sidebar, we determine which are visible, sort * them and set up our page pointers. * * This is a lot of work to do each refresh, but there are many things that * can change outside of the sidebar that we don't hear about. - * - * Returns: - * false: No, don't draw the sidebar - * true: Yes, draw the sidebar */ static bool prepare_sidebar(int page_size) { @@ -669,8 +667,11 @@ static bool prepare_sidebar(int page_size) /** * draw_divider - Draw a line between the sidebar and the rest of mutt - * @num_rows: Height of the Sidebar - * @num_cols: Width of the Sidebar + * @param num_rows Height of the Sidebar + * @param num_cols Width of the Sidebar + * @return + * * 0: Empty string + * * n: 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. @@ -678,10 +679,6 @@ static bool prepare_sidebar(int page_size) * * If the user hasn't set $sidebar_divider_char we pick a character for them, * respecting the value of $ascii_chars. - * - * @return: - * * 0: Empty string - * * n: Character occupies n screen columns */ static int draw_divider(int num_rows, int num_cols) { @@ -761,10 +758,10 @@ static int draw_divider(int num_rows, int num_cols) /** * fill_empty_space - Wipe the remaining Sidebar space - * @first_row: Window line to start (0-based) - * @num_rows: Number of rows to fill - * @div_width: Width in screen characters taken by the divider - * @num_cols: Number of columns to fill + * @param first_row Window line to start (0-based) + * @param num_rows Number of rows to fill + * @param div_width Width in screen characters taken by the divider + * @param num_cols Number of columns to fill * * Write spaces over the area the sidebar isn't using. */ @@ -787,9 +784,9 @@ static void fill_empty_space(int first_row, int num_rows, int div_width, int num /** * draw_sidebar - Write out a list of mailboxes, on the left - * @num_rows: Height of the Sidebar - * @num_cols: Width of the Sidebar - * @div_width: Width in screen characters taken by the divider + * @param num_rows Height of the Sidebar + * @param num_cols Width of the Sidebar + * @param div_width Width in screen characters taken by the divider * * Display a list of mailboxes in a panel on the left. What's displayed will * depend on our index markers: TopBuffy, OpnBuffy, HilBuffy, BotBuffy. @@ -981,7 +978,7 @@ void mutt_sb_draw(void) /** * mutt_sb_change_mailbox - Change the selected mailbox - * @op: Operation code + * @param op Operation code * * Change the selected mailbox, e.g. "Next mailbox", "Previous Mailbox * with new mail". The operations are listed OPS.SIDEBAR which is built @@ -1036,7 +1033,7 @@ void mutt_sb_change_mailbox(int op) /** * mutt_sb_set_buffystats - Update the Buffy's message counts from the Context - * @ctx: A mailbox Context + * @param ctx A mailbox Context * * Given a mailbox Context, find a matching mailbox Buffy and copy the message * counts into it. diff --git a/version.c b/version.c index 45d207615..aa5831207 100644 --- a/version.c +++ b/version.c @@ -328,7 +328,7 @@ static void print_compile_options(void) /** * rstrip_in_place - Strip a trailing carriage return - * @s: String to be modified + * @param s String to be modified * * The string has its last carriage return set to NUL. * Returns: @@ -441,20 +441,19 @@ void print_copyright(void) /** * feature_enabled - Test if a compile-time feature is enabled - * @name: Compile-time symbol of the feature + * @param name Compile-time symbol of the feature + * @return + * * true: Feature enabled + * * false: Feature not enabled, or not compiled in * * Many of the larger features of mutt can be disabled at compile time. - * They define a symbol and use #ifdef's around their code. + * They define a symbol and use ifdef's around their code. * The symbols are mirrored in "CompileOptions comp_opts[]" in this * file. * * This function checks if one of these symbols is present in the code. * * These symbols are also seen in the output of "mutt -v". - * - * Returns: - * true: Feature enabled - * false: Feature not enabled, or not compiled in */ bool feature_enabled(const char *name) {