updated doxygen for gdata

Author: maureeungaro

gdata/event/gEventDataCollection.cc

@@ -1,32 +1,47 @@
 /**
-* \file gEventDataCollection.cc
- * \brief Implementation of the GEventDataCollection class.
+ * \file gEventDataCollection.cc
+ * \brief Implementation of the \ref GEventDataCollection class.
  *
  * \details
- * Event collections own per-hit objects for each sensitive detector and provide
- * a simple API to append hit data during event processing.
+ * An event collection owns per-hit objects for each sensitive detector and provides
+ * the append API used during event processing.
+ *
+ * Key behaviors:
+ * - Detector entries are created on demand when first referenced by name.
+ * - Hit objects are owned via \c std::unique_ptr and are moved into the collection.
+ * - The class does not enforce policies such as "truth and digitized hit counts must match";
+ *   such validation is typically performed by upstream logic or examples/tests.
  */
 
 #include "gEventDataCollection.h"
 
 /// Counter used by examples/tests (not currently used in create()).
+///
+/// \details
+/// This exists as a convenience hook for potential future example factories.
+/// Current example behavior uses \ref GEventHeader::create() as the event counter.
 std::atomic<int> GEventDataCollection::globalEventDataCollectionCounter{1};
 
 /// Counter used by \ref GEventHeader::create() to generate unique event numbers in examples/tests.
 std::atomic<int> GEventHeader::globalEventHeaderCounter{1};
 
 void GEventDataCollection::addDetectorTrueInfoData(const std::string& sdName, std::unique_ptr<GTrueInfoData> data) {
 	// Create detector entry if it does not exist.
+	//
+	// This makes the API robust for detectors appearing only in certain events.
 	if (gdataCollectionMap.find(sdName) == gdataCollectionMap.end()) {
 		gdataCollectionMap[sdName] = std::make_unique<GDataCollection>();
 	}
 
 	// Event-level: store a new hit entry (ownership transferred).
+	//
+	// After std::move(data), the caller relinquishes ownership and should not use 'data'.
 	gdataCollectionMap[sdName]->addTrueInfoData(std::move(data));
 	log->info(2, "GEventDataCollection: added new detector TrueInfoData for ", sdName);
 }
 
 void GEventDataCollection::addDetectorDigitizedData(const std::string& sdName, std::unique_ptr<GDigitizedData> data) {
+	// Ensure the per-detector container exists.
 	if (gdataCollectionMap.find(sdName) == gdataCollectionMap.end()) {
 		gdataCollectionMap[sdName] = std::make_unique<GDataCollection>();
 	}

gdata/event/gEventDataCollection.h

@@ -14,13 +14,20 @@
  *                                    - vector<unique_ptr<GDigitizedData>>
  * \endcode
  *
- * Event-level semantics:
- * - each call to addDetectorTrueInfoData/addDetectorDigitizedData appends one hit entry
- *   to the detector’s vectors.
+ * ## Event-level semantics
+ * - each call to \ref GEventDataCollection::addDetectorTrueInfoData() or \ref GEventDataCollection::addDetectorDigitizedData()
+ *   appends one hit entry to the specified detector’s vectors.
+ * - the detector entry is created on demand if it does not already exist.
  *
- * Ownership:
+ * ## Ownership
  * - The event collection owns all hit entries via \c std::unique_ptr.
- * - The caller transfers ownership when adding data.
+ * - The caller transfers ownership when adding data (via \c std::move).
+ *
+ * ## Intended usage
+ * A typical event loop will:
+ * - create one \ref GEventDataCollection per event
+ * - for each hit produced by simulation/digitization, push truth/digitized records into the event container
+ * - pass the finished event container downstream (output, run integration, analysis, etc.)
  */
 
 #include "gEventHeader.h"
@@ -36,10 +43,13 @@ namespace gevent_data {
 /**
  * \brief Aggregated options for event-level data collection.
  *
+ * \details
  * Combines options from:
  * - event header
  * - true/digitized data
  * - touchable (for identity creation in examples)
+ *
+ * This provides a single "options bundle" for event-level examples/applications.
  */
 inline auto defineOptions() -> GOptions {
 	auto goptions = GOptions(GEVENTDATA_LOGGER);
@@ -51,12 +61,28 @@ inline auto defineOptions() -> GOptions {
 }
 } // namespace gevent_data
 
+/**
+ * \brief Event container that owns per-detector hit data for one event.
+ *
+ * \details
+ * The container is built around a map from sensitive detector name to \ref GDataCollection.
+ * Each detector collection stores per-hit truth and digitized objects.
+ *
+ * The header (\ref GEventHeader) stores identifying metadata such as:
+ * - local event number
+ * - thread ID label
+ * - timestamp string
+ */
 class GEventDataCollection : public GBase<GEventDataCollection>
 {
 public:
 	/**
 	 * \brief Construct an event data collection with an owned header.
 	 *
+	 * \details
+	 * Ownership:
+	 * - \p header is moved into this object and is owned exclusively.
+	 *
 	 * \param gopts   Shared options object used to configure logging and behavior.
 	 * \param header  Owned event header.
 	 */
@@ -67,7 +93,9 @@ class GEventDataCollection : public GBase<GEventDataCollection>
 	/**
 	 * \brief Append one true-hit entry to the specified detector.
 	 *
-	 * If the detector name is new, the internal per-detector \ref GDataCollection is created.
+	 * \details
+	 * - If \p sdName is new, a per-detector \ref GDataCollection is created automatically.
+	 * - Ownership of \p data is transferred to this event container.
 	 *
 	 * \param sdName Sensitive detector name (map key).
 	 * \param data   True-hit object; ownership is transferred to this collection.
@@ -77,6 +105,10 @@ class GEventDataCollection : public GBase<GEventDataCollection>
 	/**
 	 * \brief Append one digitized-hit entry to the specified detector.
 	 *
+	 * \details
+	 * - If \p sdName is new, a per-detector \ref GDataCollection is created automatically.
+	 * - Ownership of \p data is transferred to this event container.
+	 *
 	 * \param sdName Sensitive detector name (map key).
 	 * \param data   Digitized-hit object; ownership is transferred to this collection.
 	 */
@@ -91,6 +123,7 @@ class GEventDataCollection : public GBase<GEventDataCollection>
 	/**
 	 * \brief Access the per-detector map for this event.
 	 *
+	 * \details
 	 * Key: sensitive detector name.
 	 * Value: per-detector \ref GDataCollection containing per-hit entries.
 	 *
@@ -109,11 +142,14 @@ class GEventDataCollection : public GBase<GEventDataCollection>
 	/**
 	 * \brief Test/example factory: create an event collection with one dummy hit for "ctof".
 	 *
-	 * This method supports examples/tests. It:
+	 * \details
+	 * This method exists to support examples/tests. It:
 	 * - creates a new \ref GEventHeader
 	 * - constructs an event data collection
 	 * - inserts one \ref GDigitizedData and one \ref GTrueInfoData entry under detector "ctof"
 	 *
+	 * This provides a minimal "event contains something" baseline for examples.
+	 *
 	 * \param gopts Shared options.
 	 * \return Shared pointer to the created event data collection.
 	 */

gdata/event/gEventHeader.h

@@ -18,27 +18,47 @@
  * - a timestamp string (\c timeStamp)
  *
  * In production GEMC/Geant4, event number and thread ID would typically come from Geant4
- * (e.g. G4Event and G4Threading). In this library, \ref GEventHeader::create() provides a deterministic
- * generator for examples and tests.
+ * (e.g. G4Event and G4Threading). In this library, \ref GEventHeader::create() provides a
+ * deterministic generator for examples and tests.
+ *
+ * \note Time stamp is generated using the local system time at construction.
  */
 
 constexpr const char* GDATAEVENTHEADER_LOGGER = "event_header";
 
 namespace geventheader {
 /**
- * \brief Defines GOptions for the event-header logger domain.
+ * \brief Defines \ref GOptions for the event-header logger domain.
+ *
+ * \details
+ * Event header logging can be enabled/controlled by including this in composite option bundles.
  */
 inline GOptions defineOptions() {
 	auto goptions = GOptions(GDATAEVENTHEADER_LOGGER);
 	return goptions;
 }
 } // namespace geventheader
 
+/**
+ * \brief Minimal event metadata header: event number, thread id, and timestamp.
+ *
+ * \details
+ * This object is typically owned by \ref GEventDataCollection as a \c std::unique_ptr.
+ *
+ * It is primarily used for:
+ * - labeling events in logs/output
+ * - reproducing the event/thread provenance for debugging
+ */
 class GEventHeader : public GBase<GEventHeader> {
 public:
 	/**
 	 * \brief Construct an event header with explicit values.
 	 *
+	 * \details
+	 * The constructor:
+	 * - assigns \c timeStamp based on local time
+	 * - emits an informational log summarizing the header values
+	 *
 	 * \param gopts Shared options object used to configure logging and behavior.
 	 * \param n     Local event number.
 	 * \param tid   Thread ID associated with this event.
@@ -56,9 +76,13 @@ class GEventHeader : public GBase<GEventHeader> {
 	/**
 	 * \brief Factory method used by examples/tests to create a header with a unique event number.
 	 *
+	 * \details
 	 * If \p tid is negative, a default thread ID is derived from the event number
 	 * (currently mod 8) to mimic multi-threaded execution.
 	 *
+	 * Threading notes:
+	 * - Uses an atomic counter so that concurrent calls from multiple threads produce unique event numbers.
+	 *
 	 * \param gopts Shared options.
 	 * \param tid   Optional thread ID override.
 	 * \return Newly created event header.
@@ -80,6 +104,7 @@ class GEventHeader : public GBase<GEventHeader> {
 
 	/**
 	 * \brief Get the local event number.
+	 * \details This is "run-local" in typical Geant4 usage.
 	 * \return Event number.
 	 */
 	[[nodiscard]] inline int getG4LocalEvn() const { return g4localEventNumber; }
@@ -97,7 +122,12 @@ class GEventHeader : public GBase<GEventHeader> {
 	/**
 	 * \brief Create a timestamp string using local time.
 	 *
-	 * Format: \c "Mon 01.30.2026 15:04:05" (weekday mm.dd.yyyy hh:mm:ss).
+	 * \details
+	 * Format:
+	 * \code
+	 *   "Mon 01.30.2026 15:04:05"
+	 * \endcode
+	 * (weekday mm.dd.yyyy hh:mm:ss).
 	 *
 	 * \return Timestamp string.
 	 */