add documentation to GUI header files

9 files changed, 139 insertions, 27 deletions

diff --git a/confui/mainwindow.h b/confui/mainwindow.h
index 398ed7f..ad0e363 100644
--- a/confui/mainwindow.h
+++ b/confui/mainwindow.h
@@ -10,6 +10,12 @@
 class CDAutomationsTabWidget;
 class CDNodeOverviewTabWidget;
 
+/**
+ * @brief main window
+ *
+ * creates menu bar and tabs
+ * cascading refresh (automatic and manual)
+ */
 class CDMainWindow : public QMainWindow {
 	Q_OBJECT
 private:
@@ -22,7 +28,10 @@ public:
 	
 	CDMainWindow(QWidget *parent = nullptr);
 	~CDMainWindow();
+	/** @brief update user interface */
 	virtual void update();
+	/** @brief menu bar refresh action handler */
 	virtual void menu_refresh();
+	/** @brief menu bar add automation action handler */
 	virtual void menu_add_automation();
 };
diff --git a/confui/mesh_connector.cpp b/confui/mesh_connector.cpp
index 233f860..a9742cf 100644
--- a/confui/mesh_connector.cpp
+++ b/confui/mesh_connector.cpp
@@ -81,26 +81,31 @@ CDMeshConnector::~CDMeshConnector() {
 }
 
 map<cd_uid_t, cd_s_node*> CDMeshConnector::get_nodes(bool provisioned) {
+	if (provisioned == false) return _nodes;
+
+	// filter only if provisioned nodes are desired
 	map<cd_uid_t, cd_s_node*> nodes;
 	for (pair<cd_uid_t, cd_s_node*> node : _nodes) {
-		if (provisioned && (node.second->provisioned == false)) continue;
+		if (node.second->provisioned == false) continue;
 		nodes[node.first] = node.second;
 	}
 	return nodes;
 }
 
 map<cd_link_t, cd_s_automation*> CDMeshConnector::get_links(bool valid) {
+	if (valid == false) return _links;
+
+	// filter only if valid links are desired
 	map<cd_link_t, cd_s_automation*> links;
 	for (pair<cd_link_t, cd_s_automation*> link : _links) {
-		if (valid && (link.second->valid == false)) continue;
+		if (link.second->valid == false) continue;
 		links[link.first] = link.second;
 	}
 	return links;
 }
 
-void CDMeshConnector::update_link(cd_link_t link, cd_s_automation* automation) {
-	_links[link] = automation;
-	printf("link[%d]", link);
+void CDMeshConnector::update_link(cd_s_automation* automation) {
+	printf("link[%d]", automation->id);
 	if (automation->valid) {
 		printf(" = %.*s %s %.*s", (int) automation->button->name_len, automation->button->name, automation->type == CD_AUTOMATION_TYPE_TOGGLE ? "toggles" : automation->type == CD_AUTOMATION_TYPE_TURN_OFF ? "turns off" : "turns on", (int) automation->light->name_len, automation->light->name);
 	} else {
@@ -120,7 +125,8 @@ cd_link_t CDMeshConnector::create_link(cd_uid_t button, cd_uid_t light, enum cd_
 	automation->valid = true;
 
 	printf("(new) ");
-	update_link(id, automation);
+	_links[id] = automation;
+	update_link(automation);
 
 	return id;
 }
@@ -136,7 +142,8 @@ cd_link_t CDMeshConnector::create_link() {
 	automation->valid = false;
 
 	printf("(new) ");
-	update_link(id, automation);
+	_links[id] = automation;
+	update_link(automation);
 
 	return id;
 }
diff --git a/confui/mesh_connector.h b/confui/mesh_connector.h
index 2e810d4..dcab354 100644
--- a/confui/mesh_connector.h
+++ b/confui/mesh_connector.h
@@ -11,45 +11,68 @@ using std::map;
 using std::string;
 using std::array;
 
+/** @brief node id type, GUI only */
 typedef uint32_t cd_uid_t;
+/** @brief link/automation id type */
 typedef uint32_t cd_link_t;
+/** @brief node mac address type */
 typedef uint8_t cd_mac_addr_t[6];
 
+/** @brief automation types/actions */
 enum cd_e_automation_type {
-	CD_AUTOMATION_TYPE_TOGGLE,
-	CD_AUTOMATION_TYPE_TURN_ON,
-	CD_AUTOMATION_TYPE_TURN_OFF,
+	CD_AUTOMATION_TYPE_TOGGLE, /** @brief button toggles light */
+	CD_AUTOMATION_TYPE_TURN_ON, /** @brief button always turns on light (regardless of previous state) */
+	CD_AUTOMATION_TYPE_TURN_OFF, /** @brief button always turns off light (regardless of previous state) */
 };
 
+/** @brief GUI node representation */
 typedef struct {
-	cd_uid_t id;
-	cd_mac_addr_t address;
-	size_t name_len;
-	const char* name;
-	bool light_on;
-	bool provisioned;
+	cd_uid_t id; /** @brief GUI-specific id (used as handle) */
+	cd_mac_addr_t address; /** @brief node bluetooth mac address */
+	size_t name_len; /** @brief name length in bytes */
+	const char* name; /** @brief user-friendly node name */
+	bool light_on; /** @brief state of light on node */
+	bool provisioned; /** @brief whether the node is provisioned into the network */
 } cd_s_node;
 
+/** @brief automation/link struct */
 typedef struct {
-	cd_link_t id;
-	cd_e_automation_type type;
-	cd_s_node* button;
-	cd_s_node* light;
-	bool valid;
+	cd_link_t id; /** @brief automation id (also used as handle) */
+	cd_e_automation_type type; /** @brief automation type/action */
+	cd_s_node* button; /** @brief pointer to node with button */
+	cd_s_node* light; /** @brief pointer to node with light */
+	bool valid; /** @brief whether .button and .light are valid pointers (complete automation) */
 } cd_s_automation;
 
+/**
+ * @brief mesh network connector
+ * 
+ * handles communication with the border router over a serial connection and
+ * exposes current network state through structured data (as defined above).
+ *
+ * the terms link and automation are used interchangibly. a set of automation
+ * rules is called the configuration. nodes are sometimes referred to as light
+ * or button when that specific part of a node is used. the terms
+ * (gui-specific) id's and handles are also used interchangibly.
+ */
 class CDMeshConnector {
 private:
+	/** @brief list of links */
 	map<cd_link_t, cd_s_automation*> _links;
+	/** @brief list of nodes */
 	map<cd_uid_t, cd_s_node*> _nodes;
 
-	virtual cd_link_t get_new_link_id();
-	virtual cd_uid_t get_new_node_id();
-
 	cd_link_t _fresh_link_id = 0;
 	cd_uid_t _fresh_node_id = 0;
 
+	/** @brief get 'fresh' link id and increment */
+	virtual cd_link_t get_new_link_id();
+	/** @brief get 'fresh' node id and increment */
+	virtual cd_uid_t get_new_node_id();
+
+	/** @brief register a node to this class (GUI only) */
 	virtual cd_uid_t create_node(cd_s_node node);
+	/** @brief unregister a node from this class (GUI only) */
 	virtual void remove_node(cd_uid_t node_handle);
 
 public:
@@ -57,30 +80,89 @@ public:
 	virtual ~CDMeshConnector();
 
 	// (UNUSED/UNIMPLEMENTED) refresh functions
+	/** @brief [UNIMPL] force refresh network node list */
 	virtual void refresh_nodes_sync();
+	/** @brief [UNIMPL] force refresh network automation configuration */
 	virtual void refresh_config_sync();
 
 	// data fetching functions
+	/**
+	 * @brief get map of automations and their respective handles
+	 *
+	 * @param valid  `valid` field of automation needs to match this value.
+	 * `true` by default
+	 */
 	virtual map<cd_link_t, cd_s_automation*> get_links(bool valid = true);
+	/**
+	 * @brief get map of nodes and their respective handles
+	 *
+	 * @param provisioned  `provisioned` field of node needs to match this value.
+	 * `false` by default
+	 */
 	virtual map<cd_uid_t, cd_s_node*> get_nodes(bool provisioned = false);
+	/** @brief get automation pointer by automation id */
 	virtual cd_s_automation* get_link(cd_link_t id);
+	/** @brief get node pointer by node id */
 	virtual cd_s_node* get_node(cd_uid_t id);
 
 	// network modification functions
 	/** @brief create empty automation */
 	virtual cd_link_t create_link();
-	/** @brief create valid automation */
+	/**
+	 * @brief create valid automation with filled-in fields and update on
+	 * network.
+	 *
+	 * @param button  node id for node whose button will be used for this
+	 * automation.
+	 * @param light  node id for node whose light will be used for this
+	 * automation.
+	 * @param action  action/automation type (toggle, on, off).
+	 */
 	virtual cd_link_t create_link(cd_uid_t button, cd_uid_t light, enum cd_e_automation_type action);
-	virtual void update_link(cd_link_t link, cd_s_automation* automation);
+	/**
+	 * @brief overwrite link id with new automation and update on network.
+	 *
+	 * `automation` needs to be a globally available pointer to an automation
+	 * (e.g. one allocated using malloc()). used to update existing automation
+	 * properties.
+	 *
+	 * @param automation  pointer to automation struct (with new/modified values)
+	 */
+	virtual void update_link(cd_s_automation* automation);
+	/**
+	 * @brief remove automation and update on network.
+	 *
+	 * @param link_handle  automation id
+	 */
 	virtual void remove_link(cd_link_t link_handle);
 
+	/**
+	 * @brief overwrite node id with new node and update on network.
+	 *
+	 * `node` needs to be a globally available pointer to a node (e.g. one
+	 * allocated using malloc()). used to update existing node properties.
+	 *
+	 * @param node_ptr  pointer to node struct (with new/modified state)
+	 */
 	virtual void update_node(cd_s_node* node_ptr);
+	/**
+	 * @brief provision node into network
+	 *
+	 * @param node_ptr  pointer to node struct
+	 */
 	virtual void network_join_node(cd_s_node* node_ptr);
+	/**
+	 * @brief provision node out of network (remove from network)
+	 *
+	 * @param node_ptr  pointer to node struct
+	 */
 	virtual void network_remove_node(cd_s_node* node_ptr);
 
 	// conversion functions
+	/** @brief convert `cd_mac_addr_t` to `std::string` for printing/GUI */
 	static string cd_mac_to_string(cd_mac_addr_t mac);
 };
 
+/** @brief global pointer to mesh connector, initialized in CDMainWindow */
 extern CDMeshConnector* g_cd_mesh_connector;
 
diff --git a/confui/ui_automation.cpp b/confui/ui_automation.cpp
index 663d032..d4e84a7 100644
--- a/confui/ui_automation.cpp
+++ b/confui/ui_automation.cpp
@@ -78,7 +78,7 @@ void CDAutomationWidget::apply() {
 	_automation->light = g_cd_mesh_connector->get_node(dropdown_light->findData(dropdown_light->currentIndex()));
 	_automation->valid = true;
 
-	g_cd_mesh_connector->update_link(_id, _automation);
+	g_cd_mesh_connector->update_link(_automation);
 }
 
 void CDAutomationWidget::remove() {
diff --git a/confui/ui_automation.h b/confui/ui_automation.h
index e4118dc..69f2bdd 100644
--- a/confui/ui_automation.h
+++ b/confui/ui_automation.h
@@ -9,6 +9,7 @@
 #include "mesh_connector.h"
 
 class CDAutomationsTabWidget;
+/** @brief widget that displays single automation */
 class CDAutomationWidget : public QWidget {
 	Q_OBJECT
 
diff --git a/confui/ui_node.h b/confui/ui_node.h
index 615921b..3aa16e5 100644
--- a/confui/ui_node.h
+++ b/confui/ui_node.h
@@ -9,6 +9,7 @@
 
 #include "mesh_connector.h"
 
+/** @brief widget that displays single node */
 class CDNodeWidget : public QWidget {
 	Q_OBJECT
 
@@ -25,8 +26,12 @@ private:
 public:
 	CDNodeWidget(QWidget *parent = nullptr);
 	virtual ~CDNodeWidget();
+	/** @brief update node info in GUI */
 	virtual void update();
+	/** @brief register which node this widget controls */
 	virtual void set_node(cd_uid_t id);
+	/** @brief join/remove from network */
 	virtual void toggle_provision();
+	/** @brief turn led on/off */
 	virtual void update_led(bool on);
 };
diff --git a/confui/ui_scroll_container.h b/confui/ui_scroll_container.h
index e731f6a..716b3c9 100644
--- a/confui/ui_scroll_container.h
+++ b/confui/ui_scroll_container.h
@@ -4,6 +4,7 @@
 #include <QWidget>
 #include <QVBoxLayout>
 
+/** @brief generic vertically scrolling layout */
 class CDScrollContainerLayout : public QVBoxLayout {
 	Q_OBJECT
 
@@ -16,7 +17,9 @@ private:
 public:
 	CDScrollContainerLayout(QWidget *parent = nullptr);
 	virtual ~CDScrollContainerLayout();
+	/** @brief add widget to layout */
 	virtual void addWidget(QWidget* widget);
+	/** @brief remove widget from layout */
 	virtual void removeWidget(QWidget* widget);
 };
 
diff --git a/confui/ui_tab_automations.h b/confui/ui_tab_automations.h
index ec34189..6a1f372 100644
--- a/confui/ui_tab_automations.h
+++ b/confui/ui_tab_automations.h
@@ -7,6 +7,7 @@
 #include "ui_scroll_container.h"
 
 class CDAddAutomationWidget;
+/** @brief automations tab content widget */
 class CDAutomationsTabWidget : public QWidget {
 	Q_OBJECT
 
@@ -21,5 +22,7 @@ public:
 	
 	CDAutomationsTabWidget(CDMainWindow *main_window = nullptr);
 	virtual ~CDAutomationsTabWidget();
+	/** @brief cascading ui update (add/remove/update automations in scrolling
+	 * view) */
 	virtual void update();
 };
diff --git a/confui/ui_tab_node_overview.h b/confui/ui_tab_node_overview.h
index d2197b1..dc4a951 100644
--- a/confui/ui_tab_node_overview.h
+++ b/confui/ui_tab_node_overview.h
@@ -6,6 +6,7 @@
 #include "ui_node.h"
 #include "ui_scroll_container.h"
 
+/** @brief node overview tab content widget */
 class CDNodeOverviewTabWidget : public QWidget {
 	Q_OBJECT
 
@@ -18,5 +19,6 @@ public:
 	
 	CDNodeOverviewTabWidget(CDMainWindow *main_window = nullptr);
 	virtual ~CDNodeOverviewTabWidget();
+	/** @brief cascading ui update (add/remove/update nodes in scrolling view) */
 	virtual void update();
 };