From cd19b45c6724cdaa06d69046bf426b28106064bb Mon Sep 17 00:00:00 2001
From: Susumu Oda <susumu.oda@cern.ch>
Date: Fri, 6 Dec 2019 21:13:54 +0100
Subject: [PATCH 1/2] Add description of SiDetElementBoundaryLinks_xk to its
 header file.

---
 .../SiDetElementBoundaryLinks_xk.h                        | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiDetElementBoundaryLinks_xk.h b/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiDetElementBoundaryLinks_xk.h
index 7bc53f5611d7..6b3202adaac1 100644
--- a/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiDetElementBoundaryLinks_xk.h
+++ b/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiDetElementBoundaryLinks_xk.h
@@ -1,5 +1,5 @@
 /*
-  Copyright (C) 2002-2018 CERN for the benefit of the ATLAS collaboration
+  Copyright (C) 2002-2019 CERN for the benefit of the ATLAS collaboration
 */
 
 /////////////////////////////////////////////////////////////////////////////////
@@ -12,6 +12,12 @@
 #include "SiSPSeededTrackFinderData/SiDetElementBoundaryLink_xk.h"
 #include <vector>
 
+/**
+ * This InDet::SiDetElementBoundaryLinks_xk class is the vector of 
+ * InDet::SiDetElementBoundaryLink_xk. The object of this class is
+ * prepared by InDet::SiDetElementBoundaryLinksCondAlg_xk
+ * and is used by InDet::SiCombinatorialTrackFinder_xk.
+ */
 namespace InDet {
   typedef std::vector<SiDetElementBoundaryLink_xk> SiDetElementBoundaryLinks_xk;
 }
-- 
GitLab


From 1511396106700ef38125fc682fee625f438269de Mon Sep 17 00:00:00 2001
From: Susumu Oda <susumu.oda@cern.ch>
Date: Mon, 9 Dec 2019 13:28:29 +0100
Subject: [PATCH 2/2] Add more comments

---
 .../SiSpacePointsSeedMakerEventData.h         |  55 ++++---
 .../SiTrackMakerEventData_xk.h                |  54 +++++--
 .../SiTrajectoryElement_xk.h                  | 145 +++++++++++-------
 3 files changed, 165 insertions(+), 89 deletions(-)

diff --git a/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiSpacePointsSeedMakerEventData.h b/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiSpacePointsSeedMakerEventData.h
index 7e8f5860fcae..57a7594490a8 100644
--- a/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiSpacePointsSeedMakerEventData.h
+++ b/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiSpacePointsSeedMakerEventData.h
@@ -23,16 +23,27 @@
 
 namespace InDet {
 
+ /**
+  @class InDet::SiSpacePointsSeedMakerEventData
+  
+  InDet::SiSpacePointsSeedMakerEventData holds event dependent data
+  used by ISiSpacePointsSeedMaker.
+  The object is owened by SiSPSeededTrackFinder.
+  Some data members are not used depending on ToolType.
+  @author Susumu.Oda@cern.ch
+  */
+
   class SiSpacePointsSeedMakerEventData {
   public:
+    /// enums to specify which SiSpacePointsSeedMaker owns the object.
     enum ToolType {
-      ATLxk,
-      BeamGas,
-      Cosmic,
-      HeavyIon,
-      ITK,
-      LowMomentum,
-      Trigger
+      ATLxk, //!< SiSpacePointsSeedMaker_ATLxk
+      BeamGas, //!< SiSpacePointsSeedMaker_BeamGas
+      Cosmic, //!< SiSpacePointsSeedMaker_Cosmic
+      HeavyIon, //!< SiSpacePointsSeedMaker_HeavyIon
+      ITK, //!< SiSpacePointsSeedMaker_ITK
+      LowMomentum, //!< SiSpacePointsSeedMaker_LowMomentum
+      Trigger ///!< SiSpacePointsSeedMaker_Trigger
     };
 
     bool initialized{false};
@@ -78,14 +89,16 @@ namespace InDet {
     float ftrigW{0.};
     float umax{0.};    
 
-    ///////////////////////////////////////////////////////////////////
-    // Beam geometry
-    // Updated only in buildBeamFrameWork,
-    // which is called by newEvent and newRegion
-    ///////////////////////////////////////////////////////////////////
-    float xbeam[4]{0., 1., 0., 0.}; // x,ax,ay,az - center and x-axis direction
-    float ybeam[4]{0., 0., 1., 0.}; // y,ax,ay,az - center and y-axis direction
-    float zbeam[4]{0., 0., 0., 1.}; // z,ax,ay,az - center and z-axis direction
+    /**
+     * @name Beam geometry
+     * Updated only in buildBeamFrameWork,
+     * which is called by newEvent and newRegion
+     */
+    //@{
+    float xbeam[4]{0., 1., 0., 0.}; //!< x,ax,ay,az - center and x-axis direction
+    float ybeam[4]{0., 0., 1., 0.}; //!< y,ax,ay,az - center and y-axis direction
+    float zbeam[4]{0., 0., 0., 1.}; //!< z,ax,ay,az - center and z-axis direction
+    //@}
 
     std::vector<int> r_index;
     std::vector<int> r_map;
@@ -98,10 +111,11 @@ namespace InDet {
 
     std::set<float> l_vertex;
 
-    ///////////////////////////////////////////////////////////////////
-    // Tables for 3 space points seeds search
-    // Updated in many mthods
-    ///////////////////////////////////////////////////////////////////
+    /**
+     * @name Tables for 3 space points seeds search
+     * Updated in many mthods
+     */
+    //@{
     std::vector<InDet::SiSpacePointForSeed*> SP;
     std::vector<InDet::SiSpacePointForSeedITK*> SP_ITK;
     std::vector<float> Zo;
@@ -112,6 +126,7 @@ namespace InDet {
     std::vector<float> X;
     std::vector<float> Y;
     std::vector<float> Er;
+    //@}
 
     InDet::SiSpacePointsSeed seedOutput;
 
@@ -164,6 +179,8 @@ namespace InDet {
     std::multimap<float,InDet::SiSpacePointsProSeedITK*> seeds_ITK;
     std::multimap<float,InDet::SiSpacePointsProSeedITK*>::iterator seed_ITK;
 
+    /// Initialize data members based on ToolType enum.
+    /// This method has to be called just after creation in SiSPSeededTrackFinder.
     void initialize(ToolType type,
                     int maxsizeSP,
                     int maxOneSize,
diff --git a/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiTrackMakerEventData_xk.h b/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiTrackMakerEventData_xk.h
index 3ade2ec6bd4b..f8d1c4a8d196 100644
--- a/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiTrackMakerEventData_xk.h
+++ b/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiTrackMakerEventData_xk.h
@@ -7,8 +7,6 @@
 /////////////////////////////////////////////////////////////////////////////////
 //  Header file for class SiTrackMakerEventData_xk
 /////////////////////////////////////////////////////////////////////////////////
-// Class for event dependent data used in SiTrackMaker_xk
-/////////////////////////////////////////////////////////////////////////////////
 
 #ifndef SiTrackMakerEventData_xk_H
 #define SiTrackMakerEventData_xk_H
@@ -27,6 +25,19 @@ namespace Trk {
 
 namespace InDet {
 
+ /**
+  @class InDet::SiTrackMakerEventData_xk
+  
+  InDet::SiTrackMakerEventData_xk holds event dependent data
+  used by ISiTrackMaker.
+  The object is owened by SiSPSeededTrackFinder.
+  @author Susumu.Oda@cern.ch
+  */
+
+// Class for event dependent data used in SiTrackMaker_xk
+/////////////////////////////////////////////////////////////////////////////////
+
+
   class SiTrackMakerEventData_xk {
   public:
     SiTrackMakerEventData_xk();
@@ -52,30 +63,39 @@ namespace InDet {
     SiCombinatorialTrackFinderData_xk& combinatorialData();
 
   protected:
-    virtual void dummy() = 0; // make sure this cannot be instantiated (for testing)
+    virtual void dummy() = 0; //!< make sure this cannot be instantiated (for testing)
     void setPRDtoTrackMap(const Trk::PRDtoTrackMap* prd_to_track_map) { m_combinatorialData.setPRDtoTrackMap(prd_to_track_map); }
 
   private:
-    // Counters
-    int m_inputseeds{0}; // Number input seeds
-    int m_goodseeds{0}; // Number good seeds
-    int m_findtracks{0}; // Numbe found tracks
+    /// @name Counters
+    //@{
+    int m_inputseeds{0}; //!< Number input seeds
+    int m_goodseeds{0}; //!< Number good seeds
+    int m_findtracks{0}; //!< Numbe found tracks
+    //@}
     
-    // Flag for dump method
-    int m_nprint{0}; // Kind output information
+    /// Flag for dump method
+    int m_nprint{0};
 
-    // Updated by many methods
+    /// @name Data members updated by many methods
+    //@{
     std::multimap<const Trk::PrepRawData*, const Trk::Track*> m_clusterTrack;
     std::array<double, 9> m_par;
-    
-    // Updated only by newEvent and newTrigEvent methods
+    //@}
+
+    /// @name Data members updated only by newEvent and newTrigEvent methods
+    //@{
     bool m_pix{false};
     bool m_sct{false};
+    //@}
 
-    // Updated only by getTracks
+    /// @name Data members updated only by getTracks
+    //@{
     bool m_dbm{false};
+    //@}
 
-    // Updated only by newEvent method
+    /// @name Data members updated only by newEvent method
+    //@{
     std::list<double> m_caloF;
     std::list<double> m_caloR;
     std::list<double> m_caloZ;
@@ -83,9 +103,11 @@ namespace InDet {
     std::list<double> m_hadR;
     std::list<double> m_hadZ;
     std::array<double, 2> m_xybeam{0., 0.};
+    //@}
 
-    // SeedToTrackConversionData to hold the event dependent data of SeedToTrackConversionTool.
+    /// SeedToTrackConversionData to hold the event dependent data of SeedToTrackConversionTool.
     SeedToTrackConversionData m_conversionData;
+
     class ExtendedSiCombinatorialTrackFinderData_xk : public SiCombinatorialTrackFinderData_xk {
     public:
       ExtendedSiCombinatorialTrackFinderData_xk() {};
@@ -97,7 +119,7 @@ namespace InDet {
       void dummy() override {}
     };
 
-    // SiCombinatorialTrackFinderData_xk to hold the event dependent data of SiCombinatorialTrackFinder_xk.
+    /// SiCombinatorialTrackFinderData_xk to hold the event dependent data of SiCombinatorialTrackFinder_xk.
     ExtendedSiCombinatorialTrackFinderData_xk m_combinatorialData;
   };
 
diff --git a/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiTrajectoryElement_xk.h b/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiTrajectoryElement_xk.h
index 1c10bf4e27cd..9892c82fefb9 100644
--- a/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiTrajectoryElement_xk.h
+++ b/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiTrajectoryElement_xk.h
@@ -76,9 +76,9 @@ namespace InDet{
       bool isNextClusterHoleF(bool&,double&);
 
       ///////////////////////////////////////////////////////////////////
-      // Methods update with cluster information
+      /// @name Methods update with cluster information
       ///////////////////////////////////////////////////////////////////
- 
+      //@{ 
       bool addCluster
 	(Trk::PatternTrackParameters&,Trk::PatternTrackParameters&,double&);
       bool addCluster
@@ -88,11 +88,12 @@ namespace InDet{
 	(Trk::PatternTrackParameters&,
 	 Trk::PatternTrackParameters&,
 	 Trk::PatternTrackParameters&);
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Methods noise calculation
+      /// @name Methods noise calculation
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       void noiseProduction
 	(int,const Trk::PatternTrackParameters&);
       void noiseInitiate();
@@ -124,14 +125,18 @@ namespace InDet{
       const Trk::Surface*  surface()  const {return m_surface;}
       const InDet::SiClusterLink_xk& linkF (int i) const {return m_linkF[i];}
       const InDet::SiClusterLink_xk& linkB (int i) const {return m_linkB[i];}
+      //@}
  
       ///////////////////////////////////////////////////////////////////
-      // Main methods
+      /// @name Main methods
       ///////////////////////////////////////////////////////////////////
+      //@{
 
-      // T = InDet::SiClusterCollection::const_iterator or
-      //     InDet::PixelClusterCollection::const_iterator or
-      //     InDet::SCT_ClusterCollection::const_iterator
+      /**
+       * T = InDet::SiClusterCollection::const_iterator or
+       *     InDet::PixelClusterCollection::const_iterator or
+       *     InDet::SCT_ClusterCollection::const_iterator
+       */
       template <typename T>
       void set(int st,
 	       const InDet::SiDetElementBoundaryLink_xk*& dl,
@@ -142,24 +147,28 @@ namespace InDet{
       void setTools(const InDet::SiTools_xk*); 
       void setParameters(); 
       void bremNoiseModel();
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Update first trajectory element on the trajectory with track 
-      // parameters
+      /// @name Update first trajectory element on the trajectory with
+      /// track parameters
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       bool firstTrajectorElement(const Trk::TrackParameters&);
       bool firstTrajectorElement();
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Forward propagation  
+      // @name Forward propagation  
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       bool ForwardPropagationWithoutSearch(SiTrajectoryElement_xk&);
       bool ForwardPropagationWithSearch(SiTrajectoryElement_xk&);
-      // T = InDet::SiClusterCollection::const_iterator or
-      //     InDet::PixelClusterCollection::const_iterator or
-      //     InDet::SCT_ClusterCollection::const_iterator
+      /**
+       * T = InDet::SiClusterCollection::const_iterator or
+       *     InDet::PixelClusterCollection::const_iterator or
+       *     InDet::SCT_ClusterCollection::const_iterator
+       */
       template <typename T>
         bool ForwardPropagationForClusterSeach
 	(int n,
@@ -167,10 +176,13 @@ namespace InDet{
 	 const InDet::SiDetElementBoundaryLink_xk*& dl,
 	 const T& sb,
 	 const T& se);
-      
-      // T = InDet::SiClusterCollection::const_iterator or
-      //     InDet::PixelClusterCollection::const_iterator or
-      //     InDet::SCT_ClusterCollection::const_iterator
+      //@}
+
+      /**
+       * T = InDet::SiClusterCollection::const_iterator or
+       *     InDet::PixelClusterCollection::const_iterator or
+       *     InDet::SCT_ClusterCollection::const_iterator
+       */
       template <typename T>
         void CloseClusterSeach
 	(Trk::PatternTrackParameters& Tpa,
@@ -181,22 +193,24 @@ namespace InDet{
       void eraseClusterForwardPropagation();
 
       ///////////////////////////////////////////////////////////////////
-      // For last detector element initiate smoother  
+      /// @name For last detector element initiate smoother  
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       bool lastTrajectorElement();
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Backward propagation for smoother  
+      /// @name Backward propagation for smoother  
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       bool BackwardPropagationSmoother(SiTrajectoryElement_xk&,bool);
       bool BackwardPropagationFilter  (SiTrajectoryElement_xk&);
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Search clusters compatible with track  
+      /// @name Search clusters compatible with track  
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       int searchClusters                (Trk::PatternTrackParameters&,SiClusterLink_xk*);
       template <typename T> 
         int searchClustersSub             (Trk::PatternTrackParameters&,SiClusterLink_xk*);
@@ -207,93 +221,105 @@ namespace InDet{
         int searchClustersWithoutStereoSCT(Trk::PatternTrackParameters&,SiClusterLink_xk*);
       template <typename T>
         int searchClustersWithStereo      (Trk::PatternTrackParameters&,SiClusterLink_xk*);
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Search only clusters without track assosiation compatible with track  
+      /// @name Search only clusters without track assosiation compatible with track  
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       template <typename T>
         int searchClustersWithoutStereoAssPIX(Trk::PatternTrackParameters&,SiClusterLink_xk*, const Trk::PRDtoTrackMap &);
       template <typename T>
         int searchClustersWithoutStereoAssSCT(Trk::PatternTrackParameters&,SiClusterLink_xk*, const Trk::PRDtoTrackMap &);
       template <typename T>
         int searchClustersWithStereoAss      (Trk::PatternTrackParameters&,SiClusterLink_xk*, const Trk::PRDtoTrackMap &);
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Is difference between forward and backward propagation   
+      /// @name Is difference between forward and backward propagation   
       ///////////////////////////////////////////////////////////////////
-      
+      //@{
       bool difference() const;
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // TrackStateOnSurface production  
+      // @name TrackStateOnSurface production  
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       Trk::TrackStateOnSurface* trackStateOnSurface(bool,bool,bool,int);
       Trk::TrackStateOnSurface* trackSimpleStateOnSurface(bool,bool,int);
       Trk::TrackStateOnSurface* trackPerigeeStateOnSurface();
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // TrackParameters production  
+      /// @name TrackParameters production  
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       const Trk::TrackParameters* trackParameters(bool,int);
       const Trk::TrackParameters* trackParametersWithNewDirection(bool,int);
       const Trk::TrackParameters* trackParameters(Trk::PatternTrackParameters&,bool);
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Initiate state
+      // @name Initiate state
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       bool initiateState(Trk::PatternTrackParameters&,Trk::PatternTrackParameters&);
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Last detector elements with clusters
+      // @name Last detector elements with clusters
       ///////////////////////////////////////////////////////////////////
-      
+      //@{
       void lastActive();
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Step of trajectory calculation
+      /// @name Step of trajectory calculation
       ///////////////////////////////////////////////////////////////////
-      
+      //@{
       double step(SiTrajectoryElement_xk&);
       double stepToPerigee();
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Global position of the track parameters
+      /// @name Global position of the track parameters
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       Amg::Vector3D globalPosition();
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Quality of the trajectory element
+      /// @name Quality of the trajectory element
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       double quality(int&) const;
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Propagate parameters with covariance
+      /// @name Propagate parameters with covariance
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       bool propagate
 	(Trk::PatternTrackParameters  &,
 	 Trk::PatternTrackParameters  &,
 	 double                       &);
+      //@}
 
+      ////////////////////////////////////////////////////////////////////
+      /// @name Propagate parameters without covariance
       ///////////////////////////////////////////////////////////////////
-      // Propagate parameters without covariance
-      ///////////////////////////////////////////////////////////////////
-
+      //@{
       bool propagateParameters
 	(Trk::PatternTrackParameters&,
 	 Trk::PatternTrackParameters&,
 	 double                     &);
+      //@}
 
       ///////////////////////////////////////////////////////////////////
-      // Work methods for propagation
+      /// @name Work methods for propagation
       ///////////////////////////////////////////////////////////////////
-
+      //@{
       void transformPlaneToGlobal
 	(bool,Trk::PatternTrackParameters&,double*);
       bool transformGlobalToPlane
@@ -302,11 +328,12 @@ namespace InDet{
 	(bool,double*);
       bool straightLineStepToPlane
 	(bool,double*);
+      //@}
 
     private:
       
       ///////////////////////////////////////////////////////////////////
-      // Private Data
+      /// Private Data
       ///////////////////////////////////////////////////////////////////
  
       enum IteratorType {
@@ -321,7 +348,7 @@ namespace InDet{
       bool                                        m_fieldMode   ;
       bool                                        m_useassoTool = false ;
       int                                         m_status      ;  
-      int                                         m_detstatus   ; // 0 (no clusters) 
+      int                                         m_detstatus   ; //!< 0 (no clusters) 
       int                                         m_inside      ;
       int                                         m_ndist       ;
       int                                         m_nlinksF     ;
@@ -360,8 +387,18 @@ namespace InDet{
       const InDetDD::SiDetectorElement*           m_detelement  ;
       const InDet::SiDetElementBoundaryLink_xk*   m_detlink     ;
       const Trk::Surface*                         m_surface     ;
+      /**
+       * @name Data members using std::any
+       * std::any is used to cover 
+       * - InDet::PixelClusterCollection::const_iterator
+       * - InDet::SCT_ClusterCollection::const_iterator
+       * - InDet::SiClusterCollection::const_iterator
+       * used in SiTrajectoryElement_xk.cxx.
+       */
+      //@{
       std::any                                    m_sibegin     ;
       std::any                                    m_siend       ;
+      //@}
       const InDet::SiCluster*                     m_cluster     ;
       const InDet::SiCluster*                     m_clusterOld  ;
       const InDet::SiCluster*                     m_clusterNoAdd;
@@ -385,7 +422,7 @@ namespace InDet{
       IteratorType m_itType{Invalid};
 
       ///////////////////////////////////////////////////////////////////
-      // Methods
+      /// Private Methods
       ///////////////////////////////////////////////////////////////////
       
       void patternCovariances(const InDet::SiCluster*,double&,double&,double&);
-- 
GitLab