From b96d97aa07ef86eb5d4620f792c4ef2a9049f2d7 Mon Sep 17 00:00:00 2001
From: itsmattkc <itsmattkc@gmail.com>
Date: Fri, 22 Mar 2019 02:39:54 +1100
Subject: [PATCH] further preferences dialog documentation

---
 dialogs/preferencesdialog.h | 78 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 77 insertions(+), 1 deletion(-)

diff --git a/dialogs/preferencesdialog.h b/dialogs/preferencesdialog.h
index 6a5bade56..347212f4b 100644
--- a/dialogs/preferencesdialog.h
+++ b/dialogs/preferencesdialog.h
@@ -62,17 +62,93 @@ private slots:
    * @brief Override of accept to save preferences to Config.
    */
   virtual void accept() override;
+
+  /**
+   * @brief Reset all selected shortcuts in keyboard_tree to their defaults
+   */
   void reset_default_shortcut();
+
+  /**
+   * @brief Reset all shortcuts indiscriminately to their defaults
+   *
+   * This is safe to call directly as it'll ask the user if they wish to do so before it resets.
+   */
   void reset_all_shortcuts();
-  bool refine_shortcut_list(const QString &, QTreeWidgetItem* parent = nullptr);
+
+  /**
+   * @brief Shows/hides shortcut entries according to a shortcut query.
+   *
+   * This function can be directly connected to QLineEdit::textChanged() for simplicity.
+   *
+   * @param s
+   *
+   * The search query to compare shortcut names to.
+   *
+   * @param parent
+   *
+   * This is used as the function calls itself recursively to traverse the menu item hierarchy. This should be left as
+   * nullptr when called externally.
+   *
+   * @return
+   *
+   * Value used as function calls itself recursively to determine if a menu parent has any children that are not hidden.
+   * If so, TRUE is returned so the parent is shown too (even if it doesn't match the search query). If not, FALSE is
+   * returned so the parent is hidden.
+   */
+  bool refine_shortcut_list(const QString &s, QTreeWidgetItem* parent = nullptr);
+
+  /**
+   * @brief Show a file dialog to load an external shortcut preset from file
+   */
   void load_shortcut_file();
+
+  /**
+   * @brief Show a file dialog to save an external shortcut preset from file
+   */
   void save_shortcut_file();
+
+  /**
+   * @brief Show a file dialog to browse for an external CSS file to load for styling the application.
+   */
   void browse_css_file();
+
+  /**
+   * @brief Delete all previews (waveform and thumbnail cache)
+   */
   void delete_all_previews();
 
 private:
+
+  /**
+   * @brief Create and arrange all UI widgets
+   */
   void setup_ui();
+
+  /**
+   * @brief Populate keyboard shortcut panel with keyboard shortcuts from the menu bar
+   *
+   * @param menu
+   *
+   * A reference to the main application's menu bar. Usually MainWindow::menuBar().
+   */
   void setup_kbd_shortcuts(QMenuBar* menu);
+
+  /**
+   * @brief Internal function called by setup_kbd_shortcuts() to traverse down the menu bar's hierarchy and populate the
+   * shortcut panel.
+   *
+   * This function will call itself recursively as it finds submenus belong to the menu provided. It will also create
+   * QTreeWidgetItems as children of the parent item provided, either using them as parents themselves for submenus
+   * or attaching a KeySequenceEditor to them for shortcut editing.
+   *
+   * @param menu
+   *
+   * The current menu to traverse down.
+   *
+   * @param parent
+   *
+   * The parent item to add QTreeWidgetItems to.
+   */
   void setup_kbd_shortcut_worker(QMenu* menu, QTreeWidgetItem* parent);
 
   // used to delete previews