docs: Document the "singleton" like pattern

ChristianTackeGSI · dennisklein · commit 6adb758f3cfb · 2023-04-19T19:49:18.000+02:00
Co-authored-by: Dennis Klein @dennisklein
diff --git a/doxygen/singleton.dox b/doxygen/singleton.dox
@@ -0,0 +1,33 @@
+/**
+ * \weakgroup fairroot_singleton FairRoot/ROOT Style "singleton"-like Objects
+
+These classes are currently using a singleton-like pattern that is
+NOT [the classic textbook pattern](https://en.wikipedia.org/wiki/Singleton_pattern).
+
+This pattern is discouraged for new code!
+Also the existing code utilising it is slowly getting deprecated
+in favour of code not relying on singleton like behaviour.
+
+Attributes / Design:
+
+- There can only be one or zero instances per process (or thread for some).
+  Note that zero is explicitly allowed.
+
+  Some classes enforce this at runtime, some don't.
+
+- Global access via the static `::Instance()` function on the class
+  returns a pointer to that object or `nullptr` if the instance does
+  not exist. It DOES NOT lazily create the "singleton" instance (see
+  also below).
+
+  Note: This function is likely getting deprecated in the process
+  of getting away from this behaviour.
+
+- Other code is responsible for creating (thus owning) and
+  destructing the object. The object can be created on the stack,
+  on the heap or even as a member variable of another class
+  (constructors are public). That code can either be internal
+  FairRoot code or code by the user (like with the \ref FairRun
+  classes).
+
+ */
diff --git a/fairroot/base/field/FairFieldFactory.h b/fairroot/base/field/FairFieldFactory.h
@@ -17,6 +17,9 @@
 
 class FairField;
 
+/**
+ * \ingroup base_sim fairroot_singleton
+ */
 class FairFieldFactory
 {
   public:
diff --git a/fairroot/base/sim/FairGeaneApplication.h b/fairroot/base/sim/FairGeaneApplication.h
@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (C) 2014-2022 GSI Helmholtzzentrum fuer Schwerionenforschung GmbH  *
+ * Copyright (C) 2014-2023 GSI Helmholtzzentrum fuer Schwerionenforschung GmbH  *
  *                                                                              *
  *              This software is distributed under the terms of the             *
  *              GNU Lesser General Public Licence (LGPL) version 3,             *
@@ -21,11 +21,11 @@ class FairField;
 
 /**
  * The Main Application for GEANE
+ * \ingroup base_sim fairroot_singleton
  * @author M. Al-Turany
  * @version 0.1
  * @since 10.11.10
  */
-
 class FairGeaneApplication : public TVirtualMCApplication
 {
   public:
diff --git a/fairroot/base/sim/FairMCApplication.h b/fairroot/base/sim/FairMCApplication.h
@@ -53,11 +53,11 @@ enum class FairMCApplicationState
 
 /**
  * The Main Application ( Interface to MonteCarlo application )
+ * \ingroup base_sim fairroot_singleton
  * @author M. Al-Turany, D. Bertini
  * @version 0.1
  * @since 12.01.04
  */
-
 class FairMCApplication : public TVirtualMCApplication
 {
   public:
@@ -80,8 +80,7 @@ class FairMCApplication : public TVirtualMCApplication
     /** default destructor
      */
     ~FairMCApplication() override;
-    /** Singelton instance
-     */
+
     static FairMCApplication* Instance();
     virtual void AddDecayModes();
     /**  Add user defined particles (optional) */
diff --git a/fairroot/base/steer/FairLinkManager.h b/fairroot/base/steer/FairLinkManager.h
@@ -13,6 +13,9 @@
 #include <TObject.h>   // for TObject
 #include <set>         // for set of branch types to ignore
 
+/**
+ * \ingroup base_steer fairroot_singleton
+ */
 class FairLinkManager : public TObject
 {
   public:
@@ -21,7 +24,6 @@ class FairLinkManager : public TObject
     /**dtor*/
     ~FairLinkManager() override;
 
-    /** static access method */
     static FairLinkManager* Instance();
     virtual void AddIgnoreType(Int_t type);   ///< Adds a BranchId (Type) to which links are not included in the link
                                               ///< list. Either ignore types or include types can be given.
diff --git a/fairroot/base/steer/FairRadGridManager.h b/fairroot/base/steer/FairRadGridManager.h
@@ -1,5 +1,5 @@
 /********************************************************************************
- *    Copyright (C) 2014 GSI Helmholtzzentrum fuer Schwerionenforschung GmbH    *
+ * Copyright (C) 2014-2023 GSI Helmholtzzentrum fuer Schwerionenforschung GmbH  *
  *                                                                              *
  *              This software is distributed under the terms of the             *
  *              GNU Lesser General Public Licence (LGPL) version 3,             *
@@ -24,8 +24,8 @@ class TClonesArray;
 
 /**
  * @class FairRadGridManager
+ * \ingroup base_steer fairroot_singleton
  */
-
 class FairRadGridManager
 {
   public:
diff --git a/fairroot/base/steer/FairRadLenManager.h b/fairroot/base/steer/FairRadLenManager.h
@@ -1,5 +1,5 @@
 /********************************************************************************
- *    Copyright (C) 2014 GSI Helmholtzzentrum fuer Schwerionenforschung GmbH    *
+ * Copyright (C) 2014-2023 GSI Helmholtzzentrum fuer Schwerionenforschung GmbH  *
  *                                                                              *
  *              This software is distributed under the terms of the             *
  *              GNU Lesser General Public Licence (LGPL) version 3,             *
@@ -20,8 +20,8 @@ class TVirtualMC;
 
 /**
  * @class FairRadLenManager
+ * \ingroup base_steer fairroot_singleton
  */
-
 class FairRadLenManager
 {
   public:
diff --git a/fairroot/base/steer/FairRadMapManager.h b/fairroot/base/steer/FairRadMapManager.h
@@ -1,5 +1,5 @@
 /********************************************************************************
- *    Copyright (C) 2014 GSI Helmholtzzentrum fuer Schwerionenforschung GmbH    *
+ * Copyright (C) 2014-2023 GSI Helmholtzzentrum fuer Schwerionenforschung GmbH  *
  *                                                                              *
  *              This software is distributed under the terms of the             *
  *              GNU Lesser General Public Licence (LGPL) version 3,             *
@@ -20,8 +20,8 @@ class TVirtualMC;
 
 /**
  * @class FairRadMapManager
+ * \ingroup base_steer fairroot_singleton
  */
-
 class FairRadMapManager
 {
   public:
diff --git a/fairroot/base/steer/FairRun.h b/fairroot/base/steer/FairRun.h
@@ -15,6 +15,7 @@
 #include "FairSource.h"
 
 #include <Rtypes.h>   // for Int_t, Bool_t, etc
+#include <TFile.h>    //
 #include <TMCtls.h>   // for multi-threading
 #include <TNamed.h>   // for TNamed
 #include <TString.h>
@@ -28,17 +29,15 @@ class FairRootManager;
 class FairRuntimeDb;
 class FairSink;
 class FairTask;
-class TFile;
 class FairField;
-class TGeoHMatrix;
 
 /**
  * Configure the Simuation or Analysis
+ * \ingroup base_steer fairroot_singleton
  * @author M. Al-Turany  D. Bertini
  * @version 0.1
  * @since 12.01.04
  */
-
 class FairRun : public TNamed
 {
     friend class FairMCApplication;
@@ -52,9 +51,7 @@ class FairRun : public TNamed
      * default dtor
      */
     ~FairRun() override;
-    /**
-     * static instance
-     */
+
     static FairRun* Instance();
     /**
      * Add a FAIRTask to the simulation or analysis
diff --git a/fairroot/base/steer/FairRunAna.h b/fairroot/base/steer/FairRunAna.h
@@ -8,31 +8,27 @@
 #ifndef FAIRRUNANA_H
 #define FAIRRUNANA_H
 
-/**
- * Configure and manage the  Analysis
- * @author M. Al-Turany D. Bertini
- * @version 0.1
- * @since 28.02.05
- */
-
 #include "FairRootManager.h"   // for FairRootManager
 #include "FairRun.h"           // for FairRun
 #include "FairRunInfo.h"       // for FairRunInfo
 
 #include <Rtypes.h>    // for Bool_t, Double_t, UInt_t, etc
+#include <TF1.h>       //
 #include <TString.h>   // for TString
 
 class FairField;
-class TF1;
-class TFile;
-
-class FairSource;
 class FairFileSource;
 class FairMixedSource;
 
+/**
+ * Configure and manage the  Analysis
+ * \ingroup base_steer fairroot_singleton
+ * @author M. Al-Turany D. Bertini
+ * @version 0.1
+ * @since 28.02.05
+ */
 class FairRunAna : public FairRun
 {
-
   public:
     static FairRunAna* Instance();
     ~FairRunAna() override;
@@ -86,9 +82,9 @@ class FairRunAna : public FairRun
     Bool_t IsTimeStamp() { return fTimeStamps; }
 
     /** Set the flag for proccessing lmd files */
-    void StopProcessingLMD(void) { fFinishProcessingLMDFile = kTRUE; }
+    void StopProcessingLMD() { fFinishProcessingLMDFile = kTRUE; }
     /** Get the status of lmd file proccessing */
-    Bool_t GetLMDProcessingStatus(void) { return fFinishProcessingLMDFile; }
+    Bool_t GetLMDProcessingStatus() { return fFinishProcessingLMDFile; }
 
   protected:
     /**
diff --git a/fairroot/base/steer/FairRunAnaProof.h b/fairroot/base/steer/FairRunAnaProof.h
@@ -8,19 +8,18 @@
 #ifndef FAIRRUNANAPROOF_H
 #define FAIRRUNANAPROOF_H
 
+#include "FairFileSource.h"   // FairRunAnaProof can only accept FairFileSource as source
+#include "FairRunAna.h"
+
+#include <TProof.h>
+
 /**
  * Configure and manage the  Analysis on proof
+ * \ingroup base_steer fairroot_singleton
  * @author R. Karabowicz
  * @version 0.1
  * @since 30.04.2013
  */
-
-#include "FairFileSource.h"   // FairRunAnaProof can only accept FairFileSource as source
-#include "FairRunAna.h"
-
-#include <Rtypes.h>
-#include <TProof.h>
-
 class FairRunAnaProof : public FairRunAna
 {
   public:
diff --git a/fairroot/base/steer/FairRunSim.h b/fairroot/base/steer/FairRunSim.h
@@ -30,7 +30,7 @@ class FairPrimaryGenerator;
 
 /**
  * \brief Configure the Simulation session
- * \ingroup base_steer
+ * \ingroup base_steer fairroot_singleton
  * @author M. Al-Turany  D. Bertini
  * @version 0.1
  * @since 12.01.04
@@ -42,7 +42,7 @@ class FairRunSim : public FairRun
     FairRunSim(Bool_t isMaster = kTRUE);
     /** default dtor*/
     ~FairRunSim() override;
-    /** Singelton instance*/
+
     static FairRunSim* Instance();
     /**
      *       Add a module to the simulation (e.g. PIPE, Magnet, ..etc)
diff --git a/fairroot/base/steer/FairTrajFilter.h b/fairroot/base/steer/FairTrajFilter.h
@@ -24,6 +24,7 @@ class TParticle;
 
 /**
  * @class FairTrajFilter
+ * \ingroup base_steer fairroot_singleton
  * The filter for storing of the trajectories.
  * This singleton class controls storing of trajectories
  * in the gGeoManager list during the simulation.
@@ -117,11 +118,7 @@ class FairTrajFilter
 
     void Init(TString brName = "GeoTracks", TString folderName = "MCGeoTrack");
     void Reset();
-    /**
-     * This function is used to access the methods of the class.
-     * @return Pointer to the singleton FairTrajFilter object, created
-     * with FairTrajFilter::FairTrajFilter().
-     */
+
     static FairTrajFilter* Instance();
 
     /**
diff --git a/fairroot/eventdisplay/FairEventManager.h b/fairroot/eventdisplay/FairEventManager.h
@@ -34,6 +34,9 @@ class TEveText;
 class TGeoNode;
 class TGListTreeItem;
 
+/**
+ * \ingroup eventdisplay fairroot_singleton
+ */
 class FairEventManager : public TEveEventManager
 {
   public:
diff --git a/fairroot/online/steer/FairRunOnline.h b/fairroot/online/steer/FairRunOnline.h
@@ -8,13 +8,6 @@
 #ifndef FAIRRUNONLINE_H
 #define FAIRRUNONLINE_H
 
-/**
- * Configure and manage the Analysis
- * @author M. Al-Turany D. Bertini
- * @version 0.1
- * @since 28.02.05
- */
-
 #include "FairField.h"
 #include "FairRootManager.h"
 #include "FairRun.h"
@@ -25,8 +18,14 @@
 class FairField;
 class FairSource;
 class THttpServer;
-class TObject;
 
+/**
+ * Configure and manage the Analysis
+ * \ingroup online fairroot_singleton
+ * @author M. Al-Turany D. Bertini
+ * @version 0.1
+ * @since 28.02.05
+ */
 class FairRunOnline : public FairRun
 {
   public:

Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,9 @@`
`17`	`17`
`18`	`18`	`class FairField;`
`19`	`19`
	`20`	`+/**`
	`21`	`+ * \ingroup base_sim fairroot_singleton`
	`22`	`+ */`
`20`	`23`	`class FairFieldFactory`
`21`	`24`	`{`
`22`	`25`	`public:`