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/SiTrackMakerTool_xk/src/SiTrackMaker_xk.cxx

@@ -670,7 +670,9 @@ std::list<Trk::Track*> InDet::SiTrackMaker_xk::getTracks
   const Trk::TrackParameters* Tp = nullptr;
   if (data.dbm()) Tp = getAtaPlaneDBM(fieldCache, data, Sp);
   else Tp = getAtaPlane(fieldCache, data, false, Sp);
-  /// if we failed to get the initial parameters, we bail out
+  /// if we failed to get the initial parameters, we bail out.
+  /// Can happen in certain pathological cases (e.g. malformed strip hits), 
+  /// or if we would be running with calo-ROI strip seeds (we aren't)
   if (!Tp) {
      ++data.summaryStatAll()[kTotalNoTrackPar][K];
      return tracks;
@@ -686,42 +688,55 @@ std::list<Trk::Track*> InDet::SiTrackMaker_xk::getTracks
   if (!m_cosmicTrack) m_roadmaker->detElementsRoad(ctx, fieldCache, *Tp,Trk::alongMomentum,   DE);
   else                m_roadmaker->detElementsRoad(ctx, fieldCache, *Tp,Trk::oppositeMomentum,DE);
 
+  /// if we don't use all of pix and SCT, filter our list, erasing any that don't fit our requirements
   if (!data.pix() || !data.sct() || data.dbm()) detectorElementsSelection(data, DE);
 
+  /// if we did not find sufficient detector elements to fulfill the minimum cluster requirement,
+  /// bail out. We will not be able to build a track satisfying the cuts. 
   if ( static_cast<int>(DE.size())  <   m_nclusmin) {
     delete Tp;
     return tracks;
   }
 
+  /// update statistics tables - we have sufficient detector elements to have a chance of finding a track!
   data.summaryStatAll()[kDESize][K] += double(DE.size());
   ++data.summaryStatAll()[kTotalUsedSeeds][K];
 
+  /// prepare a list of global positions
   std::list<Amg::Vector3D> Gp;
 
+  /// update another counter
   ++data.summaryStatUsedInTrack()[kUsedSeedsEta][K][r];
 
-  // Find possible list of tracks using space points space points information
-  //
+  /// Find possible list of tracks using space points space points information
+  ///
   if (!m_useBremModel) {
     tracks = m_tracksfinder->getTracks        (data.combinatorialData(), *Tp, Sp, Gp, DE, data.clusterTrack());
   } else if (!m_useCaloSeeds) {
     ++data.summaryStatAll()[kTotalBremSeeds][K];
     tracks = m_tracksfinder->getTracksWithBrem(data.combinatorialData(), *Tp, Sp, Gp, DE, data.clusterTrack(), false);
-  } else if (isCaloCompatible(data)) {
+  } 
+  /// Note: The branch below is the one taken in ATLAS default inside-out tracking for run-3
+  else if (isCaloCompatible(data)) {
     ++data.summaryStatAll()[kTotalBremSeeds][K];
     tracks = m_tracksfinder->getTracksWithBrem(data.combinatorialData(), *Tp, Sp, Gp, DE, data.clusterTrack(), true);
   } else {
     tracks = m_tracksfinder->getTracks        (data.combinatorialData(), *Tp, Sp, Gp, DE, data.clusterTrack());
   }
 
-  std::array<bool,SiCombinatorialTrackFinderData_xk::kNCombStats> inf{0,0,0,0,0,0};   m_tracksfinder->fillStatistic(data.combinatorialData(),inf);                                      
+  /// update stat tables
+  std::array<bool,SiCombinatorialTrackFinderData_xk::kNCombStats> inf{0,0,0,0,0,0};   
+  m_tracksfinder->fillStatistic(data.combinatorialData(),inf);                                      
   for (size_t p =0; p<inf.size(); ++p){
     if(inf[p]) ++data.summaryStatAll()[m_indexToEnum[p]][K];
   } 
 
+  /// update the cluster-track-map to allow to filter any 
+  /// upcoming seeds with hits that are already taken
   if (m_seedsfilter) {
     std::list<Trk::Track*>::iterator t = tracks.begin();
     while (t!=tracks.end()) {
+      /// require sufficient free clusters on track
       if (!isNewTrack(data, *t)) {
         delete (*t);
         tracks.erase(t++);