Tidying

src/Application.hpp

@@ -22,6 +22,12 @@ namespace Bloom
 {
     using namespace DebugServers;
 
+    /**
+     * Bloom - a debug interface for embedded systems development on Linux.
+     *
+     * This is the main entry-point of execution for the Bloom program. The methods within will run on the main
+     * thread. If Insight is enabled, execution will be passed over to Insight::run() upon startup.
+     */
     class Application: public Thread
     {
     public:
@@ -38,25 +44,65 @@ namespace Bloom
         EventManager eventManager = EventManager();
         EventListenerPointer applicationEventListener = std::make_shared<EventListener>("ApplicationEventListener");
 
+        /**
+         * The SignalHandler deals with any UNIX signals. It runs on a dedicated thread. All other threads
+         * ignore UNIX signals.
+         *
+         * See the SignalHandler class for more on this.
+         */
         SignalHandler signalHandler = SignalHandler(this->eventManager);
         std::thread signalHandlerThread;
 
+        /**
+         * The TargetController possesses full control of the connect debug tool and target. It runs on a
+         * dedicated thread.
+         *
+         * See the TargetController class for more on this.
+         */
         TargetController targetController = TargetController(this->eventManager);
         std::thread targetControllerThread;
 
+        /**
+         * The DebugServer exposes an interface to the connected target, to third-party software such as IDEs. It runs
+         * on a dedicated thread.
+         *
+         * See the DebugServer and GdbRspDebugServer class for more on this.
+         */
         std::unique_ptr<DebugServer> debugServer = nullptr;
         std::thread debugServerThread;
 
+        /**
+         * Insight is, effectively, a small Qt application that serves a GUI to the user. It occupies the main thread,
+         * as well as a single worker thread, and possibly other threads created by Qt.
+         *
+         * When the user closes the Insight GUI, control of the main thread is returned to Application::run(). How we
+         * deal with the GUI being closed at this point depends on user configuration.
+         *
+         * See the Insight class for more on this.
+         */
         Insight insight = Insight(this->eventManager);
 
+        /**
+         * Configuration extracted from the user's project configuration file.
+         *
+         * See ApplicationConfig.hpp for more on this.
+         */
         ApplicationConfig applicationConfig;
         EnvironmentConfig environmentConfig;
         DebugServerConfig debugServerConfig;
         InsightConfig insightConfig;
-
         std::optional<std::string> selectedEnvironmentName;
 
-        auto getCommandToCallbackMapping() {
+        /**
+         * Some CLI arguments are interpreted as commands and thus require specific handler methods to be called.
+         * This mapping maps command strings to the appropriate handler methods. The mapped handler method is invoked
+         * when the command is provided as an argument from the CLI.
+         *
+         * See Application::run() for more on this.
+         *
+         * @return
+         */
+        auto getCommandToHandlerMapping() {
             return std::map<std::string, std::function<int()>> {
                 {
                     "--help",
@@ -135,13 +181,27 @@ namespace Bloom
          */
         void stopTargetController();
 
+        /**
+         * Prepares a dedicated thread for the DebugServer and kicks it off with a call to DebugServer::run().
+         */
         void startDebugServer();
 
+        /**
+         * Sends a shutdown request to the DebugServer thread and waits on it to exit.
+         */
         void stopDebugServer();
 
     public:
         explicit Application() = default;
 
+        /**
+         * This mapping is used to map debug server names from project configuration files to polymorphic instances of
+         * the DebugServer class.
+         *
+         * See Application::startDebugServer() for more on this.
+         *
+         * @return
+         */
         auto getSupportedDebugServers() {
             return std::map<std::string, std::function<std::unique_ptr<DebugServer>()>> {
                 {
@@ -153,10 +213,34 @@ namespace Bloom
             };
         };
 
+        /**
+         * Main entry-point for the Bloom program.
+         *
+         * @param arguments
+         *  A vector of string arguments passed from the user via the cli.
+         *
+         * @return
+         */
         int run(const std::vector<std::string>& arguments);
 
+        /**
+         * If the TargetController unexpectedly shuts down, the rest of the application will follow.
+         *
+         * @param event
+         */
         void handleTargetControllerStateChangedEvent(EventPointer<Events::TargetControllerStateChanged> event);
+
+        /**
+         * Same goes for the DebugServer - it should never shutdown unless a shutdown request was issued. If it does,
+         * something horrible has happened and so we shutdown the rest of the application in response.
+         *
+         * @param event
+         */
         void onDebugServerStateChanged(EventPointer<Events::DebugServerStateChanged> event);
+
+        /**
+         * Triggers a shutdown of Bloom and all of its components.
+         */
         void handleShutdownApplicationEvent(EventPointer<Events::ShutdownApplication>);
 
         /**