testing changes - mostly doxygen updates

Author: maureeungaro

actions/event/gEventAction.cc

@@ -1,4 +1,5 @@
 #include "gEventAction.h"
+#include "actions/gactionConventions.h"
 
 // geant4
 #include "G4EventManager.hh"
@@ -11,45 +12,66 @@ GEventAction::GEventAction(const std::shared_ptr<GOptions>& gopt, GRunAction* ru
     GBase(gopt, EVENTACTION_LOGGER),
     goptions(gopt),
     run_action(run_a) {
+    // Constructor: store shared config and a non-owning pointer to the run action for this thread.
     auto desc = "GEventAction " + std::to_string(G4Threading::G4GetThreadId());
     log->debug(CONSTRUCTOR, FUNCTION_NAME, desc);
 }
 
 void GEventAction::BeginOfEventAction([[maybe_unused]] const G4Event* event) {
+    // Begin-of-event hook: logs event id and thread id for tracing.
     int thread_id = G4Threading::G4GetThreadId();
     int eventID   = event->GetEventID();
 
     log->debug(CONSTRUCTOR, FUNCTION_NAME, " event id ", eventID, " in thread ", thread_id);
 }
 
 void GEventAction::EndOfEventAction([[maybe_unused]] const G4Event* event) {
+    // End-of-event hook: collect hit collections, digitize hits, and publish the event to streamers.
     G4HCofThisEvent* HCsThisEvent = event->GetHCofThisEvent();
     if (!HCsThisEvent) return;
+    if (!run_action) {
+        log->error(ERR_GRUNACTION_NOT_EXISTING, FUNCTION_NAME, " run_action is null - cannot access digitization routines or streamers.");
+    }
 
     int thread_id = G4Threading::G4GetThreadId();
     int eventID   = event->GetEventID();
 
+    // Create the event data container that will receive digitized data and truth information.
     auto gevent_header       = std::make_unique<GEventHeader>(goptions, eventID, thread_id);
     auto eventDataCollection = std::make_shared<GEventDataCollection>(goptions, std::move(gevent_header));
 
-    // looping over all collections
+    // Loop over all hit collections produced by sensitive detectors in this event.
     for (G4int hci = 0; hci < HCsThisEvent->GetNumberOfCollections(); hci++) {
         auto thisGHC = (GHitsCollection*)HCsThisEvent->GetHC(hci);
 
         if (thisGHC) {
             std::string hcSDName = thisGHC->GetSDname();
             auto        digi_map = run_action->get_digitization_routines_map();
+            if (!digi_map) {
+                log->error(ERR_GDIGIMAP_NOT_EXISTING, FUNCTION_NAME, " no digitization routines map available for collection ", hcSDName,
+                           " in thread ", thread_id);
+            }
 
             log->info(2, FUNCTION_NAME, " worker ", thread_id,
                       " for event number ", eventID,
                       " for collection number ", hci + 1,
                       " collection name: ", hcSDName);
 
-            auto digitization_routine = digi_map->at(hcSDName);
+            // Select the digitization routine by hit collection name, then publish through all streamers.
+            auto it = digi_map->find(hcSDName);
+            if (it == digi_map->end()) {
+                log->error(ERR_GDIGIMAP_NOT_EXISTING, FUNCTION_NAME, " no digitization routine registered for collection ", hcSDName,
+                           " in thread ", thread_id);
+            }
+            auto digitization_routine = it->second;
+
             auto gstreamers_map       = run_action->get_streamer_map();
+            if (!gstreamers_map) {
+                log->error(ERR_STREAMERMAP_NOT_EXISTING, FUNCTION_NAME, " no gstreamer map available in thread ", thread_id);
+            }
 
             if (digitization_routine != nullptr) {
-                // looping over hits in this collection
+                // Loop over hits in this collection and append produced data to the event container.
                 for (size_t hitIndex = 0; hitIndex < thisGHC->GetSize(); hitIndex++) {
                     auto thisHit = (GHit*)thisGHC->GetHit(hitIndex);
                     // PRAGMA TODO: switch these on/off with options
@@ -60,7 +82,7 @@ void GEventAction::EndOfEventAction([[maybe_unused]] const G4Event* event) {
                 }
 
                 for (const auto& [name, gstreamer] : *gstreamers_map) {
-                    // publish the event to the gstreamer
+                    // Publish the event to the gstreamer.
                     gstreamer->publishEventData(eventDataCollection);
                 }
             }

actions/event/gEventAction.h

@@ -7,24 +7,96 @@
 #include "gbase.h"
 #include "../run/gRunAction.h"
 
+/**
+ * @file gEventAction.h
+ * @brief Declares GEventAction, responsible for per-event lifecycle hooks and event publication.
+ *
+ * @ingroup gactions_module
+ */
+
 constexpr const char* EVENTACTION_LOGGER = "geventaction";
 
+/**
+ * @brief Namespace collecting helpers for the event action.
+ *
+ * @ingroup gactions_module
+ */
 namespace geventaction {
+/**
+ * @brief Returns the options associated with the event action.
+ *
+ * @return A GOptions instance for the event action logger scope.
+ */
 inline GOptions defineOptions() { return GOptions(EVENTACTION_LOGGER); }
-}
+} // namespace geventaction
+
 
-// Local thread classes
+/**
+ * @class GEventAction
+ * @brief Handles event begin/end callbacks and triggers digitization + streaming.
+ *
+ * Responsibilities:
+ * - At event begin: optionally log event/thread identification.
+ * - At event end:
+ *   - Retrieve the hit collections for the event.
+ *   - For each hit collection:
+ *     - Resolve the digitization routine associated with the collection name.
+ *     - Convert hits into digitized data and true-information data.
+ *     - Add these products to the event data container.
+ *   - Publish the completed event data to all configured streamers for the thread.
+ *
+ * Ownership:
+ * - The run_action pointer is non-owning; it is expected to remain valid for the
+ *   lifetime of the thread actions (it is created and registered by GAction).
+ *
+ * @ingroup gactions_module
+ */
 class GEventAction : public GBase<GEventAction>, public G4UserEventAction {
 public:
+	/**
+	 * @brief Constructs the event action.
+	 *
+	 * @param gopt Shared configuration used to construct event data containers and control logging.
+	 * @param run_a Non-owning pointer to the thread's GRunAction instance, used to access
+	 *              digitization routines and the streamer map.
+	 */
 	GEventAction(const std::shared_ptr<GOptions>& gopt, GRunAction* run_a);
 
+	/**
+	 * @brief Called by Geant4 at the beginning of an event.
+	 *
+	 * Typical usage in this module is logging and lightweight per-event bookkeeping.
+	 *
+	 * @param event The Geant4 event descriptor.
+	 */
 	void BeginOfEventAction(const G4Event* event) override;
+
+	/**
+	 * @brief Called by Geant4 at the end of an event.
+	 *
+	 * This method performs the event-level workflow:
+	 * - Collect hit collections.
+	 * - Digitize hits and collect truth information.
+	 * - Publish the resulting event data to streamers.
+	 *
+	 * @param event The Geant4 event descriptor.
+	 */
 	void EndOfEventAction(const G4Event* event) override;
 
 private:
-	std::shared_ptr<GOptions> goptions; // keeping the goption pointer to construct gdata
-	GRunAction* run_action; // non-owning, valid for the thread lifetime
+	/**
+	 * @brief Shared configuration used for constructing event products and controlling logging.
+	 */
+	std::shared_ptr<GOptions> goptions;
 
+	/**
+	 * @brief Non-owning pointer to the thread's run action.
+	 *
+	 * This is used to access:
+	 * - The digitization routines map (collection name -> routine).
+	 * - The per-thread streamer map.
+	 */
+	GRunAction* run_action;
 };
 
 
@@ -39,4 +111,4 @@ class GEventAction : public GBase<GEventAction>, public G4UserEventAction {
 // 			logSummary("Factory <" + factoryName + "> " + reportName + resultString);
 // 		}
 // 	}
-// }
+// }

actions/gaction.cc

@@ -12,13 +12,15 @@ GAction::GAction(std::shared_ptr<GOptions> gopts, std::shared_ptr<gdynamicdigiti
 
 
 void GAction::BuildForMaster() const {
+	// Master-thread registration: register the run action only.
 	log->debug(NORMAL, FUNCTION_NAME);
 
 	SetUserAction(new GRunAction(goptions, digitization_routines_map));
 }
 
 
 void GAction::Build() const {
+	// Worker-thread registration: primary generator, run action, then event action.
 	auto thread_id = G4Threading::G4GetThreadId();
 
 	log->debug(NORMAL, FUNCTION_NAME, "thread id: " + std::to_string(thread_id));

actions/gaction.h

@@ -14,22 +14,39 @@
 #include "run/gRun.h"
 #include "generator/gPrimaryGeneratorAction.h"
 
-// G4VUserActionInitialization is a newly introduced class for the user to instantiate
-// user action classes (both mandatory and optional).
-//
-// All the user action classes are thread-local and instantiated only for worker treads,
-// with the only exception of UserRunAction, which could be instantiated also for the master thread.
-// All user actions must be registered through SetUserAction() protected method defined in the
-// G4VUserActionInitialization base class.
-//
-// G4VUserActionInitialization has two virtual methods to be implemented:
-// - Build() should be used for defining user action classes for worker threads
-//   as well as for the sequential mode.
-// - BuildForMaster() should be used for defining only the UserRunAction for the master thread.
+/**
+ * @file gaction.h
+ * @brief Declares GAction, the Geant4 action-initialization entry point for GEMC.
+ *
+ * GAction derives from the Geant4 action initialization interface (\c G4VUserActionInitialization)
+ * and wires together the run, event, and primary generation actions used by GEMC.
+ *
+ * @ingroup gactions_module
+ */
 
 constexpr const char* GACTION_LOGGER = "gaction";
 
+/**
+ * @brief Namespace collecting helpers for the actions subsystem.
+ *
+ * @ingroup gactions_module
+ */
 namespace gaction {
+
+/**
+ * @brief Builds and returns the complete set of options required by the actions subsystem.
+ *
+ * This helper is intended to be used by the application/module setup to define all
+ * actions-related options in one place.
+ *
+ * It aggregates:
+ * - event action options
+ * - run action options
+ * - primary generator options
+ * - run container options
+ *
+ * @return A GOptions instance populated with the union of all action-related options.
+ */
 inline GOptions defineOptions() {
 	auto goptions = GOptions(GACTION_LOGGER);
 	goptions += geventaction::defineOptions();
@@ -38,21 +55,70 @@ inline GOptions defineOptions() {
 	goptions += grun::defineOptions();
 	return goptions;
 }
-}
+} // namespace gaction
 
 
+/**
+ * @class GAction
+ * @brief Registers GEMC user actions for worker and master threads.
+ *
+ * Geant4 uses an action initialization class (\c G4VUserActionInitialization) to instantiate
+ * user action objects. These action objects are typically thread-local:
+ *
+ * - Build() is invoked for worker threads and also for sequential mode.
+ * - BuildForMaster() is invoked for the master thread, and is commonly used to register
+ *   only the run action.
+ *
+ * This class holds:
+ * - A shared pointer to GOptions, used by the constructed actions to read runtime configuration.
+ * - A shared pointer to the digitization routines map, used by the run and event actions to
+ *   digitize hits and publish results.
+ *
+ * @ingroup gactions_module
+ */
 class GAction : public GBase<GAction>, public G4VUserActionInitialization {
 public:
+	/**
+	 * @brief Constructs the action initializer.
+	 *
+	 * @param gopts Shared configuration object used by all actions constructed by this initializer.
+	 * @param digi_map Shared map from sensitive detector / hit collection name to digitization routines.
+	 */
 	GAction(std::shared_ptr<GOptions> gopts, std::shared_ptr<gdynamicdigitization::dRoutinesMap> digi_map);
 
+	/**
+	 * @brief Registers user actions for worker threads (and sequential mode).
+	 *
+	 * Expected registrations include:
+	 * - The primary generator action.
+	 * - The run action.
+	 * - The event action.
+	 *
+	 * The constructed actions receive the shared configuration and digitization map.
+	 */
 	void Build() const override;
 
+	/**
+	 * @brief Registers user actions for the master thread.
+	 *
+	 * In multithreaded mode, the master thread typically registers only the run action.
+	 */
 	void BuildForMaster() const override;
 
 private:
-	std::shared_ptr<GOptions> goptions; // keeping the goption pointer to construct the other actions
+	/**
+	 * @brief Shared configuration used to construct and configure all action objects.
+	 *
+	 * This pointer is kept so that Build() and BuildForMaster() can construct the action objects
+	 * using the same configuration instance.
+	 */
+	std::shared_ptr<GOptions> goptions;
 
-	// digitization map, populated in ConstructSDandField
+	/**
+	 * @brief Digitization routines map used by run/event actions to digitize hit collections.
+	 *
+	 * The map is populated elsewhere (e.g., during sensitive detector and field construction)
+	 * and is shared across threads as a read-mostly structure.
+	 */
 	std::shared_ptr<gdynamicdigitization::dRoutinesMap> digitization_routines_map;
-
 };

actions/gactionConventions.h

@@ -0,0 +1,12 @@
+/**
+* \name Error codes
+ * \brief Module-level exit/status codes.
+ *
+ * Values are in the 200s range and are used by the logger error path to provide
+ * stable identifiers for common failure modes.
+ */
+///@{
+#define ERR_GRUNACTION_NOT_EXISTING 1201
+#define ERR_GDIGIMAP_NOT_EXISTING 1202
+#define ERR_STREAMERMAP_NOT_EXISTING 1203
+///@}