techincal/cosmetic documentation updates

app/scample.cxx

@@ -12,6 +12,9 @@
 #include "G4DarkBreM/G4DarkBreMModel.h"
 #include "G4DarkBreM/G4APrime.h"
 
+/**
+ * printout how to use g4db-scample
+ */
 void usage() {
   std::cout << 
       "USAGE:\n"
@@ -42,6 +45,14 @@ void usage() {
       << std::flush;
 }
 
+/**
+ * definition of g4db-scample
+ *
+ * We only need to configure the G4DarkBreMModel so
+ * we simply define G4APrime and then construct the model
+ * so we can call G4DarkBreMModel::scample for the input
+ * number of events.
+ */
 int main(int argc, char* argv[]) try {
   std::string output_filename{"scaled.csv"};
   double incident_energy{4};

app/simulate.cxx

@@ -360,7 +360,7 @@ class FindDarkBremProducts : public G4UserTrackingAction {
 };  // FindDarkBremProducts
 
 /**
- * print out how to use this executable
+ * print out how to use g4db-simulate
  */
 void usage() {
   std::cout <<
@@ -394,7 +394,10 @@ void usage() {
 }
 
 /**
- * The executable main for printing out the table.
+ * definition of g4db-simulate
+ *
+ * After parsing the command line arguments, we simply do the 
+ * standard initialization and running procedure for Geant4.
  */
 int main(int argc, char* argv[]) try {
   bool muons{false};

app/xsec_calc.cxx

@@ -10,6 +10,9 @@
 #include "G4DarkBreM/G4DarkBreMModel.h"
 #include "G4DarkBreM/G4APrime.h"
 
+/**
+ * print out how to use g4db-xsec-calc
+ */
 void usage() {
   std::cout <<
     "USAGE:\n"
@@ -29,7 +32,9 @@ void usage() {
 }
 
 /**
- * The executable main for printing out the table.
+ * definition of g4db-xsec-calc
+ *
+ * We use the cross section caching table used within the G4DarkBremsstrahlung process.
  */
 int main(int argc, char* argv[]) try {
   std::string output_filename{"xsec.csv"};

include/G4DarkBreM/ElementXsecCache.h

@@ -32,7 +32,7 @@ class ElementXsecCache {
    * Get the value of the cross section for the input variables
    * and calculate the cross section if it wasn't calculated before.
    *
-   * @raises Exception if no model is available for calculating cross sections
+   * @throws std::runtime_error if no model is available for calculating cross sections
    * @param[in] energy Energy of incident electron [MeV]
    * @param[in] A atomic mass of element [atomic mass units]
    * @param[in] Z atomic number of element [num protons]

include/G4DarkBreM/G4APrime.h

@@ -14,6 +14,19 @@
 class G4String;
 class G4DecayTable;
 
+/**
+ * Formal class representing the A' (a dark photon)
+ *
+ * This class follows the standard prototype for all G4ParticleDefinitions
+ * where a static private member holds onto the single instance of this
+ * particle definition to be shared by everyone. In this case, 
+ * _the first call_ to the accessor function needs to define the A' mass
+ * and then all subsequent calls can access it like normal with that
+ * configured mass.
+ *
+ * This first call to the accessing method should be done in the 
+ * ConstructParticle function of a physics constructor.
+ */
 class G4APrime : public G4ParticleDefinition {
  private:
   /** Reference to single particle definition of A' */

include/G4DarkBreM/G4DarkBreMModel.h

@@ -77,8 +77,8 @@ class G4DarkBreMModel : public PrototypeModel {
    * approximation that both follows the trend produced by MG/ME and is sufficiently quick.
    *
    * ## Electrons
-   * Because the electron mass is small, it typically suffices to calculate the effective photon flux $\chi$ 
-   * once rather than modeling its functional dependence on the $\aprime$ energy and angle, as in the "full" 
+   * Because the electron mass is small, it typically suffices to calculate the effective photon flux \f$\chi\f$ 
+   * once rather than modeling its functional dependence on the \f$\aprime\f$ energy and angle, as in the "full" 
    * WW approximation used below for muons. With electron's low mass, the Improved WW approximation can be used:
    * \f{equation}{
    * \sigma = \frac{pb}{GeV} \chi \int_0^{\min(1-m_e/E_0,1-m_A/E_0)} \frac{d\sigma}{dx}(x)dx
@@ -111,7 +111,7 @@ class G4DarkBreMModel : public PrototypeModel {
    * 
    * ## Muons 
    * The muon's greater mass motivated the use of the "full" WW but including the numerical evaluation of 
-   * $\chi$ at each point in phase space proved to be too costly. 
+   * \f$\chi\f$ at each point in phase space proved to be too costly. 
    * Instead, we use an analytic integration of only elastic form-factor component:
    * 
    * \f{equation}{
@@ -211,7 +211,7 @@ class G4DarkBreMModel : public PrototypeModel {
    * This function loads the directory of LHE files passed
    * into our in-memory library of events to be sampled from.
    *
-   * @param file path to directory of LHE files
+   * @param path path to directory of LHE files
    */
   void SetMadGraphDataLibrary(std::string path);
 
@@ -230,7 +230,7 @@ class G4DarkBreMModel : public PrototypeModel {
     G4double E;
   };
 
-  /*
+  /**
    * Parse an LHE File
    *
    * Parses an LHE file to extract the kinetic energy fraction and pt of the
@@ -273,8 +273,6 @@ class G4DarkBreMModel : public PrototypeModel {
    * This is only used in the ForwardOnly scaling method and is only
    * reached if the event library energies are not appropriately matched
    * with the energy range of particles that are existing in the simulation.
-   *
-   * @TODO make configurable and/or optimize somehow
    */
   unsigned int maxIterations_{10000};
 
@@ -330,7 +328,7 @@ class G4DarkBreMModel : public PrototypeModel {
   /**
    * should we always create a totally new electron when we dark brem?
    *
-   * @TODO make this configurable? I (Tom E) can't think of a reason NOT to have
+   * @note make this configurable? I (Tom E) can't think of a reason NOT to have
    * it... The alternative is to allow Geant4 to decide when to make a new
    * particle by checking if the resulting kinetic energy is below some
    * threshold.

include/G4DarkBreM/PrototypeModel.h

@@ -15,7 +15,6 @@
 namespace g4db {
 
 /**
- * @class G4DarkBremmsstrahlungModel
  * Abstract class representing a model for dark brem.
  *
  * The model is what actually determines two important things: