Tidying

src/TargetController/TargetController.hpp

@@ -39,13 +39,27 @@ namespace Bloom
         ApplicationConfig applicationConfig;
         EnvironmentConfig environmentConfig;
 
+        /**
+         * The TargetController should be the sole owner of the target and debugTool. They are constructed and
+         * destroyed within the TargetController. Under no circumstance should ownership of these resources be
+         * transferred to any other component within Bloom.
+         */
         std::unique_ptr<Targets::Target> target = nullptr;
         std::unique_ptr<DebugTool> debugTool = nullptr;
 
         EventManager& eventManager;
         EventListenerPointer eventListener = std::make_shared<EventListener>("TargetControllerEventListener");
 
+        /**
+         * We keep record of the last known execution state of the target. When the connected target reports a
+         * different state to what's stored in lastTargetState, a state change (TargetExecutionStopped/TargetExecutionResumed)
+         * event is emitted.
+         */
         TargetState lastTargetState = TargetState::UNKNOWN;
+
+        /**
+         * Obtaining a TargetDescriptor for the connected target can be quite expensive. We cache it here.
+         */
         std::optional<TargetDescriptor> cachedTargetDescriptor;
 
         /**
@@ -168,9 +182,15 @@ namespace Bloom
          */
         void fireTargetEvents();
 
+        /**
+         * When the TargetController fails to handle an event, a TargetControllerErrorOccurred event is emitted, with
+         * a correlation ID matching the ID of the event that triggered the handler.
+         *
+         * @param correlationId
+         */
         void emitErrorEvent(int correlationId);
     public:
-        TargetController(EventManager& eventManager) : eventManager(eventManager) {};
+        TargetController(EventManager& eventManager): eventManager(eventManager) {};
 
         void setApplicationConfig(const ApplicationConfig& applicationConfig) {
             this->applicationConfig = applicationConfig;
@@ -185,38 +205,128 @@ namespace Bloom
          */
         void run();
 
+        /**
+         * Obtains a TargetDescriptor from the target and includes it in a TargetDescriptorExtracted event.
+         *
+         * @param event
+         */
         void onExtractTargetDescriptor(EventPointer<Events::ExtractTargetDescriptor> event);
 
         /**
-         * Callback for StopTargetExecution event.
+         * Will attempt to stop execution on the target and emit a TargetExecutionStopped event.
          *
-         * Will attempt to stop the target and emit a TargetExecutionStopped event.
+         * @param event
          */
         void onStopTargetExecutionEvent(EventPointer<Events::StopTargetExecution> event);
 
+        /**
+         * Will attempt to step execution on the target and emit a TargetExecutionResumed event.
+         *
+         * @param event
+         */
         void onStepTargetExecutionEvent(EventPointer<Events::StepTargetExecution> event);
 
         /**
-         * Callback for ResumeTargetExecution event.
+         * Will attempt to resume execution on the target and emit a TargetExecutionResumed event.
+         *
+         * @param event
          */
         void onResumeTargetExecutionEvent(EventPointer<Events::ResumeTargetExecution> event);
 
         /**
-         * Callback for ShutdownTargetController event.
+         * Invokes a shutdown.
+         *
+         * @param event
          */
         void onShutdownTargetControllerEvent(EventPointer<Events::ShutdownTargetController> event);
 
+        /**
+         * Will attempt to read the requested registers and emit a RegistersRetrievedFromTarget event.
+         *
+         * @param event
+         */
         void onReadRegistersEvent(EventPointer<Events::RetrieveRegistersFromTarget> event);
+
+        /**
+         * Will attempt to write the specified register values and emit a RegistersWrittenToTarget event.
+         *
+         * @param event
+         */
         void onWriteRegistersEvent(EventPointer<Events::WriteRegistersToTarget> event);
+
+        /**
+         * Will attempt to read memory from the target and include the data in a MemoryRetrievedFromTarget event.
+         *
+         * @param event
+         */
         void onReadMemoryEvent(EventPointer<Events::RetrieveMemoryFromTarget> event);
+
+        /**
+         * Will attempt to write memory to the target. On success, a MemoryWrittenToTarget event is emitted.
+         *
+         * @param event
+         */
         void onWriteMemoryEvent(EventPointer<Events::WriteMemoryToTarget> event);
+
+        /**
+         * Will attempt to set the specific breakpoint on the target. On success, the BreakpointSetOnTarget event will
+         * be emitted.
+         *
+         * @param event
+         */
         void onSetBreakpointEvent(EventPointer<Events::SetBreakpointOnTarget> event);
+
+        /**
+         * Will attempt to remove a breakpoint at the specified address, on the target. On success, the
+         * BreakpointRemovedOnTarget event is emitted.
+         *
+         * @param event
+         */
         void onRemoveBreakpointEvent(EventPointer<Events::RemoveBreakpointOnTarget> event);
+
+        /**
+         * Will hold the target stopped at it's current state.
+         *
+         * @param event
+         */
         void onDebugSessionStartedEvent(EventPointer<Events::DebugSessionStarted> event);
+
+        /**
+         * Will simply kick off execution on the target.
+         *
+         * @param event
+         */
         void onDebugSessionFinishedEvent(EventPointer<Events::DebugSessionFinished> event);
+
+        /**
+         * Will update the program counter value on the target. On success, a ProgramCounterSetOnTarget event is
+         * emitted.
+         *
+         * @param event
+         */
         void onSetProgramCounterEvent(EventPointer<Events::SetProgramCounterOnTarget> event);
+
+        /**
+         * Will automatically fire a target state update event.
+         * @TODO: get rid of this - Insight should request this itself.
+         *
+         * @param event
+         */
         void onInsightStateChangedEvent(EventPointer<Events::InsightStateChanged> event);
+
+        /**
+         * Will attempt to obtain the pin states from the target. Will emit a TargetPinStatesRetrieved event on success.
+         *
+         * @param event
+         */
         void onRetrieveTargetPinStatesEvent(EventPointer<Events::RetrieveTargetPinStates> event);
+
+        /**
+         * Will update a pin state for a particular pin. Will emit a TargetPinStatesRetrieved with the new pin
+         * state, on success.
+         *
+         * @param event
+         */
         void onSetPinStateEvent(EventPointer<Events::SetTargetPinState> event);
     };
 }