style: some more documentation

Author: N-Plx

reconstruction/alert/src/main/java/org/jlab/rec/atof/Cluster/AtofCluster.java

@@ -5,16 +5,32 @@
 import org.jlab.rec.atof.hit.BarHit;
 
 /**
+ * The {@code AtofCluster} represents clusters in the atof
  *
- * @author npilleux
+ * <p>
+ * Create clusters and compute their basic properties from the hits composing
+ * them.
+ * </p>
+ *
+ * @author pilleux
  */
 public class AtofCluster {
-    
+
+    /**
+     * list of hits in the bars.
+     */
     ArrayList<BarHit> barHits;
+    /**
+     * list of hits in the wedges.
+     */
     ArrayList<AtofHit> wedgeHits;
-    double x,y,z,time,energy;
+    /**
+     * cluster properties:position [cm], time [ns], energy[MeV], path length
+     * [cm] and length through the atof [cm].
+     */
+    double x, y, z, time, energy;
     double pathLength, inPathLength;
-    
+
     public ArrayList<BarHit> getBarHits() {
         return barHits;
     }
@@ -70,58 +86,66 @@ public double getEnergy() {
     public void setEnergy(double energy) {
         this.energy = energy;
     }
-    
+
     public double getPathLength() {
         return pathLength;
     }
 
     public void setPathLength(double pathLength) {
         this.pathLength = pathLength;
     }
-    
+
     public double getInPathLength() {
         return inPathLength;
     }
 
     public void setInPathLength(double inPathLength) {
         this.inPathLength = inPathLength;
     }
-    
-    //Cluster coordinates and time are defined as the coordinates and time of the max energy hit
-    //Can be changed later
+
+    /**
+     * Compute the cluster properties.
+     *
+     * Cluster coordinates and time are defined as the coordinates and time of
+     * the max energy hit.
+     *
+     * TO DO: Test other choices for the definitions.
+     *
+     */
     public final void computeClusterProperties() {
-        this.energy=0;
+        this.energy = 0;
         double max_energy = -1;
         AtofHit max_energy_hit = new AtofHit();
         BarHit max_energy_barhit = new BarHit();
 
-        for(int i_wedge = 0; i_wedge<this.wedgeHits.size(); i_wedge++)
-        {
+        for (int i_wedge = 0; i_wedge < this.wedgeHits.size(); i_wedge++) {
             AtofHit this_wedge_hit = this.wedgeHits.get(i_wedge);
             double this_energy = this_wedge_hit.getEnergy();
-            this.energy+=this_energy;
-            if(this_energy>max_energy){max_energy_hit = this_wedge_hit; max_energy = this_energy;}
+            this.energy += this_energy;
+            if (this_energy > max_energy) {
+                max_energy_hit = this_wedge_hit;
+                max_energy = this_energy;
+            }
         }
-        
-        for(int i_bar = 0; i_bar<this.barHits.size(); i_bar++)
-        {
+
+        for (int i_bar = 0; i_bar < this.barHits.size(); i_bar++) {
             BarHit this_bar_hit = this.barHits.get(i_bar);
             double this_energy = this_bar_hit.getEnergy();
-            this.energy+=this_energy;
-            if(this_energy>max_energy){max_energy_barhit = this_bar_hit; max_energy = this_energy;}
+            this.energy += this_energy;
+            if (this_energy > max_energy) {
+                max_energy_barhit = this_bar_hit;
+                max_energy = this_energy;
+            }
         }
-        
-        if(max_energy_hit.getEnergy() > max_energy_barhit.getEnergy())
-        {
+
+        if (max_energy_hit.getEnergy() > max_energy_barhit.getEnergy()) {
             this.time = max_energy_hit.getTime();
             this.x = max_energy_hit.getX();
             this.y = max_energy_hit.getY();
             this.z = max_energy_hit.getZ();
             this.pathLength = max_energy_hit.getPathLength();
             this.inPathLength = max_energy_hit.getInPathLength();
-        }
-        else
-        {
+        } else {
             this.time = max_energy_barhit.getTime();
             this.x = max_energy_barhit.getX();
             this.y = max_energy_barhit.getY();
@@ -130,28 +154,66 @@ public final void computeClusterProperties() {
             this.inPathLength = max_energy_barhit.getInPathLength();
         }
     }
-    
-    public double getPhi()
-    {
-        return Math.atan2(this.y, this.x);
+
+    public double getEdepWedge() {
+        double energy = 0;
+        for (int i = 0; i < this.wedgeHits.size(); i++) {
+            AtofHit this_hit = this.wedgeHits.get(i);
+            energy += this_hit.getEnergy();
+        }
+        return energy;
     }
-    
-    public double getBeta()
-    {
-        return (this.pathLength / this.time) / (2.9979 * Math.pow(10, 2));//to do: Change to non-hardcoded value for c
-    }
-    
-    public AtofCluster(ArrayList<BarHit> bar_hits, ArrayList<AtofHit> wedge_hits) 
-	{
-		this.barHits = bar_hits;  
-		this.wedgeHits = wedge_hits;  
-                this.computeClusterProperties();
+
+    public double getEdepBar() {
+        double energy = 0;
+        for (int i = 0; i < this.barHits.size(); i++) {
+            AtofHit this_hit = this.barHits.get(i);
+            energy += this_hit.getEnergy();
         }
+        return energy;
+    }
+
+    /**
+     * Compute the cluster phi angle in radians.
+     *
+     * @return a double that is angle in radians
+     * 
+     */
+    public double getPhi() {
+        return Math.atan2(this.y, this.x);
+    }
+
+    /**
+     * Compute the cluster beta from the path length and time.
+     *
+     * @return a double that is beta
+     * 
+     * - TO DO: Change to non-hardcoded value for c
+     * 
+     */
+    public double getBeta() {
+        //Need to change to non hardcoded value
+        return (this.pathLength / this.time) / (2.9979 * Math.pow(10, 2));
+    }
+
+    /**
+     * Constructor that initializes the list of bar hits and list of wedge hits
+     * and computes the cluster properties.
+     * 
+     * @param bar_hits a {@link ArrayList} of {@link BarHit}.
+     * @param wedge_hits a {@link ArrayList} of {@link AtofHit}.
+     * 
+     */
+    public AtofCluster(ArrayList<BarHit> bar_hits, ArrayList<AtofHit> wedge_hits) {
+        this.barHits = bar_hits;
+        this.wedgeHits = wedge_hits;
+        this.computeClusterProperties();
+    }
 
     /**
      * @param args the command line arguments
      */
     public static void main(String[] args) {
     }
-    
+
 }

reconstruction/alert/src/main/java/org/jlab/rec/atof/Cluster/ClusterFinder.java

@@ -8,21 +8,51 @@
 import org.jlab.rec.atof.hit.HitFinder;
 
 /**
+ * The {@code ClusterFinder} class builds clusters in the atof
  *
- * @author npilleux
+ * <p>
+ * Uses found hits information.
+ * Creates a {@link AtofCluster} matching them.
+ * </p>
+ *
+ * @author pilleux
  */
 public class ClusterFinder {
 
+    /**
+     * list of clusters.
+     */
     private ArrayList<AtofCluster> clusters;
 
+    /**
+     * Sets the list of clusters.
+     *
+     * @param clusters a {@link ArrayList} of {@link AtofCluster}.
+     * 
+     */
     public void setClusters(ArrayList<AtofCluster> clusters) {
         this.clusters = clusters;
     }
 
+    /**
+     * Gets the list of clusters.
+     *
+     * @return a {@link ArrayList} of {@link AtofCluster}.
+     * 
+     */
     public ArrayList<AtofCluster> getClusters() {
         return clusters;
     }
 
+    /**
+     * Builds clusters in the {@link DateEvent} using hits found and
+     * stored in a {@link HitFinder}.
+     *
+     * @param event the {@link DataEvent} containing the clusters to be built
+     * 
+     * @param hitfinder the {@link HitFinder} containing the hits that were found
+     * 
+     */
     public void makeClusters(DataEvent event, HitFinder hitfinder) {
 
         //A list of clusters is built for each event
@@ -162,6 +192,10 @@ public void makeClusters(DataEvent event, HitFinder hitfinder) {
         }
     }
 
+    /**
+     * Default constructor that initializes the list clusters as new empty
+     * list.
+     */
     public ClusterFinder() {
         clusters = new ArrayList<>();
     }

reconstruction/alert/src/main/java/org/jlab/rec/atof/Hit/AtofHit.java

@@ -147,11 +147,19 @@ public void setInPathLength(double inpath_length) {
         this.inPathLength = inpath_length;
     }
 
+    /**
+     * Computes the module index for the hit.
+     *
+     */
     public int computeModuleIndex() {
         //Index ranging 0 to 60 for each wedge+bar module
         return 4 * this.sector + this.layer;
     }
 
+     /**
+     * Assigns a type to the hit.
+     *
+     */
     public final String makeType() {
         //Type of hit can be wedge, bar up, bar down or bar.
         //Avoids testing components and order every time.
@@ -458,6 +466,15 @@ public final void matchTrack(TrackProjector track_projector) {
         }
     }
 
+    /**
+     * Matches the current track with ahdc tracks projections that have been written to the banks.
+     * Calculates the match by comparing the hit's azimuthal angle and longitudinal position
+     * (z) with the track projection. If a match is found within defined
+     * tolerances for phi and z, the path length of the matched hit is updated.
+     *
+     * @param event a @link{DataEvent} in which the track projections bank has been written.
+     *
+     */
     public int matchTrack(DataEvent event) {
 
         String track_bank_name = "AHDC::Projections";

reconstruction/alert/src/main/java/org/jlab/rec/atof/Hit/HitFinder.java

@@ -8,14 +8,33 @@
 import org.jlab.rec.atof.trackMatch.TrackProjector;
 
 /**
+ * The {@code HitFinder} class finds hits in the atof.
+ * 
+ * <p>
+ * Uses atof tdc bank information 
+ * 
+ * Creates a {@link ArrayList} of {@link BarHit} for bar hits read.
+ * Creates a {@link ArrayList} of {@link AtofHit} for wedge hits read.
+ * 
+ * </p>
  *
- * @author npilleux
+ * @author pilleux
  */
 public class HitFinder {
 
+    /**
+     * list of bar hits
+     */
     private ArrayList<BarHit> barHits;
+    /**
+     * list of wedge hits
+     */
     private ArrayList<AtofHit> wedgeHits;
 
+    /**
+     * Default constructor that initializes the list of hits as new empty
+     * lists.
+     */
     public HitFinder() {
         this.barHits = new ArrayList<>();
         this.wedgeHits = new ArrayList<>();
@@ -38,6 +57,16 @@ public void setWedgeHits(ArrayList<AtofHit> wedge_hits) {
         this.wedgeHits = wedge_hits;
     }
 
+    /**
+     * Find hits in the event, matches them to tracks found in the ahdc 
+     * and build their properties.
+     *
+     * @param event the {@link DataEvent} containing hits.
+     * @param atof the {@link Detector} representing the atof geometry to match
+     * the sector/layer/component to x/y/z.
+     * @param track_projector the {@link TrackProjector} containing the ahdc tracks projected
+     * to the atof for matching.
+     */
     public void findHits(DataEvent event, Detector atof, TrackProjector track_projector) {
         //For each event a list of bar hits and a list of wedge hits are filled
         this.barHits.clear();
@@ -103,6 +132,14 @@ public void findHits(DataEvent event, Detector atof, TrackProjector track_projec
         Collections.sort(this.wedgeHits, (hit1, hit2) -> Double.compare(hit2.getEnergy(), hit1.getEnergy()));
     }
 
+    /**
+     * Find hits in the event, matches them to tracks in the 
+     * projections bank and build their properties.
+     *
+     * @param event the {@link DataEvent} containing hits and the bank with ahdc track projections.
+     * @param atof the {@link Detector} representing the atof geometry to match
+     * the sector/layer/component to x/y/z.
+     */
     public void findHits(DataEvent event, Detector atof) {
 
         //For each event a list of bar hits and a list of wedge hits are filled