@@ -9,36 +9,64 @@
 import org.jlab.geom.detector.alert.AHDC.AlertDCDetector;
 import org.jlab.utils.groups.IndexedTable;
 
+/**
+ * Reads raw AHDC hits from the {@code AHDC::adc} bank, applies calibration corrections
+ * (time offsets, time-over-threshold, ADC gains), filters them against per-wire cuts in
+ * data mode, and builds the list of {@link Hit} objects used by downstream reconstruction.
+ * In simulation mode, the per-wire cuts and data-only ADC/ToT corrections are bypassed,
+ * and truth information is additionally read from the {@code MC::True} bank into {@link TrueHit}s.
+ */
 public class HitReader {
 
     private ArrayList<Hit>     _AHDCHits;
     private ArrayList<TrueHit> _TrueAHDCHits;
     private boolean sim = false;
 
-    private IndexedTable rawHitCutsTable;
-    private IndexedTable timeOffsetsTable;
-    private IndexedTable timeToDistanceWireTable;
-    private IndexedTable timeOverThresholdTable;
-    private IndexedTable adcGainsTable;
-
-    public HitReader(DataEvent event, AlertDCDetector detector, boolean simulation,
-                     IndexedTable rawHitCuts,
-                     IndexedTable timeOffsets,
-                     IndexedTable timeToDistanceWire,
-                     IndexedTable timeOverThreshold,
-                     IndexedTable adcGains) {
+    /**
+     * Constructs a HitReader and eagerly populates the hit lists from the given event.
+     * After construction, retrieve the results via {@link #get_AHDCHits()} and
+     * (in simulation) {@link #get_TrueAHDCHits()}.
+     *
+     * @param event              current event containing the {@code AHDC::adc} bank (and {@code MC::True} in sim)
+     * @param detector           AHDC geometry used to resolve wire positions on each hit
+     * @param simulation         {@code true} for Monte Carlo events; disables data-only cuts and corrections
+     * @param rawHitCuts         per-wire acceptance cuts (time, ToT, ADC, pedestal min/max)
+     * @param timeOffsets        per-wire {@code t0} offsets applied to the leading-edge time
+     * @param timeToDistanceWire per-wire T2D calibration coefficients used to convert time to DOCA
+     * @param timeOverThreshold  per-wire ToT correction factors (applied in data mode only)
+     * @param adcGains           per-wire ADC gain corrections (applied in data mode only)
+     */
+    public HitReader(DataEvent event, AlertDCDetector detector, boolean simulation, IndexedTable rawHitCuts, IndexedTable timeOffsets,
+					 IndexedTable timeToDistanceWire, IndexedTable timeOverThreshold, IndexedTable adcGains) {
         sim = simulation;
         fetch_AHDCHits(event, detector, rawHitCuts, timeOffsets, timeToDistanceWire, timeOverThreshold, adcGains);
         if (simulation) fetch_TrueAHDCHits(event);
     }
 
-	public double T2Dfunction(int sector, int layer, int wire, double time){
-		long hash = timeToDistanceWireTable.getList().getIndexGenerator().hashCode(sector, layer, wire);
-		List<Double> t2d = timeToDistanceWireTable.getDoublesByHash(hash);
-
-		// T2D function consists of three 1st order polynomials (p1, p2, p3) and two transition functions (t1, t2).
-		// Column order: p1_int(0), p1_slope(1), p2_int(2), p2_slope(3), p3_int(4), p3_slope(5),
-		//               t1_x0(6), t1_width(7), t2_x0(8), t2_width(9), z0(10), z1(11), z2(12), extra1(13), extra2(14), chi2ndf(15)
+	/**
+	 * Converts a calibrated drift time into a distance-of-closest-approach (DOCA) for a
+	 * given wire, using the piecewise T2D calibration stored in {@code timeToDistanceWire}.
+	 *
+	 * <p>The result is a blend of three 1st-order polynomials {@code p1, p2, p3} stitched
+	 * together by two logistic transition functions {@code t1, t2}:
+	 * {@code doca = p1·(1-t1) + t1·p2·(1-t2) + t2·p3}. The coefficients are looked up
+	 * once per call via a hashed index on (sector, layer, wire).
+	 *
+	 * <p>Expected column order of the calibration row:
+	 * p1_int(0), p1_slope(1), p2_int(2), p2_slope(3), p3_int(4), p3_slope(5),
+	 * t1_x0(6), t1_width(7), t2_x0(8), t2_width(9), z0(10), z1(11), z2(12),
+	 * extra1(13), extra2(14), chi2ndf(15).
+	 *
+	 * @param sector             AHDC sector index
+	 * @param layer              packed layer index ({@code superlayer*10 + layer})
+	 * @param wire               wire (component) id within the layer
+	 * @param time               calibrated drift time in ns
+	 * @param timeToDistanceWire per-wire T2D calibration table
+	 * @return the DOCA in mm
+	 */
+	private double T2Dfunction(int sector, int layer, int wire, double time, IndexedTable timeToDistanceWire){
+		long hash = timeToDistanceWire.getList().getIndexGenerator().hashCode(sector, layer, wire);
+		List<Double> t2d = timeToDistanceWire.getDoublesByHash(hash);
 
 		double p1 = (t2d.get(0) + t2d.get(1)*time);
 		double p2 = (t2d.get(2) + t2d.get(3)*time);
@@ -50,16 +78,31 @@ public double T2Dfunction(int sector, int layer, int wire, double time){
 		return (p1)*(1.0 - t1) + (t1)*(p2)*(1.0 - t2) + (t2)*(p3);
 	}
 
-	public final void fetch_AHDCHits(DataEvent event, AlertDCDetector detector,
-	                                 IndexedTable rawHitCuts, IndexedTable timeOffsets,
-	                                 IndexedTable timeToDistanceWire, IndexedTable totCorrTable,
-	                                 IndexedTable adcGains) {
-		this.rawHitCutsTable = rawHitCuts;
-		this.timeOffsetsTable = timeOffsets;
-		this.timeToDistanceWireTable = timeToDistanceWire;
-		this.timeOverThresholdTable = totCorrTable;
-		this.adcGainsTable = adcGains;
-
+	/**
+	 * Reads the {@code AHDC::adc} bank, calibrates each raw row, and builds the list of
+	 * reconstructed {@link Hit}s. For each row the method:
+	 * <ol>
+	 *   <li>applies the per-wire time offset {@code t0} (subtracting event start time in data mode),</li>
+	 *   <li>in data mode, corrects time-over-threshold and enforces per-wire acceptance cuts
+	 *       (time, ToT, ADC, pedestal, and {@code wfType <= 2}) — hits failing the cuts are dropped,</li>
+	 *   <li>computes the DOCA from the calibrated time via {@link #T2Dfunction} (DOCA forced to 0
+	 *       when {@code time < 0}),</li>
+	 *   <li>in data mode, applies the per-wire ADC gain correction,</li>
+	 *   <li>instantiates a {@link Hit}, resolves its wire position via the geometry, and stores the
+	 *       calibrated ADC and ToT on it.</li>
+	 * </ol>
+	 * The resulting list is stored via {@link #set_AHDCHits(ArrayList)} (empty if the bank is absent).
+	 *
+	 * @param event                  current event
+	 * @param detector               AHDC geometry used to set each hit's wire position
+	 * @param rawHitCuts             per-wire acceptance cuts (data mode only)
+	 * @param timeOffsets            per-wire {@code t0}
+	 * @param timeToDistanceWire     per-wire T2D coefficients
+	 * @param timeOverThresholdTable per-wire ToT correction factors (data mode only)
+	 * @param adcGains               per-wire ADC gain corrections (data mode only)
+	 */
+	private void fetch_AHDCHits(DataEvent event, AlertDCDetector detector, IndexedTable rawHitCuts, IndexedTable timeOffsets,
+	                            IndexedTable timeToDistanceWire, IndexedTable timeOverThresholdTable, IndexedTable adcGains) {
 		ArrayList<Hit> hits = new ArrayList<>();
 
 		if (!event.hasBank("AHDC::adc")) {
@@ -92,45 +135,43 @@ public final void fetch_AHDCHits(DataEvent event, AlertDCDetector detector,
 			double adcOffset         = bankDGTZ.getFloat("ped", i);
 			int    wfType            = bankDGTZ.getShort("wfType", i);
 
-			// Raw hit cuts
-			double t_min   = rawHitCutsTable.getDoubleValue("t_min",   sector, number, wire);
-			double t_max   = rawHitCutsTable.getDoubleValue("t_max",   sector, number, wire);
-			double tot_min = rawHitCutsTable.getDoubleValue("tot_min", sector, number, wire);
-			double tot_max = rawHitCutsTable.getDoubleValue("tot_max", sector, number, wire);
-			double adc_min = rawHitCutsTable.getDoubleValue("adc_min", sector, number, wire);
-			double adc_max = rawHitCutsTable.getDoubleValue("adc_max", sector, number, wire);
-			double ped_min = rawHitCutsTable.getDoubleValue("ped_min", sector, number, wire);
-			double ped_max = rawHitCutsTable.getDoubleValue("ped_max", sector, number, wire);
-
 			// Time calibration
-			double t0   = timeOffsetsTable.getDoubleValue("t0", sector, number, wire);
+			double t0   = timeOffsets.getDoubleValue("t0", sector, number, wire);
 			double time = leadingEdgeTime - t0 - startTime;
 
 			// ToT correction
 			double totUsed = timeOverThreshold;
 			if (!sim) {
 				double totCorr = timeOverThresholdTable.getDoubleValue("totCorr", sector, number, wire);
 				if (totCorr != 0.0) totUsed = timeOverThreshold * totCorr;
-			}
-
-			// Hit selection (cuts)
-			boolean passCuts =
-				(wfType <= 2) &&
-				(adcRaw >= adc_min) && (adcRaw <= adc_max) &&
-				(time   >= t_min)   && (time   <= t_max) &&
-				(timeOverThreshold >= tot_min) && (timeOverThreshold <= tot_max) &&
-				(adcOffset >= ped_min) && (adcOffset <= ped_max);
 
-			if (!passCuts && !sim) continue;
+				// Hit selection (cuts) — only applied on data, bypassed in sim
+				double t_min   = rawHitCuts.getDoubleValue("t_min",   sector, number, wire);
+				double t_max   = rawHitCuts.getDoubleValue("t_max",   sector, number, wire);
+				double tot_min = rawHitCuts.getDoubleValue("tot_min", sector, number, wire);
+				double tot_max = rawHitCuts.getDoubleValue("tot_max", sector, number, wire);
+				double adc_min = rawHitCuts.getDoubleValue("adc_min", sector, number, wire);
+				double adc_max = rawHitCuts.getDoubleValue("adc_max", sector, number, wire);
+				double ped_min = rawHitCuts.getDoubleValue("ped_min", sector, number, wire);
+				double ped_max = rawHitCuts.getDoubleValue("ped_max", sector, number, wire);
+
+				boolean passCuts =
+					(wfType <= 2) &&
+					(adcRaw >= adc_min) && (adcRaw <= adc_max) &&
+					(time   >= t_min)   && (time   <= t_max) &&
+					(timeOverThreshold >= tot_min) && (timeOverThreshold <= tot_max) &&
+					(adcOffset >= ped_min) && (adcOffset <= ped_max);
+
+				if (!passCuts) continue;
+			}
 
 			// DOCA from calibrated time
-			double doca = T2Dfunction(sector, number, wire, time);
-			if (time < 0) doca = 0.0;
+			double doca = (time < 0) ? 0.0 : T2Dfunction(sector, number, wire, time, timeToDistanceWire);
 
 			// ADC gain calibration
 			double adcCal = adcRaw;
 			if (!sim) {
-				double gainCorr = adcGainsTable.getDoubleValue("gainCorr", sector, number, wire);
+				double gainCorr = adcGains.getDoubleValue("gainCorr", sector, number, wire);
 				if (gainCorr != 0.0) adcCal = adcRaw * gainCorr;
 			}
 
@@ -144,7 +185,15 @@ public final void fetch_AHDCHits(DataEvent event, AlertDCDetector detector,
 		this.set_AHDCHits(hits);
 	}
 
-	public final void fetch_TrueAHDCHits(DataEvent event) {
+	/**
+	 * Reads Monte-Carlo truth information from the {@code MC::True} bank into a list of
+	 * {@link TrueHit}s (particle id and average hit position/energy). Called only when
+	 * the reader is constructed with {@code simulation = true}. If the bank is absent,
+	 * the resulting list is empty.
+	 *
+	 * @param event current event
+	 */
+	private void fetch_TrueAHDCHits(DataEvent event) {
 
 		ArrayList<TrueHit> truehits = new ArrayList<>();
 
@@ -164,18 +213,36 @@ public final void fetch_TrueAHDCHits(DataEvent event) {
 		this.set_TrueAHDCHits(truehits);
 	}
 
+	/**
+	 * @return the calibrated AHDC hits produced from the current event; never {@code null}
+	 *         (empty if the {@code AHDC::adc} bank is missing)
+	 */
 	public ArrayList<Hit> get_AHDCHits() {
 		return _AHDCHits;
 	}
 
+	/**
+	 * Replaces the internally stored list of AHDC hits. Primarily used by {@link #fetch_AHDCHits}.
+	 *
+	 * @param hits the list to store
+	 */
 	public void set_AHDCHits(ArrayList<Hit> hits) {
 		this._AHDCHits = hits;
 	}
 
+	/**
+	 * @return the MC-truth hits for the current event (populated only in simulation mode;
+	 *         {@code null} for data events where {@code fetch_TrueAHDCHits} was not called)
+	 */
 	public ArrayList<TrueHit> get_TrueAHDCHits() {
 		return _TrueAHDCHits;
 	}
 
+	/**
+	 * Replaces the internally stored list of MC-truth hits. Primarily used by {@link #fetch_TrueAHDCHits}.
+	 *
+	 * @param trueHits the list to store
+	 */
 	public void set_TrueAHDCHits(ArrayList<TrueHit> trueHits) {
 		this._TrueAHDCHits = trueHits;
 	}