Client doxygen

Add documentation to the client

client/helpers.hpp

@@ -9,10 +9,50 @@
 #include <qwt_slider.h>
 #include <qwt_thermo.h>
 
+/**
+ * @brief Helper to create a dial needle
+ *
+ * @param dial The dial to create the needle for
+ */
 void create_dial_needle(QwtDial *dial);
 
+/**
+ * @brief Set the widget color object
+ *
+ * @param widget The widget to set the color for
+ * @param color The color to set
+ * @param bg The background color to set
+ */
 void set_widget_color(QWidget *widget, QColor color, QColor bg);
+
+/**
+ * @brief Set the widget color object
+ *
+ * @param widget The widget to set the color for
+ * @param color The color to set
+ * @param bg The background color to set
+ */
 void set_widget_color(QWidget *widget, QString color, QString bg);
+
+/**
+ * @brief Get the widget background color
+ *
+ * @param widget The widget to get the background color for
+ * @return QColor The background color
+ */
 QColor widget_bg_color(QWidget *widget);
+
+/**
+ * @brief Get the widget color
+ *
+ * @param widget The widget to get the color for
+ * @return QColor The color
+ */
 QColor widget_color(QWidget *widget);
+
+/**
+ * @brief Reset the widget color to default
+ *
+ * @param widget The widget to reset the color for
+ */
 void reset_widget_color(QWidget *widget);

client/mainwindow.cpp

@@ -56,8 +56,9 @@ MainWindow::~MainWindow()
     delete ui;
 }
 
-void MainWindow::setup_cb(void)
+void MainWindow::showEvent(QShowEvent *event)
 {
+    QWidget::showEvent(event);
     connect(m_web_socket.get(), &Web_socket_wrapper::on_command_cb, this, [=, this](json &j) { on_cmd_cb(j); });
     connect(m_web_socket.get(), &Web_socket_wrapper::on_connected, this,
             [=, this] { m_web_socket->send_command(Web_socket_wrapper::Command::get_simulators); });
@@ -67,12 +68,6 @@ void MainWindow::setup_cb(void)
     });
 }
 
-void MainWindow::showEvent(QShowEvent *event)
-{
-    QWidget::showEvent(event);
-    setup_cb();
-}
-
 void MainWindow::hideEvent(QHideEvent *event)
 {
     QWidget::hideEvent(event);

client/mainwindow.hpp

@@ -22,20 +22,67 @@ class MainWindow : public QMainWindow
     Q_OBJECT
 
   public:
+    /**
+     * @brief Construct a new Main Window object
+     *
+     * @param ws_url The WebSocket URL
+     * @param sim The default simulator name
+     * @param parent The parent widget
+     */
     explicit MainWindow(QUrl ws_url, QString sim, QWidget *parent = nullptr);
     ~MainWindow();
 
   private:
+    /**
+     * @brief Handle the show event
+     *        And will connect the WebSocket signals
+     *
+     * @param event
+     */
     void showEvent(QShowEvent *event) override;
+    /**
+     * @brief Handle the hide event
+     *        And will disconnect the WebSocket signals
+     *
+     * @param event
+     */
     void hideEvent(QHideEvent *event) override;
 
+    /**
+     * @brief Set the default simulator only possible on construction
+     *
+     * @param name The simulator name
+     */
     void default_sim(QString name);
+    /**
+     * @brief Parse the simulator names from JSON and add them to the combo box
+     *
+     * @param sims The JSON array of simulator names
+     */
     void pase_sim_names(json &sims);
+    /**
+     * @brief Open the simulator window using the selected simulator
+     */
     void open_sim_window(void);
+    /**
+     * @brief Open a simulator by name
+     *
+     * @param sim_name The simulator name
+     */
     void check_active_sim(QString name);
+    /**
+     * @brief Open a simulator by name
+     *        Used when using the default simulator
+     *
+     * @param sim_name
+     */
     void open_sim(QString sim_name);
-    void setup_cb(void);
 
+    /**
+     * @brief Handle command callbacks from the server
+     *
+     * @param j The JSON command
+     */
     void on_cmd_cb(json &j);
 
     bool m_default_sim = false;

client/ui_base.hpp

@@ -22,10 +22,34 @@ class UI_base : public QMainWindow
 {
     Q_OBJECT
   public:
+    /**
+     * @brief Construct a new ui base object
+     *
+     * @param name The name of the simulator
+     * @param api The weboscket connection to the server API
+     * @param parent The parent widget
+     */
     explicit UI_base(QString name, Web_socket_wrapper *api, QWidget *parent = nullptr);
-    void sim_update(void);
+    /**
+     * @brief Get the name of the simulator
+     *
+     * @return QString The name of the simulator
+     */
     QString name() const;
+    /**
+     * @brief Get the UI element by its ID
+     *
+     * @param id The ID of the UI element
+     * @return QWidget* The UI element
+     */
     QWidget *id_to_ui(size_t id);
+    /**
+     * @brief Get the label associated with a widget
+     *        This function has to be overridden in derived classes if labels are used
+     *
+     * @param widget The widget
+     * @return QLabel* The associated label, or nullptr if none
+     */
     virtual QLabel *id_to_label(QWidget *widget)
     {
         Q_UNUSED(widget);
@@ -33,46 +57,259 @@ class UI_base : public QMainWindow
     }
 
   protected:
+    /**
+     * @brief Handle an event callback from the server
+     *
+     * @param j The JSON event
+     */
     void on_event_cb(json &j);
+    /**
+     * @brief Handle a command callback from the server
+     *
+     * @param j The JSON command
+     */
     void on_cmd_cb(json &j);
 
+    /**
+     * @brief Push a UI item to the internal list and setup its connections
+     *        The item have to be in the same order as from the server
+     *
+     * @param item The UI item to push
+     */
     void push_ui_item(QWidget *item);
 
+    /**
+     * @brief Parse UI items from JSON and update the UI accordingly
+     *
+     * @param input The JSON input containing UI items
+     */
     void UI_item_parser(json &input);
-    virtual void process_ui_label(json &ui_item, QWidget *widget);
+    /**
-    virtual void process_ui_slider(json &ui_item, QWidget *widget);
+     * @brief Process a label UI item
-    virtual void process_ui_dial(json &ui_item, QWidget *widget);
+     *
-    virtual void process_ui_thermo(json &ui_item, QWidget *widget);
+     * @param ui_item The JSON UI item
-    virtual void process_ui_textbox(json &ui_item, QWidget *widget);
+     * @param widget The associated widget
-    virtual void process_ui_combobox(json &ui_item, QWidget *widget);
+     */
-    virtual void process_ui_radiobutton(json &ui_item, QWidget *widget);
+    void process_ui_label(json &ui_item, QWidget *widget);
-    virtual void process_ui_checkbox(json &ui_item, QWidget *widget);
+    /**
-    virtual void process_ui_button(json &ui_item, QWidget *widget);
+     * @brief Process a slider UI item
-    virtual void process_ui_led(json &ui_item, QWidget *widget);
+     *
-    virtual void process_ui_spinbox(json &ui_item, QWidget *widget);
+     * @param ui_item The JSON UI item
-    virtual void process_ui_double_spinbox(json &ui_item, QWidget *widget);
+     * @param widget The associated widget
-    virtual void process_ui_hex_spinbox(json &ui_item, QWidget *widget);
+     */
-    virtual void process_ui_tab_widget(json &ui_item, QWidget *widget);
+    void process_ui_slider(json &ui_item, QWidget *widget);
-    virtual void process_ui_stacked_widget(json &ui_item, QWidget *widget);
+    /**
-    virtual void process_ui_status_bar(json &ui_item, QWidget *widget);
+     * @brief Process a dial UI item
-    virtual void process_ui_plot(json &ui_item, QWidget *widget);
+     *
-    virtual void process_ui_table(json &ui_item, QWidget *widget);
+     * @param ui_item The JSON UI item
-    virtual void process_ui_can(json &ui_item, QWidget *widget);
+     * @param widget The associated widget
+     */
+    void process_ui_dial(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a thermo UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_thermo(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a textbox UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_textbox(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a combobox UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_combobox(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a radiobutton UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_radiobutton(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a checkbox UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_checkbox(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a button UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_button(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a LED UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_led(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a spinbox UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_spinbox(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a double spinbox UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_double_spinbox(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a hex spinbox UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_hex_spinbox(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a tab widget UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_tab_widget(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a stacked widget UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_stacked_widget(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a status bar UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_status_bar(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a plot UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_plot(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a table UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_table(json &ui_item, QWidget *widget);
+    /**
+     * @brief Process a CAN UI item
+     *
+     * @param ui_item The JSON UI item
+     * @param widget The associated widget
+     */
+    void process_ui_can(json &ui_item, QWidget *widget);
 
+    /**
+     * @brief Setup a generic UI item
+     *
+     * @param item The UI item
+     * @param index The index of the UI item
+     */
     void setup_ui_item(QWidget *item, size_t index);
+    /**
+     * @brief Setup a button UI item
+     *
+     * @param item The UI item
+     * @param index The index of the UI item
+     */
     void setup_button(QWidget *item, size_t index);
+    /**
+     * @brief Set the up combobox object
+     *
+     * @param item The UI item
+     * @param index The index of the UI item
+     */
     void setup_combobox(QWidget *item, size_t index);
+    /**
+     * @brief Set the up checkbox object
+     *
+     * @param item The UI item
+     * @param index The index of the UI item
+     */
     void setup_checkbox(QWidget *item, size_t index);
+    /**
+     * @brief Set the up dial object
+     *
+     * @param item The UI item
+     * @param index The index of the UI item
+     */
     void setup_dial(QWidget *item, size_t index);
+    /**
+     * @brief Set the up slider object
+     *
+     * @param item The UI item
+     * @param index The index of the UI item
+     */
     void setup_slider(QWidget *item, size_t index);
+    /**
+     * @brief Set the up spinbox object
+     *
+     * @param item The UI item
+     * @param index The index of the UI item
+     */
     void setup_spinbox(QWidget *item, size_t index);
+    /**
+     * @brief Set the up double spinbox object
+     *
+     * @param item The UI item
+     * @param index The index of the UI item
+     */
     void setup_double_spinbox(QWidget *item, size_t index);
+    /**
+     * @brief Set the up hex spinbox object
+     *
+     * @param item The UI item
+     * @param index The index of the UI item
+     */
     void setup_hex_spinbox(QWidget *item, size_t index);
+    /**
+     * @brief Set the up tab widget object
+     *
+     * @param item The UI item
+     * @param index The index of the UI item
+     */
     void setup_tab_widget(QWidget *item, size_t index);
+    /**
+     * @brief Set the up CAN UI object
+     *
+     * @param item The UI item
+     * @param index The index of the UI item
+     */
     void setup_can_ui(QWidget *item, size_t index);
 
-    void showEvent(QShowEvent *event);
+    /**
-    void closeEvent(QCloseEvent *event);
+     * @brief Handle the show event
+     *        And will connect the WebSocket signals
+     *
+     * @param event
+     */
+    void showEvent(QShowEvent *event) override;
+    /**
+     * @brief Handle the close event
+     *        And will disconnect the WebSocket signals
+     *
+     * @param event
+     */
+    void closeEvent(QCloseEvent *event) override;
 
   private:
     Web_socket_wrapper *m_web_socket;

client/web_socket_wrapper.hpp

@@ -34,28 +34,127 @@ class Web_socket_wrapper : public QObject
     };
 
   public:
+    /**
+     * @brief Construct a new Web_socket_wrapper object
+     *
+     * @param url The WebSocket URL to connect to
+     * @param parent The parent QObject
+     */
     explicit Web_socket_wrapper(const QUrl &url, QObject *parent = nullptr);
 
+    /**
+     * @brief Send a command to the server
+     *
+     * @param c The command to send
+     * @param id The ID associated with the command (if applicable)
+     */
     void send_command(Command c, size_t id = 0);
+    /**
+     * @brief Send a command to the server with a string value
+     *
+     * @param c The command to send
+     * @param val The string value associated with the command
+     */
     void send_command(Command c, QString val);
+
+    /**
+     * @brief Send an event to the server
+     *
+     * @param e The event to send
+     * @param id The ID associated with the event
+     */
     void send_event(Event e, size_t id);
+    /**
+     * @brief Send an event to the server with a size_t value
+     *
+     * @param e The event to send
+     * @param id The ID associated with the event
+     * @param val The size_t value associated with the event
+     */
     void send_event(Event e, size_t id, size_t val);
+    /**
+     * @brief Send an event to the server with a double value
+     *
+     * @param e The event to send
+     * @param id The ID associated with the event
+     * @param val The double value associated with the event
+     */
     void send_event(Event e, size_t id, double val);
+    /**
+     * @brief Send an event to the server with a string value
+     *
+     * @param e The event to send
+     * @param id The ID associated with the event
+     * @param val The string value associated with the event
+     */
     void send_event(Event e, size_t id, QString val);
+    /**
+     * @brief Send a CAN event to the server
+     *
+     * @param e The event to send
+     * @param id The ID associated with the event
+     * @param sid The CAN standard identifier
+     * @param dlc The CAN data length code
+     * @param payload The CAN data payload
+     */
     void send_event(Event e, size_t id, uint32_t sid, uint8_t dlc, std::array<uint8_t, 8> payload);
+    /**
+     * @brief Close the WebSocket connection
+     *
+     */
     void close();
+    /**
+     * @brief Inhibit or allow sending events to the server
+     *
+     * @param inhibit True to inhibit events, false to allow
+     */
     void inhibit_events(bool inhibit);
 
   Q_SIGNALS:
+    /**
+     * @brief Signal emitted when the WebSocket is connected
+     *
+     */
     void on_connected();
+    /**
+     * @brief Signal emitted when the WebSocket is closed
+     *
+     */
     void on_closed();
+    /**
+     * @brief Signal emitted when a command is received from the server
+     *
+     * @param data The JSON command data
+     */
     void on_command_cb(json &data);
+    /**
+     * @brief Signal emitted when an event is received from the server
+     *
+     * @param data The JSON event data
+     */
     void on_event_cb(json &data);
 
   private Q_SLOTS:
+    /**
+     * @brief Internal slot for handling WebSocket connection established
+     *
+     */
     void m_on_connected();
+    /**
+     * @brief Internal slot for handling WebSocket disconnection
+     *
+     */
     void m_on_received(QString message);
+    /**
+     * @brief Internal slot for handling pong responses
+     *
+     * @param elapsedTime The elapsed time since the ping was sent
+     */
     void m_on_pong(quint64 elapsedTime);
+    /**
+     * @brief Internal slot for handling pong timeouts
+     *
+     */
     void m_on_pong_timeout();
 
   private: