doxy: improve comments

flatcap · Apr 11, 2021 · b2ba20d · b2ba20d
1 parent f0eee5f
commit b2ba20d
Show file tree

Hide file tree

Showing 11 changed files with 15 additions and 12 deletions.
diff --git a/alternates.c b/alternates.c
@@ -150,7 +150,9 @@ enum CommandResult parse_unalternates(struct Buffer *buf, struct Buffer *s,
 }
 
 /**
- * mutt_alternates_match - XXX
+ * mutt_alternates_match - Compare an Address to the Un/Alternates lists
+ * @param addr Address to check
+ * @retval true Address matches
  */
 bool mutt_alternates_match(const char *addr)
 {

diff --git a/config/subset.h b/config/subset.h
@@ -49,7 +49,7 @@ struct ConfigSubset
   enum ConfigScope scope;      ///< Scope of Subset, e.g. #SET_SCOPE_ACCOUNT
   struct ConfigSubset *parent; ///< Parent Subset
   struct ConfigSet *cs;        ///< Parent ConfigSet
-  struct Notify *notify;       ///< Notifications system
+  struct Notify *notify;       ///< Notifications: #NotifyConfig, #EventConfig
 };
 
 /**

diff --git a/context.h b/context.h
@@ -47,7 +47,7 @@ struct Context
   bool collapsed : 1;                ///< Are all threads collapsed?
 
   struct Mailbox *mailbox;
-  struct Notify *notify;             ///< Notifications handler
+  struct Notify *notify;             ///< Notifications: #NotifyContext, #EventContext
 };
 
 /**

diff --git a/core/account.h b/core/account.h
@@ -39,7 +39,7 @@ struct Account
   char *name;                     ///< Name of Account
   struct ConfigSubset *sub;       ///< Inherited config items
   struct MailboxList mailboxes;   ///< List of Mailboxes
-  struct Notify *notify;          ///< Notifications handler
+  struct Notify *notify;          ///< Notifications: #NotifyAccount, #EventAccount
   void *adata;                    ///< Private data (for Mailbox backends)
 
   /**

diff --git a/core/mailbox.h b/core/mailbox.h
@@ -141,7 +141,7 @@ struct Mailbox
    */
   void (*mdata_free)(void **ptr);
 
-  struct Notify *notify;              ///< Notifications handler
+  struct Notify *notify;              ///< Notifications: #NotifyMailbox, #EventMailbox
 
   int gen;                            ///< Generation number, for sorting
 };

diff --git a/email/email.h b/email/email.h
@@ -116,7 +116,7 @@ struct Email
    */
   void (*edata_free)(void **ptr);
 
-  struct Notify *notify;       ///< Notifications handler
+  struct Notify *notify;       ///< Notifications: #NotifyEmail, #EventEmail
 };
 
 /**

diff --git a/gui/color.h b/gui/color.h
@@ -149,7 +149,7 @@ struct Colors
   struct ColorList *user_colors;
   int num_user_colors;
 
-  struct Notify *notify;                   ///< Notifications system
+  struct Notify *notify;                   ///< Notifications: #ColorId, #EventColor
 };
 
 /**

diff --git a/gui/dialog.c b/gui/dialog.c
@@ -158,8 +158,9 @@ static int dialog_config_observer(struct NotifyCallback *nc)
 
 /**
  * dialog_create_simple_index - Create a simple index Dialog
- * @param mtype Menu type, e.g. #MENU_ALIAS
- * @param wtype Dialog type, e.g. #WT_DLG_ALIAS
+ * @param mtype     Menu type, e.g. #MENU_ALIAS
+ * @param wtype     Dialog type, e.g. #WT_DLG_ALIAS
+ * @param help_data Data for the Help Bar
  * @retval ptr New Dialog Window
  */
 struct MuttWindow *dialog_create_simple_index(enum MenuType mtype, enum WindowType wtype,

diff --git a/gui/mutt_window.h b/gui/mutt_window.h
@@ -129,7 +129,7 @@ struct MuttWindow
   struct MuttWindow *parent;         ///< Parent Window
   struct MuttWindowList children;    ///< Children Windows
 
-  struct Notify *notify;             ///< Notifications system
+  struct Notify *notify;             ///< Notifications: #NotifyWindow, #EventWindow
 
   struct MuttWindow *focus;          ///< Focussed Window
   int help_menu;                     ///< Menu for key bindings, e.g. #MENU_PAGER

diff --git a/index/shared_data.h b/index/shared_data.h
@@ -41,7 +41,7 @@ struct IndexSharedData
   struct Mailbox *mailbox;  ///< Current Mailbox
   struct Email *email;      ///< Currently selected Email
   size_t email_seq;         ///< Sequence number of the current email
-  struct Notify *notify;    ///< Notifications handler
+  struct Notify *notify;    ///< Notifications: #NotifyIndex, #IndexSharedData
 };
 
 void                    index_shared_data_free(struct MuttWindow *win, void **ptr);

diff --git a/pattern/dlgpattern.c b/pattern/dlgpattern.c
@@ -227,7 +227,7 @@ static struct Menu *create_pattern_menu(struct MuttWindow *dlg)
 
 /**
  * free_pattern_menu - Free the Pattern Completion menu
- * @param ptr Menu to free
+ * @param menu Menu to free
  */
 static void free_pattern_menu(struct Menu *menu)
 {