Address @smharper comments on #1169

include/openmc/hdf5_interface.h

@@ -223,6 +223,10 @@ read_attribute(hid_t obj_id, const char* name, std::vector<std::string>& vec)
 // Templates/overloads for read_dataset and related methods
 //==============================================================================
 
+// Template for scalars. We need to be careful that the compiler does not use
+// this version of read_dataset for vectors, arrays, or other non-scalar types.
+// enable_if_t allows us to conditionally remove the function from overload
+// resolution when the type T doesn't meet a certain criterion.
 template<typename T> inline
 std::enable_if_t<std::is_scalar<std::decay_t<T>>::value>
 read_dataset(hid_t obj_id, const char* name, T& buffer, bool indep=false)

include/openmc/particle.h

@@ -148,10 +148,10 @@ extern "C" {
     //! \param src Source site data
     void from_source(const Bank* src);
 
-    //! Transport the particle
+    //! Transport a particle from birth to death
     void transport();
 
-    //! Cross a surface
+    //! Cross a surface and handle boundary conditions
     void cross_surface();
 
     //! mark a particle as lost and create a particle restart file

include/openmc/simulation.h

@@ -36,6 +36,7 @@ extern "C" bool need_depletion_rx; //!< need to calculate depletion rx?
 extern "C" int restart_batch;   //!< batch at which a restart job resumed
 extern "C" bool satisfy_triggers; //!< have tally triggers been satisfied?
 extern "C" int total_gen;        //!< total number of generations simulated
+extern "C" double total_weight;  //!< Total source weight in a batch
 extern "C" int64_t work;         //!< number of particles per process
 
 extern std::vector<double> k_generation;

include/openmc/tallies/derivative.h

@@ -35,8 +35,20 @@ void
 apply_derivative_to_score(const Particle* p, int i_tally, int i_nuclide,
   double atom_density, int score_bin, double& score);
 
+//! Adjust diff tally flux derivatives for a particle scattering event.
+//
+//! Note that this subroutine will be called after absorption events in
+//! addition to scattering events, but any flux derivatives scored after an
+//! absorption will never be tallied.  The paricle will be killed before any
+//! further tallies are scored.
+//
+//! \param p The particle being tracked
 void score_collision_derivative(const Particle* p);
 
+//! Adjust diff tally flux derivatives for a particle tracking event.
+//
+//! \param p The particle being tracked
+//! \param distance The distance in [cm] traveled by the particle
 void score_track_derivative(const Particle* p, double distance);
 
 //! Set the flux derivatives on differential tallies to zero.

include/openmc/tallies/tally.h

@@ -101,8 +101,6 @@ private:
 // Global variable declarations
 //==============================================================================
 
-extern "C" double total_weight;
-
 namespace model {
 
 extern std::vector<std::unique_ptr<Tally>> tallies;

include/openmc/tallies/tally_scoring.h

@@ -50,14 +50,45 @@ private:
 // Non-member functions
 //==============================================================================
 
+//! Score tallies using a 1 / Sigma_t estimate of the flux.
+//
+//! This is triggered after every collision.  It is invalid for tallies that
+//! require post-collison information because it can score reactions that didn't
+//! actually occur, and we don't a priori know what the outcome will be for
+//! reactions that we didn't sample.  It is assumed the material is not void
+//! since collisions do not occur in voids.
+//
+//! \param p The particle being tracked
 void score_collision_tally(const Particle* p);
 
+//! Score tallies based on a simple count of events (for continuous energy).
+//
+//! Analog tallies are triggered at every collision, not every event.
+//
+//! \param p The particle being tracked
 void score_analog_tally_ce(const Particle* p);
 
+//! Score tallies based on a simple count of events (for multigroup).
+//
+//! Analog tallies are triggered at every collision, not every event.
+//
+//! \param p The particle being tracked
 void score_analog_tally_mg(const Particle* p);
 
+//! Score tallies using a tracklength estimate of the flux.
+//
+//! This is triggered at every event (surface crossing, lattice crossing, or
+//! collision) and thus cannot be done for tallies that require post-collision
+//! information.
+//
+//! \param p The particle being tracked
+//! \param distance The distance in [cm] traveled by the particle
 void score_tracklength_tally(const Particle* p, double distance);
 
+//! Score surface or mesh-surface tallies for particle currents.
+//
+//! \param p The particle being tracked
+//! \param tallies A vector of tallies to score to
 void score_surface_tally(const Particle* p, const std::vector<int>& tallies);
 
 } // namespace openmc