Document Si track extension - first batch

This MR contains the initial work towards cleaning up and documenting the combinatorial silicon track extension - including the SiTrackMaker_xk, SiCombinatorialTrackFinder_xk, SiTrajectory_xk, SiTrajectoryElement_xk.

The changes attempt to make the code more readable for newcomers and document the logic in a more accessible way to users studying the code, while preserving the elegance of the original implementation. No performance changes are expected.

As the classes are tightly coupled, they can only be documented together. As a result, there is a large number of changed lines throughout the affected classes, even though the vast majority of changes are just formatting, renaming, and comments.

Given that I have reached 1400 lines of changes, with a related growth in the risk of merge conflicts (already had one), I am containing the progress so far within this MR, and will follow up in another.

Adding @sroe, @npetters, @sswatman and @zschilla

Also adding @jsandesa - do any of my changes clash with developments you are working on?

InnerDetector/InDetRecTools/SiCombinatorialTrackFinderTool_xk/src/SiCombinatorialTrackFinder_xk.cxx

@@ -367,7 +367,7 @@ const std::list<Trk::Track*>&  InDet::SiCombinatorialTrackFinder_xk::getTracks
     return data.tracks();
   }
 
-  /// sort 
+  /// sort in step order
   data.trajectory().sortStep();
 
 
@@ -597,57 +597,78 @@ InDet::SiCombinatorialTrackFinder_xk::EStat_t InDet::SiCombinatorialTrackFinder_
 
   /// Build initial trajectory
   bool Qr;
+  /// This will initialize the trajectory using the clusters we have and the parameter estimate 
   bool Q = data.trajectory().initialize(m_usePIX, m_useSCT, p_pixcontainer, p_sctcontainer, Tp, Cl, DEL, Qr);
 
+  /// if the initialisation fails (indicating this is probably a bad attempt) and we are running with
+  /// global positions instead of seeding  
   if (!Q && Sp.size() < 2 && Gp.size() > 3) {
-
+    /// reset our cluster list 
     Cl.clear();
+    /// try again using the clusters from the track parameters only
     if (!data.trajectory().trackParametersToClusters(p_pixcontainer, p_sctcontainer, Tp, DEL, PT, Cl)) return TwoCluster;
     if (!data.trajectory().initialize(m_usePIX, m_useSCT, p_pixcontainer, p_sctcontainer, Tp, Cl, DEL, Qr)) return TwoCluster;
+    /// if it worked now, set the quality flag to true
     Q = Qr = true;
   }
 
-  if (!Qr){++data.roadbug(); return WrongRoad;} 
+  /// this can never happen?!
+  if (!Qr){
+    ++data.roadbug(); 
+    return WrongRoad;
+  } 
+  /// this can never happen either?!
   if (!Q) return WrongInit;
+
   ++data.inittracks();
+  /// if the last cluster on track is in the pixels, this is assumed to come from a pixel seed
   bool pixseed = data.trajectory().isLastPixel();
+  /// max #iterations
   int itmax    = 30;
   if (data.simpleTrack()) itmax = 10;
   if (data.heavyIon()) itmax = 50;
 
-  // Track finding
-  //
-  if (pixseed) {      // Strategy for pixel seeds
+  /// Track finding
+  if (pixseed) {      /// Strategy for pixel seeds
     if (!data.trajectory().forwardExtension (false,itmax)) return CantFindTrk;
     if (!data.trajectory().backwardSmoother (false)      ) return CantFindTrk;
     if (!data.trajectory().backwardExtension(itmax)      ) return CantFindTrk;
-
+    /// refine if needed
     if (data.trajectory().difference() > 0) {
       if (!data.trajectory().forwardFilter()          ) return CantFindTrk;
       if (!data.trajectory().backwardSmoother (false) ) return CantFindTrk;
     } 
     int na = data.trajectory().nclustersNoAdd();
+    /// check if we found enough clusters
     if (data.trajectory().nclusters()+na < data.nclusmin() || data.trajectory().ndf() < data.nwclusmin()) return CantFindTrk;
-  } else {      // Strategy for mixed seeds
+  } 
+  /// case of a strip seed or mixed PPS
+  else {      // Strategy for mixed seeds
     if (!data.trajectory().backwardSmoother(isTwoPointSeed)       ) return CantFindTrk;
     if (!data.trajectory().backwardExtension(itmax)    ) return CantFindTrk;
     if (!data.trajectory().forwardExtension(true,itmax)) return CantFindTrk;
 
+    /// first application of hit cut 
     int na = data.trajectory().nclustersNoAdd();
     if (data.trajectory().nclusters()+na < data.nclusmin() || data.trajectory().ndf() < data.nwclusmin()) return CantFindTrk;
+    /// backward smooting
     if (!data.trajectory().backwardSmoother(false)    ) return CantFindTrk;
 
+    /// apply hit cut again following smoothing step
     na     = data.trajectory().nclustersNoAdd();
     if (data.trajectory().nclusters()+na < data.nclusmin() || data.trajectory().ndf() < data.nwclusmin()) return CantFindTrk;
 
+    /// refine if needed
     if (data.trajectory().difference() > 0) {
       if (!data.trajectory().forwardFilter()         ) return CantFindTrk;
       if (!data.trajectory().backwardSmoother (false)) return CantFindTrk;
     }
   } 
-
+  /// quality cut 
   if (data.trajectory().qualityOptimization()     <           (m_qualityCut*data.nclusmin())    ) return CantFindTrk;
+
   if (data.trajectory().pTfirst  () < data.pTmin()     && data.trajectory().nclusters() < data.nclusmin() ) return CantFindTrk;
+
   if (data.trajectory().nclusters() < data.nclusminb() || data.trajectory().ndf      () < data.nwclusmin()) return CantFindTrk;
   
   return Success;