Commit 092df2c

committed

saving doxygen doc progress

1 parent 819b87b commit 092df2cCopy full SHA for 092df2c

40 files changed

`‎ci/create_doxygen.sh‎`

-Original file line number
+Diff line change
   inplace_sed 's|^HIDE_FRIEND_COMPOUNDS[[:space:]]*=.*|HIDE_FRIEND_COMPOUNDS    = NO|g' "$f"
   inplace_sed 's|^QUIET[[:space:]]*=.*|QUIET                                    = YES|g' "$f"
   inplace_sed 's|^WARNINGS[[:space:]]*=.*|WARNINGS                              = YES|g' "$f"
 +  inplace_sed 's|^CLASS_GRAPH[[:space:]]*=.*|CLASS_GRAPH                        = NO|g' "$f"
 +  inplace_sed 's|^COLLABORATION_GRAPH[[:space:]]*=.*|COLLABORATION_GRAPH        = NO|g' "$f"
 +  inplace_sed 's|^AUTOLINK_SUPPORT[[:space:]]*=.*|AUTOLINK_SUPPORT              = YES|g' "$f"
   replace_doxy_list_key_single_line "$f" "FILE_PATTERNS" \
     "*.h *.hh *.hpp *.hxx *.c *.cc *.cpp *.cxx *.C *.H"

`‎ci/doxygen.sh‎`

-Original file line number
+Diff line change
 # ---- config ----
 doc_modules=(
 -  goptions guts gfields glogging gfactory gtouchable ghit gtranslationTable
 -  gdata gdynamicDigitization g4display g4dialog
 -)
 +guts goptions glogging gbase gfactory textProgressBar gtouchable ghit gtranslationTable gdata gboard gdynamicDigitization
 +gsystem gstreamer eventDispenser gqtbuttonswidget g4display g4dialog g4system gparticle gphysics gsplash gsd
 +gfields gdetector dbselect gtree gui actions utilities)
 script_dir="${0:A:h}"
 pages_dir="pages"

`‎gdata/event/gEventDataCollection.cc‎`

-Original file line number
+Diff line change
  * - 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.
 + *
 + * Ownership summary:
 + * - After calling \ref GEventDataCollection::addDetectorTrueInfoData "addDetectorTrueInfoData()"
 + *   or \ref GEventDataCollection::addDetectorDigitizedData "addDetectorDigitizedData()",
 + *   the event container owns the provided object and the caller must not use the moved-from pointer.
  */
 #include "gEventDataCollection.h"
 ///
 /// \details
 /// This exists as a convenience hook for potential future example factories.
 -/// Current example behavior uses \ref GEventHeader::create() as the event counter.
 +/// Current example behavior uses \ref GEventHeader::create "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.
 +/// Counter used by \ref GEventHeader::create "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) {

`‎gdata/event/gEventDataCollection.h‎`

-Original file line number
+Diff line change
 /**
  * \file gEventDataCollection.h
 - * \brief Defines \ref GEventDataCollection event-level aggregation of per-detector hit data.
 + * \brief Defines \ref GEventDataCollection, event-level aggregation of per-detector hit data.
+ *
  * \details
  * An event data collection groups all hit data produced during a single event.
  * \endcode
+ *
  * ## Event-level semantics
 - * - each call to \ref GEventDataCollection::addDetectorTrueInfoData() or \ref GEventDataCollection::addDetectorDigitizedData()
 + * - each call to \ref GEventDataCollection::addDetectorTrueInfoData "addDetectorTrueInfoData()"
 + *   or \ref GEventDataCollection::addDetectorDigitizedData "addDetectorDigitizedData()"
  *   appends one hit entry to the specified detector’s vectors.
  * - the detector entry is created on demand if it does not already exist.
+ *
  * - touchable (for identity creation in examples)
+ *
  * This provides a single "options bundle" for event-level examples/applications.
 + *
 + * \return Composite options group rooted at \ref GEVENTDATA_LOGGER.
  */
 inline auto defineOptions() -> GOptions {
 	auto goptions = GOptions(GEVENTDATA_LOGGER);
  * - local event number
  * - thread ID label
  * - timestamp string
 + *
 + * \note
 + * This class intentionally does not enforce invariants such as "truth hits must equal digitized hits".
 + * If an application requires such invariants, it should validate them at a higher level.
  */
 class GEventDataCollection : public GBase<GEventDataCollection>
+{
 	/**
 	 * \brief Convenience accessor for the event number.
 +	 *
 +	 * \details
 +	 * Equivalent to \ref GEventHeader::getG4LocalEvn "getG4LocalEvn()" on the owned header.
 +	 *
 	 * \return Event number stored in the header.
 	 */
 	[[nodiscard]] auto getEventNumber() const -> int { return gevent_header->getG4LocalEvn(); }
+	 *
 	 * \details
 	 * This method exists to support examples/tests. It:
 -	 * - creates a new \ref GEventHeader
 +	 * - creates a new \ref GEventHeader via \ref GEventHeader::create "create()"
 	 * - constructs an event data collection
 	 * - inserts one \ref GDigitizedData and one \ref GTrueInfoData entry under detector "ctof"
+	 *

`‎gdata/event/gEventHeader.h‎`

-Original file line number
+Diff line change
  * - 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 "create()"
 + * provides a deterministic generator for examples and tests.
+ *
 - * \note Time stamp is generated using the local system time at construction.
 + * Timestamp behavior:
 + * - Time stamp is generated using local system time at construction.
 + *
 + * \note Threading
 + * The factory \ref GEventHeader::create "create()" uses an atomic counter so that concurrent calls
 + * from multiple threads produce unique event numbers in examples/tests.
  */
 constexpr const char* GDATAEVENTHEADER_LOGGER = "event_header";
+ *
  * \details
  * Event header logging can be enabled/controlled by including this in composite option bundles.
 + *
 + * \return An options group rooted at the \ref GDATAEVENTHEADER_LOGGER domain.
  */
 inline GOptions defineOptions() {
 	auto goptions = GOptions(GDATAEVENTHEADER_LOGGER);
  * - labeling events in logs/output
  * - reproducing the event/thread provenance for debugging
  */
 -class GEventHeader : public GBase<GEventHeader> {
 +class GEventHeader : public GBase<GEventHeader>
 +{
 public:
 	/**
 	 * \brief Construct an event header with explicit values.
 	/**
 	 * \brief Get the local event number.
 -	 * \details This is "run-local" in typical Geant4 usage.
 +	 *
 +	 * \details
 +	 * This is "run-local" in typical Geant4 usage (i.e. it resets each run).
 +	 *
 	 * \return Event number.
 	 */
 	[[nodiscard]] inline int getG4LocalEvn() const { return g4localEventNumber; }

`‎gdata/examples/event_example.cc‎`

-Original file line number
+Diff line change
  * This example emulates a simplified event loop where each event produces hit data for one or more
  * sensitive detectors and stores them into a \ref GEventDataCollection.
+ *
 - * The \ref GEventDataCollection owns *per-hit* objects (event-level semantics):
 - * - \ref GTrueInfoData:   "truth" observables derived from simulation / tracking (energy deposition, positions, times, …)
 - * - \ref GDigitizedData:  "digitized" observables produced by electronics/digitization (ADC/TDC-like quantities, readout coords, …)
 + * The \ref GEventDataCollection owns *per-hit* objects (event-level semantics). For each hit, two
 + * complementary views may be produced and stored:
 + * - \ref GTrueInfoData stores simulation-level ("truth") observables derived from tracking
 + *   (energy deposition, step-averaged kinematics, positions, times, provenance labels, ...).
 + * - \ref GDigitizedData stores electronics-level ("digitized") observables produced by
 + *   detector response and digitization logic (ADC/TDC-like quantities, calibrated values, readout coordinates, ...).
+ *
  * For each event, data are organized as:
  * \code
  * \endcode
+ *
  * \section event_demo What this example demonstrates
 - * - Creating event containers (\ref GEventDataCollection::create()).
 - * - Adding *additional hits* and *additional detectors* to the same event via:
 - *   - \ref GEventDataCollection::addDetectorTrueInfoData()
 - *   - \ref GEventDataCollection::addDetectorDigitizedData()
 - * - Inspecting the stored data:
 + * - Creating event containers with the factory \ref GEventDataCollection::create "create()".
 + * - Adding *additional hits* and *additional detectors* to the same event with:
 + *   - \ref GEventDataCollection::addDetectorTrueInfoData "addDetectorTrueInfoData()"
 + *   - \ref GEventDataCollection::addDetectorDigitizedData "addDetectorDigitizedData()"
 + * - Inspecting stored data:
  *   - per-detector hit counts
 - *   - identity strings (\ref GTrueInfoData::getIdentityString, \ref GDigitizedData::getIdentityString)
 + *   - identity strings (\ref GTrueInfoData::getIdentityString "getIdentityString()",
 + *     \ref GDigitizedData::getIdentityString "getIdentityString()")
  *   - truth and digitized observable maps
 - * - Demonstrating digitized filtering of streaming-readout (SRO) keys:
 - *   - \ref GDigitizedData::getIntObservablesMap(int)
 - *   - \ref GDigitizedData::getDblObservablesMap(int)
 + * - Demonstrating filtering of streaming-readout (SRO) keys for digitized data:
 + *   - \ref GDigitizedData::getIntObservablesMap "getIntObservablesMap(int)"
 + *   - \ref GDigitizedData::getDblObservablesMap "getDblObservablesMap(int)"
+ *
  * \section event_threading Threading model
  * The example uses a simple work-distribution pattern:
  * - A shared atomic counter assigns event numbers.
  * - Each worker thread builds independent \ref GEventDataCollection objects.
  * - Results are appended to a shared vector under a mutex.
+ *
 - * \note \ref GEventHeader::create() and the test factories \ref GTrueInfoData::create and
 - *       \ref GDigitizedData::create use internal thread-safe counters, so concurrent execution
 - *       is supported for this example-style workload.
 + * \note \ref GEventHeader::create "create()" and the test factories
 + *       \ref GTrueInfoData::create "create()" and \ref GDigitizedData::create "create()"
 + *       use internal thread-safe counters, so concurrent execution is supported for this
 + *       example-style workload.
+ *
  * \section gdata_event_usage Usage
  * Build this example together with the GData library components and required GEMC utilities
 - * (logging, options, threads abstraction).
 + * (logging, options, threads abstraction). Then run it to print a readable dump of each generated
 + * event container.
+ *
  * \author \n &copy; Maurizio Ungaro
  * \author e-mail: ungaro@jlab.org
  * \brief Convert a scalar map into a compact, deterministic string for logging.
+ *
  * \details
 - * This helper exists purely for examples/tests: it prints key/value pairs in the
 - * order given by the container (std::map order is lexicographic by key).
 + * This helper exists purely for examples/tests. It prints key/value pairs in the order given
 + * by the container.
 + *
 + * Determinism note:
 + * - \c std::map iterates in lexicographic key order, which makes the output stable across runs.
+ *
  * \tparam MapType A map-like type with string keys and printable scalar values.
  * \param m The map to stringify.
+ *
  * \details
  * This performs a deep inspection of the \ref GEventDataCollection structure:
 - * - loops over detectors (sdName)
 - * - prints number of truth hits and digitized hits
 + * - loops over detectors (\c sdName)
 + * - prints the number of truth hits and digitized hits
  * - for each hit prints identity and observables
+ *
 - * For digitized data, this also prints both filtered views:
 - * - which=0: non-SRO (physics/content) keys
 - * - which=1: SRO-only keys (crate/slot/channel/timeAtElectronics/chargeAtElectronics)
 + * For digitized data, this prints both filtered views to demonstrate SRO separation:
 + * - \c which=0: non-SRO (physics/content) keys
 + * - \c which=1: SRO-only keys (crate/slot/channel/timeAtElectronics/chargeAtElectronics)
+ *
  * \param edc The event to inspect.
 - * \param log Logger to emit messages to.
 + * \param log Logger used to emit messages.
  */
 static void dump_event(const std::shared_ptr<GEventDataCollection>& edc, const std::shared_ptr<GLogger>& log) {
 	log->info(0, "------------------------------------------------------------");
 			log->info(0, "    dbl  non-SRO: ", map_to_string(dbls_non_sro));
 			log->info(0, "    dbl  SRO:     ", map_to_string(dbls_sro_only));
 -			// Convenience accessor demo (shows sentinel if missing):
 +			// Convenience accessor demo (shows sentinel if missing).
 			log->info(0, "    timeAtElectronics() = ", dh->getTimeAtElectronics());
+		}
+	}
+ *
  * \details
  * This performs a few sanity checks that are useful when evolving the library:
 - * - event has at least one detector
 - * - each detector collection has consistent hit vectors (non-null pointers)
 + * - the event has at least one detector
 + * - each detector collection has non-null hit pointers
+ *
 - * \note This is intentionally non-fatal; it logs diagnostics rather than aborting.
 + * This is intentionally non-fatal. It logs diagnostics rather than aborting so the example
 + * can continue printing the full event content for debugging.
+ *
  * \param edc The event to validate.
  * \param log Logger instance.
  */
 -static void validate_event_structure(const std::shared_ptr<GEventDataCollection>& edc, const std::shared_ptr<GLogger>& log) {
 +static void validate_event_structure(const std::shared_ptr<GEventDataCollection>& edc,
 +                                     const std::shared_ptr<GLogger>&              log) {
 	const auto& dcm = edc->getDataCollectionMap();
 	if (dcm.empty()) {
 		log->info(0, "VALIDATION: event ", edc->getEventNumber(), " has no detectors (unexpected in this example).");
 			if (!digiHits[i]) log->info(0, "VALIDATION: detector <", sdName, "> digitized hit ", i, " is null.");
+		}
 -		// A very common expectation in practice: same number of truth and digitized hits per detector.
 -		// This is not guaranteed by the API (you can add one without the other), but it is a useful
 -		// check for this demo-style data producer.
 +		// A common expectation in production is matching truth and digitized hit counts per detector.
 +		// This is not enforced by the API (you can add one without the other), but it is a useful
 +		// consistency check for this demo-style producer.
 		if (truthHits.size() != digiHits.size()) {
 			log->info(0, "VALIDATION: detector <", sdName, "> truthHits(", truthHits.size(),
 			          ") != digitizedHits(", digiHits.size(), ") in event ", edc->getEventNumber());
  * \brief Produce a set of events using multiple worker threads.
+ *
  * \details
 - * Each event is created via \ref GEventDataCollection::create(), then extended to demonstrate:
 + * Each event is created via \ref GEventDataCollection::create "create()", then extended to demonstrate:
  * - adding additional hits under the same detector key
  * - adding a second detector key
+ *
 + * Concurrency notes:
 + * - Each worker produces independent event containers (no shared mutation of events).
 + * - A mutex is used only when appending thread-local results to the shared output vector.
 + *
  * \param nevents  Total number of events to generate.
  * \param nthreads Number of worker threads.
  * \param gopt     Shared options.
 	std::vector<std::shared_ptr<GEventDataCollection>> collected;
 	collected.reserve(static_cast<size_t>(nevents));
 -	// Thread-safe integer event counter starts at 1.
 +	// Thread-safe integer event counter starts at 1 (local to this example run).
 	std::atomic<int> next{1};
 	// Pool of threads. (jthread_alias joins on destruction.)

`‎gdata/examples/gframe_example.cc‎`

-Original file line number
+Diff line change
@@ @@ -1,20 +1,33 @@ @@
 /**
 -* \file gframe_example.cc
 + * \file gframe_example.cc
  * \brief Example demonstrating frame data collection.
+ *
  * \page gdata_frame_example Frame data example
+ *
  * \section frame_overview Overview
 - * This example demonstrates how to build a frame container (\ref GFrameDataCollection)
 - * that owns:
 + * This example demonstrates how to build a frame container (\ref GFrameDataCollection) that owns:
  * - a \ref GFrameHeader (frame ID + duration)
  * - a list of \ref GIntegralPayload objects (crate/slot/channel/charge/time)
+ *
 - * Frames are typically used for streaming/readout-style output where data are grouped
 - * by time windows rather than by Geant4 events.
 + * Frames are typically used for streaming/readout-style output where data are grouped by
 + * time windows rather than by Geant4 events. Conceptually, a frame corresponds to a fixed
 + * integration window (for example 33.33 ms), during which many channels may fire.
 + *
 + * \section frame_payload_layout Payload layout
 + * The \ref GFrameDataCollection::addIntegralPayload "addIntegralPayload()" API accepts a packed
 + * integer vector with a fixed order (size must be exactly 5):
 + * - payload[0] crate
 + * - payload[1] slot
 + * - payload[2] channel
 + * - payload[3] charge
 + * - payload[4] time
 + *
 + * This example constructs three such payloads and inserts them into the frame collection.
+ *
  * \section gdata_frame_usage Usage
 - * Compile this file along with the frame classes and the logging/options utilities.
 + * Compile this file along with the frame classes and the logging/options utilities. Run it to:
 + * - print the frame ID and computed frame time
 + * - print each stored payload in its fixed order
+ *
  * \author \n &copy; Maurizio Ungaro
  * \author e-mail: ungaro@jlab.org
 using namespace std;
 -// TODO: run this in multiple threads and collect results in frames like in runAction
 -int main(int argc, char *argv[]) {
 +// TODO: Run this in multiple threads and collect results into frames (similar to a runAction-style aggregator).
 +int main(int argc, char* argv[]) {
 	auto gopts = std::make_shared<GOptions>(argc, argv, gevent_data::defineOptions());
 	auto log  = std::make_shared<GLogger>(gopts, SFUNCTION_NAME, GEVENTDATA_LOGGER);
 	cout << "Frame ID: " << frameData->getFrameID() << endl;
 	cout << "Frame Header Time: " << frameData->getHeader()->getTime() << endl;
 -	const vector<GIntegralPayload*> *payloads = frameData->getIntegralPayload();
 +	const vector<GIntegralPayload*>* payloads = frameData->getIntegralPayload();
 	cout << "Number of integral payloads: " << payloads->size() << endl;
 	for (size_t i = 0; i < payloads->size(); ++i) {
 		cout << endl;
+	}
 -	delete frameData;  // deletes header and all payloads inside
 +	delete frameData; // deletes header and all payloads inside
 	return EXIT_SUCCESS;
+}

Comments

(0)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Commit 092df2c

`‎ci/create_doxygen.sh‎`

`‎ci/doxygen.sh‎`

`‎gdata/event/gEventDataCollection.cc‎`

`‎gdata/event/gEventDataCollection.h‎`

`‎gdata/event/gEventHeader.h‎`

`‎gdata/examples/event_example.cc‎`

`‎gdata/examples/gframe_example.cc‎`

Uh oh!

File tree

‎ci/create_doxygen.sh‎

‎ci/doxygen.sh‎

‎gdata/event/gEventDataCollection.cc‎

‎gdata/event/gEventDataCollection.h‎

‎gdata/event/gEventHeader.h‎

‎gdata/examples/event_example.cc‎

‎gdata/examples/gframe_example.cc‎

0 commit comments

`‎ci/create_doxygen.sh‎`

`‎ci/doxygen.sh‎`

`‎gdata/event/gEventDataCollection.cc‎`

`‎gdata/event/gEventDataCollection.h‎`

`‎gdata/event/gEventHeader.h‎`

`‎gdata/examples/event_example.cc‎`

`‎gdata/examples/gframe_example.cc‎`