doxy: document struct members

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

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

autocrypt/lib.h

@@ -104,50 +104,50 @@ 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
 };
 
 /**
  * struct AutocryptPeer - Autocrypt peer
  */
 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
 };
 
 /**
  * struct AutocryptPeerHistory - Autocrypt peer history
  */
 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
 };
 
 /**
  * struct AutocryptGossipHistory - Autocrypt gossip history
  */
 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
 };
 
 /**

bcache/bcache.c

@@ -49,7 +49,7 @@ struct ConnAccount;
  */
 struct BodyCache
 {
-  char *path;
+  char *path; ///< On-disk path to the file
 };
 
 /**

browser.h

@@ -43,44 +43,44 @@ 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
 };
 
 /**
  * struct FolderFile - Browser entry representing a folder/dir
  */
 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);

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

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
 

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
 };
 

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

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

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
 };
 
 

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

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

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

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

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

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;