work on documentation

corsika/framework/process/BaseProcess.hpp

@@ -13,7 +13,7 @@ namespace corsika {
   class TDerived; // fwd decl
 
   /**
-     \class BaseProcess
+     Each process in C8 must derive from BaseProcess
 
      The structural base type of a process object in a
      ProcessSequence. Both, the ProcessSequence and all its elements

corsika/framework/process/ContinuousProcess.hpp

@@ -14,7 +14,7 @@ n/*
 namespace corsika {
 
   /**
-     \class ContinuousProcess
+     Processes with continuous effects along a particle Trajectory
 
      The structural base type of a process object in a
      ProcessSequence. Both, the ProcessSequence and all its elements

corsika/framework/process/DecayProcess.hpp

@@ -14,7 +14,7 @@ n/*
 namespace corsika {
 
   /**
-     \class DecayProcess
+     Process decribing the decay of particles
 
      The structural base type of a process object in a
      ProcessSequence. Both, the ProcessSequence and all its elements

corsika/framework/process/InteractionProcess.hpp

@@ -14,7 +14,7 @@ n/*
 namespace corsika {
 
   /**
-     \class InteractionProcess
+     Process describing the interaction of particles
 
      The structural base type of a process object in a
      ProcessSequence. Both, the ProcessSequence and all its elements

corsika/framework/process/NullModel.hpp

@@ -12,6 +12,10 @@
 
 namespace corsika {
 
+  /**
+   * Process that does nothing
+   */
+  
   class NullModel : public BaseProcess<NullModel> {
 
   public:

corsika/framework/process/ProcessReturn.hpp

@@ -8,9 +8,13 @@ n/*
 
 #pragma once
 
+/**
+ * \file ProcessReturn.hpp
+ **/
+
 namespace corsika {
 
-  /**
+  /**   
      since in a process sequence many status updates can accumulate
      for a single particle, this enum should define only bit-flags
      that can be accumulated easily with "|="

corsika/framework/process/ProcessSequence.hpp

@@ -8,6 +8,10 @@ n/*
 
 #pragma once
 
+/**
+ * \file ProcessSequence.hpp
+ */
+
 #include <corsika/framework/process/BaseProcess.hpp>
 #include <corsika/framework/process/ProcessTraits.hpp>
 #include <corsika/framework/process/BoundaryCrossingProcess.hpp>
@@ -24,22 +28,22 @@ namespace corsika {
 
   /**
    *
-     \class ProcessSequence
-
-     A compile time static list of processes. The compiler will
-     generate a new type based on template logic containing all the
-     elements provided by the user.
-
-     TProcess1 and TProcess2 must both be derived from BaseProcess,
-     and are both references if possible (lvalue), otherwise (rvalue)
-     they are just classes. This allows us to handle both, rvalue as
-     well as lvalue Processes in the ProcessSequence.
-
-     The sequence, and the processes use CRTP.
-
-     \todo There are several FIXME's in the ProcessSequence.inl due to
-     outstanding migration of SecondaryView::parent()
-   */
+   *  Definition of a static process list/sequence
+   *
+   *  A compile time static list of processes. The compiler will
+   *  generate a new type based on template logic containing all the
+   *  elements provided by the user.
+   *
+   *  TProcess1 and TProcess2 must both be derived from BaseProcess,
+   *  and are both references if possible (lvalue), otherwise (rvalue)
+   *  they are just classes. This allows us to handle both, rvalue as
+   *  well as lvalue Processes in the ProcessSequence.
+   *
+   *  The sequence, and the processes use CRTP.
+   *
+   *  \todo There are several FIXME's in the ProcessSequence.inl due to
+   *  outstanding migration of SecondaryView::parent()
+   **/
 
   template <typename TProcess1, typename TProcess2 = NullModel>
   class ProcessSequence : public BaseProcess<ProcessSequence<TProcess1, TProcess2>> {
@@ -61,10 +65,27 @@ namespace corsika {
                   "can only use process derived from BaseProcess in "
                   "ProcessSequence, for Process 2");
 
-    TProcess1 A_; // this is a reference, if possible
-    TProcess2 B_; // this is a reference, if possible
+    TProcess1 A_; /// process/list A, this is a reference, if possible
+    TProcess2 B_; /// process/list B, this is a reference, if possible
 
   public:
+    // resource management
+    ProcessSequence() = delete; // only initialized objects
+    ProcessSequence(ProcessSequence const&) = default;
+    ProcessSequence(ProcessSequence&&) = default;
+    ProcessSequence& operator=(ProcessSequence const&) = default;
+    ~ProcessSequence() = default;
+
+    /**
+     * Only valid user constructor will create fully initialized object
+     *
+     * ProcessSequence supports and encourages move semantics. You can
+     * use object, l-value references or r-value references to
+     * construct sequences.
+     *
+     * \param in_A process/list A
+     * \param in_A process/list B
+     **/        
     ProcessSequence(TProcess1 in_A, TProcess2 in_B)
         : A_(in_A)
         , B_(in_B) {}
@@ -128,7 +149,7 @@ namespace corsika {
   };
 
   /**
-   * \function make_sequence
+   * Factory function to create ProcessSequence
    *
    * to construct ProcessSequences in a flexible and dynamic way the
    * `sequence` factory functions are provided
@@ -145,6 +166,9 @@ namespace corsika {
    * The sequence function checks that all its arguments are all of
    * types derived from BaseProcess. Also the ProcessSequence itself
    * is derived from type BaseProcess
+   *
+   * \param vA needs to derive from BaseProcess or ProcessSequence
+   * \param vB paramter-pack, needs to derive BaseProcess or ProcessSequence
    **/
 
   template <typename... TProcesses, typename TProcess1>
@@ -158,6 +182,14 @@ namespace corsika {
         vA, make_sequence(std::forward<TProcesses>(vBs)...));
   }
 
+ /**
+   * Factory function to create ProcessSequence
+   *
+   * specialization for two input objects (no paramter pack in vB).
+   *
+   * \param vA needs to derive from BaseProcess or ProcessSequence
+   * \param vB needs to derive BaseProcess or ProcessSequence
+   **/
   template <typename TProcess1, typename TProcess2>
   inline typename std::enable_if_t<
       std::is_base_of_v<BaseProcess<typename std::decay_t<TProcess1>>,
@@ -170,10 +202,12 @@ namespace corsika {
   }
 
   /**
-   * \ function make_sequence
+   * Factory function to create ProcessSequence from a single BaseProcess
    *
    * also allow a single Process in ProcessSequence, accompany by
    * `NullModel`
+   *
+   * \param vA needs to derive from BaseProcess or ProcessSequence
    **/
   template <typename TProcess>
   inline typename std::enable_if_t<
@@ -185,8 +219,6 @@ namespace corsika {
   }
 
   /**
-   * \class is_process_sequence
-   *
    * traits marker to identify objectas ProcessSequence
    **/
   template <typename TProcess1, typename TProcess2>

corsika/framework/process/ProcessTraits.hpp

@@ -8,6 +8,10 @@
 
 #pragma once
 
+/**
+ * \file ProcessTraits.hpp
+ */
+
 #include <type_traits>
 
 namespace corsika {

corsika/framework/process/SecondariesProcess.hpp

@@ -14,7 +14,7 @@
 namespace corsika {
 
   /**
-     \class SecondariesProcess
+     Process that modifies a list of secondaries of other processes
 
      The structural base type of a process object in a
      ProcessSequence. Both, the ProcessSequence and all its elements

corsika/framework/process/StackProcess.hpp

@@ -14,7 +14,7 @@
 namespace corsika {
 
   /**
-     \class StackProcess
+     Process to act on the entire particle stack
 
      The structural base type of a process object in a
      ProcessSequence. Both, the ProcessSequence and all its elements

corsika/framework/process/SwitchProcessSequence.hpp

@@ -8,6 +8,10 @@
 
 #pragma once
 
+/**
+ * \file SwitchProcessSequence.hpp
+ **/
+
 #include <corsika/framework/process/BaseProcess.hpp>
 #include <corsika/framework/process/ProcessTraits.hpp>
 #include <corsika/framework/process/BoundaryCrossingProcess.hpp>
@@ -25,14 +29,16 @@
 
 namespace corsika {
 
-  // enum for the process switch selection: identify if First or
-  // Second process branch should be used.
+  /**
+   * enum for the process switch selection: identify if First or
+   * Second process branch should be used.
+   **/
   enum class SwitchResult { First, Second };
 
   /**
-     \class SwitchProcessSequence
+     Class to switch between two process branches
 
-     A compile time static list of processes that uses an internal
+     A compile-time static list of processes that uses an internal
      TSelect class to switch between different versions of processes
      (or process sequence).
 
@@ -51,7 +57,7 @@ namespace corsika {
      since this makes no sense. The StackProcess acts on an entire
      particle stack and not on indiviidual particles.
 
-     \comment See also class ProcessSequence
+     See also class \sa ProcessSequence
   **/
 
   template <typename TProcess1, typename TProcess2, typename TSelect>
@@ -87,12 +93,25 @@ namespace corsika {
                   "cannot use StackProcess in SwitchProcessSequence, remove from "
                   "ProcessSequence 2");
 
-    TSelect select_; // this is a reference, if possible
-
-    TProcess1 A_; // this is a reference, if possible
-    TProcess2 B_; // this is a reference, if possible
-
   public:
+    // resource management
+    SwitchProcessSequence() = delete; // only initialized objects
+    SwitchProcessSequence(SwitchProcessSequence const&) = default;
+    SwitchProcessSequence(SwitchProcessSequence&&) = default;
+    SwitchProcessSequence& operator=(SwitchProcessSequence const&) = default;
+    ~SwitchProcessSequence() = default;
+
+    /**
+     * Only valid user constructor will create fully initialized object
+     *
+     * SwitchProcessSequence supports and encourages move semantics. You can
+     * use object, l-value references or r-value references to
+     * construct sequences.
+     *
+     * \param in_A process branch A
+     * \param in_A process branch B
+     * \param sel functor to swtich between branch A and B
+     **/    
     SwitchProcessSequence(TProcess1 in_A, TProcess2 in_B, TSelect sel)
         : select_(sel)
         , A_(in_A)
@@ -138,10 +157,16 @@ namespace corsika {
     inline ProcessReturn selectDecay(
         TSecondaryView& view, [[maybe_unused]] InverseTimeType decay_inv_select,
         [[maybe_unused]] InverseTimeType decay_inv_sum = InverseTimeType::zero());
+
+  private:
+    TSelect select_; /// selector functor to switch between branch a and b, this is a
+                     /// reference, if possible
+
+    TProcess1 A_; /// process branch a, this is a reference, if possible
+    TProcess2 B_; /// process branch b, this is a reference, if possible
   };
 
   /**
-   * \function make_select
    *
    * the functin `make_select(proc1,proc1,selector)` assembles many
    * BaseProcesses, and ProcessSequences into a SwitchProcessSequence,