From dd58e7585a017f0266a0a738b89c46c17f6fc3df Mon Sep 17 00:00:00 2001 From: Richard Russon Date: Wed, 4 Aug 2021 00:13:03 +0100 Subject: [PATCH] doxy: document struct members --- alias/alias.h | 2 +- autocrypt/dlgautocrypt.c | 6 ++--- autocrypt/lib.h | 44 +++++++++++++++++----------------- bcache/bcache.c | 2 +- browser.h | 52 ++++++++++++++++++++-------------------- compose/attach_data.h | 4 ++-- conn/sasl.c | 6 ++--- context.h | 2 +- core/mailbox.c | 9 ++++--- core/mailbox.h | 2 +- core/mxapi.h | 12 +++++----- email/email.h | 4 ++-- email/envelope.h | 16 ++++++------- email/rfc2231.c | 10 ++++---- enriched.c | 4 ++-- enter_state.h | 12 +++++----- gui/color.c | 18 +++++++------- gui/color.h | 2 +- hcache/hcache.c | 11 +++++---- hcache/lib.h | 8 +++---- hdrline.c | 8 +++---- history/history.c | 6 ++--- imap/adata.h | 24 +++++++++---------- imap/edata.h | 10 ++++---- imap/mdata.h | 4 ++-- keymap.c | 4 ++-- maildir/mdata.h | 4 ++-- monitor.c | 2 +- mutt/file.h | 4 ++-- mutt/mapping.h | 4 ++-- mutt/notify.c | 4 ++-- mutt/slist.h | 6 ++--- mutt/string.c | 4 ++-- ncrypt/crypt_gpgme.h | 2 +- ncrypt/dlggpgme.c | 8 +++---- ncrypt/dlgpgp.c | 2 +- ncrypt/pgpkey.c | 2 +- ncrypt/pgplib.h | 4 ++-- nntp/adata.h | 20 ++++++++-------- nntp/edata.h | 4 ++-- nntp/lib.h | 8 +++---- nntp/mdata.h | 4 ++-- notmuch/adata.h | 6 ++--- pager/lib.h | 18 +++++++------- pattern/private.h | 10 ++++---- pop/adata.h | 18 +++++++------- pop/edata.h | 4 ++-- remailer.h | 14 +++++------ send/header.c | 1 + send/send.c | 4 ++-- version.c | 4 ++-- 51 files changed, 225 insertions(+), 218 deletions(-) diff --git a/alias/alias.h b/alias/alias.h index e916b58dfd0..348f68f5c7c 100644 --- a/alias/alias.h +++ b/alias/alias.h @@ -62,7 +62,7 @@ enum NotifyAlias */ struct EventAlias { - struct Alias *alias; + struct Alias *alias; ///< Alias that changed }; void alias_free (struct Alias **ptr); diff --git a/autocrypt/dlgautocrypt.c b/autocrypt/dlgautocrypt.c index 1a8c5c11d82..c501ab920cb 100644 --- a/autocrypt/dlgautocrypt.c +++ b/autocrypt/dlgautocrypt.c @@ -88,9 +88,9 @@ */ struct AccountEntry { - int num; - struct AutocryptAccount *account; - struct Address *addr; + int num; ///< Number in the index + struct AutocryptAccount *account; ///< Account details + struct Address *addr; ///< Email address associated with the account }; /// Help Bar for the Autocrypt Account selection dialog diff --git a/autocrypt/lib.h b/autocrypt/lib.h index 4d56a975571..cc72f650ea7 100644 --- a/autocrypt/lib.h +++ b/autocrypt/lib.h @@ -104,11 +104,11 @@ struct Mailbox; */ struct AutocryptAccount { - char *email_addr; - char *keyid; - char *keydata; + char *email_addr; ///< Email address + char *keyid; ///< PGP Key id + char *keydata; ///< PGP Key data bool prefer_encrypt; ///< false = nopref, true = mutual - bool enabled; + bool enabled; ///< Is this account enabled }; /** @@ -116,15 +116,15 @@ struct AutocryptAccount */ struct AutocryptPeer { - char *email_addr; - sqlite3_int64 last_seen; - sqlite3_int64 autocrypt_timestamp; - char *keyid; - char *keydata; - bool prefer_encrypt; ///< false = nopref, true = mutual - sqlite3_int64 gossip_timestamp; - char *gossip_keyid; - char *gossip_keydata; + char *email_addr; ///< Email address + sqlite3_int64 last_seen; ///< When was the peer last seen + sqlite3_int64 autocrypt_timestamp; ///< When the email was sent + char *keyid; ///< PGP Key id + char *keydata; ///< PGP Key data + bool prefer_encrypt; ///< false = nopref, true = mutual + sqlite3_int64 gossip_timestamp; ///< Timestamp of Gossip header + char *gossip_keyid; ///< Gossip Key id + char *gossip_keydata; ///< Gossip Key data }; /** @@ -132,10 +132,10 @@ struct AutocryptPeer */ struct AutocryptPeerHistory { - char *peer_email_addr; - char *email_msgid; - sqlite3_int64 timestamp; - char *keydata; + char *peer_email_addr; ///< Email address of the peer + char *email_msgid; ///< Message id of the email + sqlite3_int64 timestamp; ///< Timestamp of email + char *keydata; ///< PGP Key data }; /** @@ -143,11 +143,11 @@ struct AutocryptPeerHistory */ struct AutocryptGossipHistory { - char *peer_email_addr; - char *sender_email_addr; - char *email_msgid; - sqlite3_int64 timestamp; - char *gossip_keydata; + char *peer_email_addr; ///< Email addressof the peer + char *sender_email_addr; ///< Sender's email address + char *email_msgid; ///< Sender's email's message id + sqlite3_int64 timestamp; ///< Timestamp of sender's email + char *gossip_keydata; ///< Gossip Key data }; /** diff --git a/bcache/bcache.c b/bcache/bcache.c index 01756d81ccc..f9a047bcb1c 100644 --- a/bcache/bcache.c +++ b/bcache/bcache.c @@ -49,7 +49,7 @@ struct ConnAccount; */ struct BodyCache { - char *path; + char *path; ///< On-disk path to the file }; /** diff --git a/browser.h b/browser.h index 63f64129b75..d5d22b7c488 100644 --- a/browser.h +++ b/browser.h @@ -43,8 +43,8 @@ typedef uint8_t SelectFileFlags; ///< Flags for mutt_select_file(), e.g. #MUTT_ */ struct Folder { - struct FolderFile *ff; - int num; + struct FolderFile *ff; ///< File / Dir / Mailbox + int num; ///< Number in the index }; /** @@ -52,35 +52,35 @@ struct Folder */ struct FolderFile { - mode_t mode; - off_t size; - time_t mtime; - uid_t uid; - gid_t gid; - nlink_t nlink; + mode_t mode; ///< File permissions + off_t size; ///< File size + time_t mtime; ///< Modification time + uid_t uid; ///< File's User ID + gid_t gid; ///< File's Group ID + nlink_t nlink; ///< Number of hard links - char *name; - char *desc; + char *name; ///< Name of file/dir/mailbox + char *desc; ///< Description of mailbox - bool has_new_mail; ///< true if mailbox has "new mail" - int msg_count; ///< total number of messages - int msg_unread; ///< number of unread messages + bool has_new_mail; ///< 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; + char delim; ///< Path delimiter - bool imap : 1; - bool selectable : 1; - bool inferiors : 1; + bool imap : 1; ///< This is an IMAP folder + bool selectable : 1; ///< Folder can be selected + bool inferiors : 1; ///< Folder has children #endif - bool has_mailbox : 1; - bool local : 1; ///< folder is on local filesystem - bool tagged : 1; + bool has_mailbox : 1; ///< This is a mailbox + bool local : 1; ///< Folder is on local filesystem + bool tagged : 1; ///< Folder is tagged #ifdef USE_NNTP - struct NntpMboxData *nd; + struct NntpMboxData *nd; ///< Extra NNTP data #endif - int gen; + int gen; ///< Unique id, used for (un)sorting }; ARRAY_HEAD(BrowserStateEntry, struct FolderFile); @@ -90,12 +90,12 @@ ARRAY_HEAD(BrowserStateEntry, struct FolderFile); */ struct BrowserState { - struct BrowserStateEntry entry; + struct BrowserStateEntry entry; ///< Array of files / dirs / mailboxes #ifdef USE_IMAP - bool imap_browse; - char *folder; + bool imap_browse; ///< IMAP folder + char *folder; ///< Folder name #endif - bool is_mailbox_list; + bool is_mailbox_list; ///< Viewing mailboxes }; void mutt_select_file(char *file, size_t filelen, SelectFileFlags flags, struct Mailbox *m, char ***files, int *numfiles); diff --git a/compose/attach_data.h b/compose/attach_data.h index 40250324d14..e5a96e72a28 100644 --- a/compose/attach_data.h +++ b/compose/attach_data.h @@ -31,8 +31,8 @@ struct Menu; */ struct ComposeAttachData { - struct AttachCtx *actx; - struct Menu *menu; + struct AttachCtx *actx; ///< Set of attachments + struct Menu *menu; ///< Menu displaying the attachments }; void attach_data_free(struct Menu *menu, void **ptr); diff --git a/conn/sasl.c b/conn/sasl.c index f802b71fc10..ebc695a02b4 100644 --- a/conn/sasl.c +++ b/conn/sasl.c @@ -64,9 +64,9 @@ struct SaslSockData const unsigned int *pbufsize; /* read buffer */ - const char *buf; - unsigned int blen; - unsigned int bpos; + const char *buf; ///< Buffer for data read from the connection + unsigned int blen; ///< Size of the read buffer + unsigned int bpos; ///< Current read position void *sockdata; ///< Underlying socket data diff --git a/context.h b/context.h index 2e5d6c502c1..0cceef4e728 100644 --- a/context.h +++ b/context.h @@ -46,7 +46,7 @@ struct Context bool collapsed : 1; ///< Are all threads collapsed? - struct Mailbox *mailbox; + struct Mailbox *mailbox; ///< Current Mailbox struct Notify *notify; ///< Notifications: #NotifyContext, #EventContext }; diff --git a/core/mailbox.c b/core/mailbox.c index 32b1917a2bc..4c8f80142f4 100644 --- a/core/mailbox.c +++ b/core/mailbox.c @@ -251,10 +251,13 @@ bool mailbox_set_subset(struct Mailbox *m, struct ConfigSubset *sub) return true; } -static struct +/** + * struct EmailGarbageCollector - Email garbage collection + */ +static struct EmailGarbageCollector { - struct Email *arr[10]; - size_t idx; + struct Email *arr[10]; ///< Array of Emails to be deleted + size_t idx; ///< Current position } gc = { 0 }; /** diff --git a/core/mailbox.h b/core/mailbox.h index 9c98e0ff973..cc0c9921448 100644 --- a/core/mailbox.h +++ b/core/mailbox.h @@ -80,7 +80,7 @@ typedef uint16_t AclFlags; ///< Flags, e.g. #MUTT_ACL_ADMIN */ struct Mailbox { - struct Buffer pathbuf; + struct Buffer pathbuf; ///< Path of the Mailbox char *realpath; ///< Used for duplicate detection, context comparison, and the sidebar char *name; ///< A short name for the Mailbox struct ConfigSubset *sub; ///< Inherited config items diff --git a/core/mxapi.h b/core/mxapi.h index f9db6d708fe..d114196e8d8 100644 --- a/core/mxapi.h +++ b/core/mxapi.h @@ -46,12 +46,12 @@ struct Message bool write; ///< nonzero if message is open for writing struct { - bool read : 1; - bool flagged : 1; - bool replied : 1; - bool draft : 1; - } flags; - time_t received; ///< the time at which this message was received + bool read : 1; ///< Message has been read + bool flagged : 1; ///< Message is flagged + bool replied : 1; ///< Message has been replied to + bool draft : 1; ///< Message has been read + } flags; ///< Flags for the Message + time_t received; ///< Time at which this message was received }; diff --git a/email/email.h b/email/email.h index 889a6281d9e..dfb2708ea88 100644 --- a/email/email.h +++ b/email/email.h @@ -154,8 +154,8 @@ enum NotifyEmail */ struct EventEmail { - int num_emails; - struct Email **emails; + int num_emails; ///< Number of Emails the event applies to + struct Email **emails; ///< Emails affected by the event }; /** diff --git a/email/envelope.h b/email/envelope.h index 54ff270fa47..f0b9b7b0e44 100644 --- a/email/envelope.h +++ b/email/envelope.h @@ -40,11 +40,11 @@ */ struct AutocryptHeader { - char *addr; - char *keydata; - bool prefer_encrypt : 1; - bool invalid : 1; - struct AutocryptHeader *next; + char *addr; ///< Email address + char *keydata; ///< PGP Key data + bool prefer_encrypt : 1; ///< User prefers encryption + bool invalid : 1; ///< Header is invalid + struct AutocryptHeader *next; ///< Linked list }; #endif @@ -82,10 +82,10 @@ struct Envelope struct ListHead in_reply_to; ///< in-reply-to header content struct ListHead userhdrs; ///< user defined headers #ifdef USE_AUTOCRYPT - struct AutocryptHeader *autocrypt; - struct AutocryptHeader *autocrypt_gossip; + struct AutocryptHeader *autocrypt; ///< Autocrypt header + struct AutocryptHeader *autocrypt_gossip; ///< Autocrypt Gossip header #endif - unsigned char changed; ///< Changed fields, e.g. #MUTT_ENV_CHANGED_SUBJECT + unsigned char changed; ///< Changed fields, e.g. #MUTT_ENV_CHANGED_SUBJECT }; bool mutt_env_cmp_strict(const struct Envelope *e1, const struct Envelope *e2); diff --git a/email/rfc2231.c b/email/rfc2231.c index dd5db6e5cf8..47efc1346a9 100644 --- a/email/rfc2231.c +++ b/email/rfc2231.c @@ -50,11 +50,11 @@ */ struct Rfc2231Parameter { - char *attribute; - char *value; - int index; - bool encoded; - struct Rfc2231Parameter *next; + char *attribute; ///< Attribute name + char *value; ///< Attribute value + int index; ///< Index number in the list + bool encoded; ///< Is the value encoded? + struct Rfc2231Parameter *next; ///< Linked list }; /** diff --git a/enriched.c b/enriched.c index 19688e2fbf5..9e419c121cc 100644 --- a/enriched.c +++ b/enriched.c @@ -67,8 +67,8 @@ enum RichAttribs */ struct Etags { - const wchar_t *tag_name; - int index; + const wchar_t *tag_name; ///< Tag name + int index; ///< Index number }; // clang-format off diff --git a/enter_state.h b/enter_state.h index 5a6a9ad80f8..035df88a112 100644 --- a/enter_state.h +++ b/enter_state.h @@ -31,12 +31,12 @@ */ struct EnterState { - wchar_t *wbuf; - size_t wbuflen; - size_t lastchar; - size_t curpos; - size_t begin; - int tabs; + wchar_t *wbuf; ///< Buffer for the string being entered + size_t wbuflen; ///< Length of buffer + size_t lastchar; ///< Position of the last character + size_t curpos; ///< Position of the cursor + size_t begin; ///< Position of the start + int tabs; ///< Number of times the user has hit tab }; void mutt_enter_state_free(struct EnterState **ptr); diff --git a/gui/color.c b/gui/color.c index b0f7028dbac..cc11abebfb0 100644 --- a/gui/color.c +++ b/gui/color.c @@ -50,8 +50,8 @@ #endif #define COLOR_UNSET UINT32_MAX -#define COLOR_QUOTES_MAX \ - 10 ///< Ten colours, quoted0..quoted9 (quoted and quoted0 are equivalent) +/// Ten colours, quoted0..quoted9 (quoted and quoted0 are equivalent) +#define COLOR_QUOTES_MAX 10 /** * struct ColorList - A set of colors @@ -60,11 +60,11 @@ struct ColorList { /* TrueColor uses 24bit. Use fixed-width integer type to make sure it fits. * Use the upper 8 bits to store flags. */ - uint32_t fg; - uint32_t bg; - short index; - short count; - struct ColorList *next; + uint32_t fg; ///< Foreground colour + uint32_t bg; ///< Background colour + short index; ///< Index number + short count; ///< Number of users + struct ColorList *next; ///< Linked list }; /** @@ -89,8 +89,8 @@ static struct int quotes[COLOR_QUOTES_MAX]; ///< Array of colours for quoted email text int quotes_used; ///< Number of colours for quoted email text - struct ColorList *user_colors; - int num_user_colors; + struct ColorList *user_colors; ///< Array of user colours + int num_user_colors; ///< Number of user colours struct Notify *notify; ///< Notifications: #ColorId, #EventColor } Colors; diff --git a/gui/color.h b/gui/color.h index 4a7511c0598..8b6e0d4995d 100644 --- a/gui/color.h +++ b/gui/color.h @@ -121,7 +121,7 @@ STAILQ_HEAD(ColorLineList, ColorLine); */ struct EventColor { - enum ColorId color; + enum ColorId color; ///< Colour that has changed }; /** diff --git a/hcache/hcache.c b/hcache/hcache.c index 9227a8429e7..9595e7db965 100644 --- a/hcache/hcache.c +++ b/hcache/hcache.c @@ -174,10 +174,13 @@ static struct Email *restore(const unsigned char *d) return e; } +/** + * struct RealKey - Hcache key name (including compression method) + */ struct RealKey { - char key[1024]; - size_t len; + char key[1024]; ///< Key name + size_t len; ///< Length of key }; /** @@ -344,8 +347,8 @@ struct HeaderCache *mutt_hcache_open(const char *path, const char *folder, hcach { union { - unsigned char charval[16]; - unsigned int intval; + unsigned char charval[16]; ///< MD5 digest as a string + unsigned int intval; ///< MD5 digest as an integer } digest; struct Md5Ctx md5ctx; diff --git a/hcache/lib.h b/hcache/lib.h index 24c242461b9..e717f07ed05 100644 --- a/hcache/lib.h +++ b/hcache/lib.h @@ -85,10 +85,10 @@ struct Email; */ struct HeaderCache { - char *folder; - unsigned int crc; - void *ctx; - void *cctx; + char *folder; ///< Folder name + unsigned int crc; ///< CRC of the cache entry + void *ctx; ///< Store context (handle) + void *cctx; ///< Compression context (handle) }; /** diff --git a/hdrline.c b/hdrline.c index eef2c09afcb..0f2d679c0eb 100644 --- a/hdrline.c +++ b/hdrline.c @@ -65,10 +65,10 @@ */ struct HdrFormatInfo { - struct Mailbox *mailbox; - int msg_in_pager; - struct Email *email; - const char *pager_progress; + struct Mailbox *mailbox; ///< Current Mailbox + int msg_in_pager; ///< Index of Email displayed in the Pager + struct Email *email; ///< Current Email + const char *pager_progress; ///< String representing Pager postiion through Email }; /** diff --git a/history/history.c b/history/history.c index b80fe42cbe6..0bece13c594 100644 --- a/history/history.c +++ b/history/history.c @@ -87,9 +87,9 @@ */ struct History { - char **hist; - short cur; - short last; + char **hist; ///< Array of history items + short cur; ///< Current history item + short last; ///< Last history item }; /* global vars used for the string-history routines */ diff --git a/imap/adata.h b/imap/adata.h index a65e814ba61..c7c0bb8e48a 100644 --- a/imap/adata.h +++ b/imap/adata.h @@ -38,9 +38,9 @@ struct Mailbox; */ struct ImapAccountData { - struct Connection *conn; + struct Connection *conn; ///< Connection to IMAP server bool recovering; - bool closing; ///< If true, we are waiting for CLOSE completion + bool closing; ///< If true, we are waiting for CLOSE completion unsigned char state; ///< ImapState, e.g. #IMAP_AUTHENTICATED unsigned char status; ///< ImapFlags, e.g. #IMAP_FATAL /* let me explain capstr: SASL needs the capability string (not bits). @@ -51,11 +51,11 @@ struct ImapAccountData * I've chosen (3) for now. (2) might not be too bad, but it involves * tracking all possible capabilities. bah. (1) I don't like because * it's just no fun to get the same information twice */ - char *capstr; - ImapCapFlags capabilities; - unsigned char seqid; ///< tag sequence prefix - unsigned int seqno; ///< tag sequence number, e.g. '{seqid}0001' - time_t lastread; ///< last time we read a command for the server + char *capstr; ///< Capability string from the server + ImapCapFlags capabilities; ///< Capability flags + unsigned char seqid; ///< tag sequence prefix + unsigned int seqno; ///< tag sequence number, e.g. '{seqid}0001' + time_t lastread; ///< last time we read a command for the server char *buf; size_t blen; @@ -66,13 +66,13 @@ struct ImapAccountData struct ImapList *cmdresult; /* command queue */ - struct ImapCommand *cmds; - int cmdslots; - int nextcmd; - int lastcmd; + struct ImapCommand *cmds; ///< Queue of commands for the server + int cmdslots; ///< Size of the command queue + int nextcmd; ///< Next command to be sent + int lastcmd; ///< Last command in the queue struct Buffer cmdbuf; - char delim; + char delim; ///< Path delimiter struct Mailbox *mailbox; ///< Current selected mailbox struct Mailbox *prev_mailbox; ///< Previously selected mailbox struct Account *account; ///< Parent Account diff --git a/imap/edata.h b/imap/edata.h index 33dfe7957da..f071d7244d0 100644 --- a/imap/edata.h +++ b/imap/edata.h @@ -33,11 +33,11 @@ struct Email; struct ImapEmailData { /* server-side flags */ - bool read : 1; - bool old : 1; - bool deleted : 1; - bool flagged : 1; - bool replied : 1; + bool read : 1; ///< Email has been read + bool old : 1; ///< Email has been seen + bool deleted : 1; ///< Email has been deleted + bool flagged : 1; ///< Email has been flagged + bool replied : 1; ///< Email has been replied to bool parsed : 1; diff --git a/imap/mdata.h b/imap/mdata.h index 8c9ab4a911c..6b05abae706 100644 --- a/imap/mdata.h +++ b/imap/mdata.h @@ -57,9 +57,9 @@ struct ImapMboxData // Cached data used only when the mailbox is opened struct HashTable *uid_hash; ARRAY_HEAD(MSN, struct Email *) msn; ///< look up headers by (MSN-1) - struct BodyCache *bcache; + struct BodyCache *bcache; ///< Email body cache - struct HeaderCache *hcache; + struct HeaderCache *hcache; ///< Email header cache }; void imap_mdata_free(void **ptr); diff --git a/keymap.c b/keymap.c index 08e54c8ba3b..182968cf714 100644 --- a/keymap.c +++ b/keymap.c @@ -131,8 +131,8 @@ struct KeymapList Keymaps[MENU_MAX]; */ struct Extkey { - const char *name; - const char *sym; + const char *name; ///< NeoMutt key name + const char *sym; ///< Curses key name }; static const struct Extkey ExtKeys[] = { diff --git a/maildir/mdata.h b/maildir/mdata.h index 78c7c9f8d37..c1f9800e565 100644 --- a/maildir/mdata.h +++ b/maildir/mdata.h @@ -33,8 +33,8 @@ struct Mailbox; */ struct MaildirMboxData { - struct timespec mtime_cur; - mode_t mh_umask; + struct timespec mtime_cur; ///< Timestamp of the 'cur' dir + mode_t mh_umask; ///< umask to use when creating files }; void maildir_mdata_free(void **ptr); diff --git a/monitor.c b/monitor.c index 4fcfd077cee..69e4cfe3542 100644 --- a/monitor.c +++ b/monitor.c @@ -81,7 +81,7 @@ enum ResolveResult */ struct Monitor { - struct Monitor *next; + struct Monitor *next; ///< Linked list char *mh_backup_path; dev_t st_dev; ino_t st_ino; diff --git a/mutt/file.h b/mutt/file.h index 0dbf8301fb9..95f9148415e 100644 --- a/mutt/file.h +++ b/mutt/file.h @@ -47,8 +47,8 @@ struct timespec; */ struct timespec { - time_t tv_sec; - long tv_nsec; + time_t tv_sec; ///< Number of seconds since the epoch + long tv_nsec; ///< Number of nanosecond, on top }; #endif diff --git a/mutt/mapping.h b/mutt/mapping.h index c6bf9374972..f9958d9e1e5 100644 --- a/mutt/mapping.h +++ b/mutt/mapping.h @@ -30,8 +30,8 @@ */ struct Mapping { - const char *name; - int value; + const char *name; ///< String value + int value; ///< Integer value }; const char *mutt_map_get_name(int val, const struct Mapping *map); diff --git a/mutt/notify.c b/mutt/notify.c index 9877ad773b2..3f3eeff8e31 100644 --- a/mutt/notify.c +++ b/mutt/notify.c @@ -49,8 +49,8 @@ static char *NotifyTypeNames[] = { */ struct Notify { - struct Notify *parent; - struct ObserverList observers; + struct Notify *parent; ///< Parent of the notification object + struct ObserverList observers; ///< List of observers of this object }; /** diff --git a/mutt/slist.h b/mutt/slist.h index 8d8e011ce5c..8a311d01b19 100644 --- a/mutt/slist.h +++ b/mutt/slist.h @@ -45,9 +45,9 @@ struct Buffer; */ struct Slist { - struct ListHead head; - size_t count; - uint32_t flags; + struct ListHead head; ///< List containing values + size_t count; ///< Number of values in list + uint32_t flags; ///< Flags controlling list, e.g. #SLIST_SEP_SPACE }; struct Slist *slist_add_list(struct Slist *list, const struct Slist *add); diff --git a/mutt/string.c b/mutt/string.c index 42a2388ceff..0bd3460c025 100644 --- a/mutt/string.c +++ b/mutt/string.c @@ -51,8 +51,8 @@ */ struct SysExits { - int err_num; - const char *err_str; + int err_num; ///< Error number, see errno(3) + const char *err_str; ///< Human-readable string for error }; static const struct SysExits sysexits[] = { diff --git a/ncrypt/crypt_gpgme.h b/ncrypt/crypt_gpgme.h index 0a9a08d0516..37f5ec711f5 100644 --- a/ncrypt/crypt_gpgme.h +++ b/ncrypt/crypt_gpgme.h @@ -43,7 +43,7 @@ struct State; */ struct CryptKeyInfo { - struct CryptKeyInfo *next; + struct CryptKeyInfo *next; ///< Linked list gpgme_key_t kobj; int idx; ///< and the user ID at this index const char *uid; ///< and for convenience point to this user ID diff --git a/ncrypt/dlggpgme.c b/ncrypt/dlggpgme.c index 14c790f8d43..f9fe4a55a22 100644 --- a/ncrypt/dlggpgme.c +++ b/ncrypt/dlggpgme.c @@ -115,8 +115,8 @@ static const struct Mapping GpgmeHelp[] = { */ struct CryptEntry { - size_t num; - struct CryptKeyInfo *key; + size_t num; ///< Index number + struct CryptKeyInfo *key; ///< Key }; /** @@ -124,8 +124,8 @@ struct CryptEntry */ struct DnArray { - char *key; - char *value; + char *key; ///< Key + char *value; ///< Value }; static const char *const KeyInfoPrompts[] = { diff --git a/ncrypt/dlgpgp.c b/ncrypt/dlgpgp.c index 406d3cf069f..b509861d05d 100644 --- a/ncrypt/dlgpgp.c +++ b/ncrypt/dlgpgp.c @@ -110,7 +110,7 @@ static const struct Mapping PgpHelp[] = { */ struct PgpEntry { - size_t num; + size_t num; ///< Index number struct PgpUid *uid; }; diff --git a/ncrypt/pgpkey.c b/ncrypt/pgpkey.c index db8e5e7ac18..a5a8c49a22a 100644 --- a/ncrypt/pgpkey.c +++ b/ncrypt/pgpkey.c @@ -65,7 +65,7 @@ struct PgpCache { char *what; char *dflt; - struct PgpCache *next; + struct PgpCache *next; ///< Linked list }; static struct PgpCache *id_defaults = NULL; diff --git a/ncrypt/pgplib.h b/ncrypt/pgplib.h index 661aade7581..e31e2f35a05 100644 --- a/ncrypt/pgplib.h +++ b/ncrypt/pgplib.h @@ -36,8 +36,8 @@ struct PgpUid char *addr; short trust; int flags; - struct PgpKeyInfo *parent; - struct PgpUid *next; + struct PgpKeyInfo *parent; ///< Parent key + struct PgpUid *next; ///< Linked list }; /** diff --git a/nntp/adata.h b/nntp/adata.h index 9c451a76e15..bf3fee213a6 100644 --- a/nntp/adata.h +++ b/nntp/adata.h @@ -35,15 +35,15 @@ struct Mailbox; */ struct NntpAccountData { - bool hasCAPABILITIES : 1; - bool hasSTARTTLS : 1; - bool hasDATE : 1; - bool hasLIST_NEWSGROUPS : 1; - bool hasXGTITLE : 1; - bool hasLISTGROUP : 1; - bool hasLISTGROUPrange : 1; - bool hasOVER : 1; - bool hasXOVER : 1; + bool hasCAPABILITIES : 1; ///< Server supports CAPABILITIES command + bool hasSTARTTLS : 1; ///< Server supports STARTTLS command + bool hasDATE : 1; ///< Server supports DATE command + bool hasLIST_NEWSGROUPS : 1; ///< Server supports LIST_NEWSGROUPS command + bool hasXGTITLE : 1; ///< Server supports XGTITLE command + bool hasLISTGROUP : 1; ///< Server supports LISTGROUP command + bool hasLISTGROUPrange : 1; ///< Server supports LISTGROUPrange command + bool hasOVER : 1; ///< Server supports OVER command + bool hasXOVER : 1; ///< Server supports XOVER command unsigned int use_tls : 3; unsigned int status : 3; bool cacheable : 1; @@ -60,7 +60,7 @@ struct NntpAccountData unsigned int groups_max; void **groups_list; struct HashTable *groups_hash; - struct Connection *conn; + struct Connection *conn; ///< Connection to NNTP Server }; void nntp_adata_free(void **ptr); diff --git a/nntp/edata.h b/nntp/edata.h index 5804fbed24f..97ce0efd8a3 100644 --- a/nntp/edata.h +++ b/nntp/edata.h @@ -33,8 +33,8 @@ struct Email; */ struct NntpEmailData { - anum_t article_num; - bool parsed : 1; + anum_t article_num; ///< NNTP article number + bool parsed : 1; ///< Email has been parse }; void nntp_edata_free(void **ptr); diff --git a/nntp/lib.h b/nntp/lib.h index 62a53984636..f31cdd5f926 100644 --- a/nntp/lib.h +++ b/nntp/lib.h @@ -65,8 +65,8 @@ extern struct MxOps MxNntpOps; */ struct NntpAcache { - unsigned int index; - char *path; + unsigned int index; ///< Index number + char *path; ///< Cache path }; /** @@ -74,8 +74,8 @@ struct NntpAcache */ struct NewsrcEntry { - anum_t first; - anum_t last; + anum_t first; ///< First article number in run + anum_t last; ///< Last article number in run }; /* number of entries in article cache */ diff --git a/nntp/mdata.h b/nntp/mdata.h index 2a86fa67bb8..e994d91ed22 100644 --- a/nntp/mdata.h +++ b/nntp/mdata.h @@ -31,8 +31,8 @@ */ struct NntpMboxData { - char *group; - char *desc; + char *group; ///< Name of newsgroup + char *desc; ///< Description of newsgroup anum_t first_message; anum_t last_message; anum_t last_loaded; diff --git a/notmuch/adata.h b/notmuch/adata.h index dfdfbee7f63..7f0fe8a290a 100644 --- a/notmuch/adata.h +++ b/notmuch/adata.h @@ -33,9 +33,9 @@ struct Mailbox; */ struct NmAccountData { - notmuch_database_t *db; - bool longrun : 1; ///< A long-lived action is in progress - bool trans : 1; ///< Atomic transaction in progress + notmuch_database_t *db; ///< Connection to Notmuch database + bool longrun : 1; ///< A long-lived action is in progress + bool trans : 1; ///< Atomic transaction in progress }; void nm_adata_free(void **ptr); diff --git a/pager/lib.h b/pager/lib.h index 18e8a9666ac..c32880b98a7 100644 --- a/pager/lib.h +++ b/pager/lib.h @@ -153,15 +153,15 @@ struct PagerData */ struct PagerView { - struct PagerData *pdata; ///< Data that pager displays. NOTNULL - enum PagerMode mode; ///< Pager mode - PagerFlags flags; ///< Additional settings to tweak pager's function - const char *banner; ///< Title to display in status bar - - struct MuttWindow *win_ibar; - struct MuttWindow *win_index; - struct MuttWindow *win_pbar; - struct MuttWindow *win_pager; + struct PagerData *pdata; ///< Data that pager displays. NOTNULL + enum PagerMode mode; ///< Pager mode + PagerFlags flags; ///< Additional settings to tweak pager's function + const char *banner; ///< Title to display in status bar + + struct MuttWindow *win_ibar; ///< Index Bar Window + struct MuttWindow *win_index; ///< Index Window + struct MuttWindow *win_pbar; ///< Pager Bar Window + struct MuttWindow *win_pager; ///< Pager Window }; typedef uint8_t NotifyPager; ///< Flags, e.g. #NT_PAGER_ACCOUNT diff --git a/pattern/private.h b/pattern/private.h index c60fd84b72c..3700858e003 100644 --- a/pattern/private.h +++ b/pattern/private.h @@ -48,12 +48,12 @@ enum PatternEat */ struct PatternFlags { - int tag; ///< Character used to represent this operation, e.g. 'A' for '~A' - int op; ///< Operation to perform, e.g. #MUTT_PAT_SCORE - PatternCompFlags flags; ///< Pattern flags, e.g. #MUTT_PC_FULL_MSG + int tag; ///< Character used to represent this operation, e.g. 'A' for '~A' + int op; ///< Operation to perform, e.g. #MUTT_PAT_SCORE + PatternCompFlags flags; ///< Pattern flags, e.g. #MUTT_PC_FULL_MSG - enum PatternEat eat_arg; - char *desc; + enum PatternEat eat_arg; ///< Type of function needed to parse flag, e.g. #EAT_DATE + char *desc; ///< Description of flag }; /** diff --git a/pop/adata.h b/pop/adata.h index 0fc13669509..b48f8346708 100644 --- a/pop/adata.h +++ b/pop/adata.h @@ -35,18 +35,18 @@ struct Mailbox; */ struct PopAccountData { - struct Connection *conn; - unsigned int status : 2; - bool capabilities : 1; + struct Connection *conn; ///< Connection to POP server + 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 + 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; + 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 diff --git a/pop/edata.h b/pop/edata.h index 3563950eeb3..41c9a3eaccb 100644 --- a/pop/edata.h +++ b/pop/edata.h @@ -30,8 +30,8 @@ struct Email; */ struct PopEmailData { - const char *uid; - int refno; ///< Message number on server + const char *uid; ///< UID of email + int refno; ///< Message number on server }; void pop_edata_free(void **ptr); diff --git a/remailer.h b/remailer.h index 053568cc055..a779d174e17 100644 --- a/remailer.h +++ b/remailer.h @@ -44,11 +44,11 @@ typedef uint8_t MixCapFlags; ///< Flags, e.g. #MIX_CAP_NO_FLAGS */ struct Remailer { - int num; - char *shortname; - char *addr; - char *ver; - MixCapFlags caps; + int num; ///< Index number + char *shortname; ///< Short name of remailer host + char *addr; ///< Address of host + char *ver; ///< Version of host + MixCapFlags caps; ///< Capabilities of host }; /** @@ -56,8 +56,8 @@ struct Remailer */ struct MixChain { - size_t cl; - int ch[MAX_MIXES]; + size_t cl; ///< Length of chain + int ch[MAX_MIXES]; ///< Indexes of chain hosts }; int mix_send_message(struct ListHead *chain, const char *tempfile); diff --git a/send/header.c b/send/header.c index b1750c1b833..2515d327c26 100644 --- a/send/header.c +++ b/send/header.c @@ -67,6 +67,7 @@ enum UserHdrsOverrideIdx */ struct UserHdrsOverride { + /// Which email headers have been overridden bool is_overridden[mutt_array_size(userhdrs_override_headers)]; }; diff --git a/send/send.c b/send/send.c index cb59b591eb1..d3edfb859fe 100644 --- a/send/send.c +++ b/send/send.c @@ -90,8 +90,8 @@ */ struct GreetingInfo { - struct Mailbox *mailbox; - struct Email *email; + struct Mailbox *mailbox; ///< Current Mailbox + struct Email *email; ///< Current Email }; /** diff --git a/version.c b/version.c index fa7ca932124..7d99fbe72c6 100644 --- a/version.c +++ b/version.c @@ -120,8 +120,8 @@ static const char *Notice = */ struct CompileOptions { - const char *name; - int enabled; ///< 0 Disabled, 1 Enabled, 2 Devel only + const char *name; ///< Option name + int enabled; ///< 0 Disabled, 1 Enabled, 2 Devel only }; /* These are sorted by the display string */