Add doxygen comments

src/angle_energy.h

@@ -3,6 +3,13 @@
 
 namespace openmc {
 
+//==============================================================================
+//! Abstract type that defines a correlated or uncorrelated angle-energy
+//! distribution that is a function of incoming energy. Each derived type must
+//! implement a sample() method that returns an outgoing energy and
+//! scattering cosine given an incoming energy.
+//==============================================================================
+
 class AngleEnergy {
 public:
   virtual void sample(double E_in, double& E_out, double& mu) const = 0;

src/constants.h

@@ -1,8 +1,8 @@
 //! \file constants.h
 //! A collection of constants
 
-#ifndef CONSTANTS_H
-#define CONSTANTS_H
+#ifndef OPENMC_CONSTANTS_H
+#define OPENMC_CONSTANTS_H
 
 #include <cmath>
 #include <array>
@@ -442,4 +442,4 @@ enum class Interpolation {
 
 } // namespace openmc
 
-#endif // CONSTANTS_H
+#endif // OPENMC_CONSTANTS_H

src/distribution.h

@@ -1,13 +1,17 @@
-#ifndef DISTRIBUTION_H
-#define DISTRIBUTION_H
+//! \file distribution.h
+//! Univariate probability distributions
+
+#ifndef OPENMC_DISTRIBUTION_H
+#define OPENMC_DISTRIBUTION_H
 
 #include <cstddef> // for size_t
 #include <memory> // for unique_ptr
 #include <vector> // for vector
 
-#include "constants.h"
 #include "pugixml.hpp"
 
+#include "constants.h"
+
 namespace openmc {
 
 //==============================================================================
@@ -16,8 +20,8 @@ namespace openmc {
 
 class Distribution {
 public:
-  virtual double sample() const = 0;
   virtual ~Distribution() = default;
+  virtual double sample() const = 0;
 };
 
 //==============================================================================
@@ -30,11 +34,13 @@ public:
   Discrete(const double* x, const double* p, int n);
 
   //! Sample a value from the distribution
+  //! \return Sampled value
   double sample() const;
 private:
-  std::vector<double> x_;
-  std::vector<double> p_;
+  std::vector<double> x_; //!< Possible outcomes
+  std::vector<double> p_; //!< Probability of each outcome
 
+  //! Normalize distribution so that probabilities sum to unity
   void normalize();
 };
 
@@ -48,14 +54,15 @@ public:
   Uniform(double a, double b) : a_{a}, b_{b} {};
 
   //! Sample a value from the distribution
+  //! \return Sampled value
   double sample() const;
 private:
-  double a_;
-  double b_;
+  double a_; //!< Lower bound of distribution
+  double b_; //!< Upper bound of distribution
 };
 
 //==============================================================================
-//! Maxwellian distribution of form c*E*exp(-E/a)
+//! Maxwellian distribution of form c*E*exp(-E/theta)
 //==============================================================================
 
 class Maxwell : public Distribution {
@@ -64,9 +71,10 @@ public:
   Maxwell(double theta) : theta_{theta} { };
 
   //! Sample a value from the distribution
+  //! \return Sampled value
   double sample() const;
 private:
-  double theta_;
+  double theta_; //!< Factor in exponential [eV]
 };
 
 //==============================================================================
@@ -79,10 +87,11 @@ public:
   Watt(double a, double b) : a_{a}, b_{b} { };
 
   //! Sample a value from the distribution
+  //! \return Sampled value
   double sample() const;
 private:
-  double a_;
-  double b_;
+  double a_; //!< Factor in exponential [eV]
+  double b_; //!< Factor in square root [1/eV]
 };
 
 //==============================================================================
@@ -96,6 +105,7 @@ public:
           const double* c=nullptr);
 
   //! Sample a value from the distribution
+  //! \return Sampled value
   double sample() const;
 private:
   std::vector<double> x_; //!< tabulated independent variable
@@ -104,15 +114,15 @@ private:
   Interpolation interp_;  //!< interpolation rule
 
   //! Initialize tabulated probability density function
-  //! @param x Array of values for independent variable
-  //! @param p Array of tabulated probabilities
-  //! @param n Number of tabulated values
+  //! \param x Array of values for independent variable
+  //! \param p Array of tabulated probabilities
+  //! \param n Number of tabulated values
   void init(const double* x, const double* p, std::size_t n,
             const double* c=nullptr);
 };
 
 //==============================================================================
-//!
+//! Equiprobable distribution
 //==============================================================================
 
 class Equiprobable : public Distribution {
@@ -121,16 +131,20 @@ public:
   Equiprobable(const double* x, int n) : x_{x, x+n} { };
 
   //! Sample a value from the distribution
+  //! \return Sampled value
   double sample() const;
 private:
-  std::vector<double> x_;
+  std::vector<double> x_; //! Possible outcomes
 };
 
 
 using UPtrDist = std::unique_ptr<Distribution>;
 
+//! Return univariate probability distribution specified in XML file
+//! \param[in] node XML node representing distribution
+//! \return Unique pointer to distribution
 UPtrDist distribution_from_xml(pugi::xml_node node);
 
 } // namespace openmc
 
-#endif // DISTRIBUTION_H
+#endif // OPENMC_DISTRIBUTION_H

src/distribution_angle.h

@@ -1,3 +1,6 @@
+//! \file distribution_angle.h
+//! Angle distribution dependent on incident particle energy
+
 #ifndef OPENMC_DISTRIBUTION_ANGLE_H
 #define OPENMC_DISTRIBUTION_ANGLE_H
 
@@ -8,18 +11,29 @@
 
 namespace openmc {
 
+//==============================================================================
+//! Angle distribution that depends on incident particle energy
+//==============================================================================
+
 class AngleDistribution {
 public:
   AngleDistribution() = default;
   explicit AngleDistribution(hid_t group);
+
+  //! Sample an angle given an incident particle energy
+  //! \param[in] E Particle energy in [eV]
+  //! \return Cosine of the angle in the range [-1,1]
   double sample(double E) const;
 
+  //! Determine whether angle distribution is empty
+  //! \return Whether distribution is empty
   bool empty() const { return energy_.empty(); }
+
 private:
   std::vector<double> energy_;
   std::vector<UPtrDist> distribution_;
 };
 
-}
+} // namespace openmc
 
 #endif // OPENMC_DISTRIBUTION_ANGLE_H

src/distribution_energy.h

@@ -1,12 +1,16 @@
+//! \file distribution_energy.h
+//! Energy distributions that depend on incident particle energy
+
 #ifndef OPENMC_DISTRIBUTION_ENERGY_H
 #define OPENMC_DISTRIBUTION_ENERGY_H
 
 #include <vector>
 
 #include "xtensor/xtensor.hpp"
+#include "hdf5.h"
+
 #include "constants.h"
 #include "endf.h"
-#include "hdf5.h"
 
 namespace openmc {
 
@@ -22,73 +26,127 @@ public:
   virtual ~EnergyDistribution() = default;
 };
 
+//===============================================================================
+//! Discrete photon energy distribution
+//===============================================================================
+
 class DiscretePhoton : public EnergyDistribution {
 public:
   explicit DiscretePhoton(hid_t group);
+
+  //! Sample energy distribution
+  //! \param[in] E Incident particle energy in [eV]
+  //! \return Sampled energy in [eV]
   double sample(double E) const;
 private:
-  int primary_flag_;
-  double energy_;
-  double A_;
+  int primary_flag_; //!< Indicator of whether the photon is a primary or
+                     //!< non-primary photon.
+  double energy_; //!< Photon energy or binding energy
+  double A_; //!< Atomic weight ratio of the target nuclide
 };
 
+//===============================================================================
+//! Level inelastic scattering distribution
+//===============================================================================
+
 class LevelInelastic : public EnergyDistribution {
 public:
   explicit LevelInelastic(hid_t group);
+
+  //! Sample energy distribution
+  //! \param[in] E Incident particle energy in [eV]
+  //! \return Sampled energy in [eV]
   double sample(double E) const;
 private:
-  double threshold_;
-  double mass_ratio_;
+  double threshold_; //!< Energy threshold in lab, (A + 1)/A * |Q|
+  double mass_ratio_; //!< (A/(A+1))^2
 };
 
+//===============================================================================
+//! An energy distribution represented as a tabular distribution with histogram
+//! or linear-linear interpolation. This corresponds to ACE law 4, which NJOY
+//! produces for a number of ENDF energy distributions.
+//===============================================================================
+
 class ContinuousTabular : public EnergyDistribution {
 public:
   explicit ContinuousTabular(hid_t group);
+
+  //! Sample energy distribution
+  //! \param[in] E Incident particle energy in [eV]
+  //! \return Sampled energy in [eV]
   double sample(double E) const;
 private:
+  //! Outgoing energy for a single incoming energy
   struct CTTable {
-    Interpolation interpolation;
-    int n_discrete;
-    xt::xtensor<double, 1> e_out;
-    xt::xtensor<double, 1> p;
-    xt::xtensor<double, 1> c;
+    Interpolation interpolation; //!< Interpolation law
+    int n_discrete; //!< Number of of discrete energies
+    xt::xtensor<double, 1> e_out; //!< Outgoing energies in [eV]
+    xt::xtensor<double, 1> p; //!< Probability density
+    xt::xtensor<double, 1> c; //!< Cumulative distribution
   };
 
-  int n_region_;
-  std::vector<int> breakpoints_;
-  std::vector<Interpolation> interpolation_;
-  std::vector<double> energy_;
-  std::vector<CTTable> distribution_;
+  int n_region_; //!< Number of inteprolation regions
+  std::vector<int> breakpoints_; //!< Breakpoints between regions
+  std::vector<Interpolation> interpolation_; //!< Interpolation laws
+  std::vector<double> energy_; //!< Incident energy in [eV]
+  std::vector<CTTable> distribution_; //!< Distributions for each incident energy
 };
 
+//===============================================================================
+//! Evaporation spectrum corresponding to ACE law 9 and ENDF File 5, LF=9.
+//===============================================================================
+
 class Evaporation : public EnergyDistribution {
 public:
   explicit Evaporation(hid_t group);
+
+  //! Sample energy distribution
+  //! \param[in] E Incident particle energy in [eV]
+  //! \return Sampled energy in [eV]
   double sample(double E) const;
 private:
-  Tabulated1D theta_;
-  double u_;
+  Tabulated1D theta_; //!< Incoming energy dependent parameter
+  double u_; //!< Restriction energy
 };
 
+//===============================================================================
+//! Energy distribution of neutrons emitted from a Maxwell fission spectrum.
+//! This corresponds to ACE law 7 and ENDF File 5, LF=7.
+//===============================================================================
+
 class MaxwellEnergy : public EnergyDistribution {
 public:
   explicit MaxwellEnergy(hid_t group);
+
+  //! Sample energy distribution
+  //! \param[in] E Incident particle energy in [eV]
+  //! \return Sampled energy in [eV]
   double sample(double E) const;
 private:
-  Tabulated1D theta_;
-  double u_;
+  Tabulated1D theta_; //!< Incoming energy dependent parameter
+  double u_; //!< Restriction energy
 };
 
+//===============================================================================
+//! Energy distribution of neutrons emitted from a Watt fission spectrum. This
+//! corresponds to ACE law 11 and ENDF File 5, LF=11.
+//===============================================================================
+
 class WattEnergy : public EnergyDistribution {
 public:
   explicit WattEnergy(hid_t group);
+
+  //! Sample energy distribution
+  //! \param[in] E Incident particle energy in [eV]
+  //! \return Sampled energy in [eV]
   double sample(double E) const;
 private:
-  Tabulated1D a_;
-  Tabulated1D b_;
-  double u_;
+  Tabulated1D a_; //!< Energy-dependent 'a' parameter
+  Tabulated1D b_; //!< Energy-dependent 'b' parameter
+  double u_; //!< Restriction energy
 };
 
-}
+} // namespace openmc
 
 #endif // OPENMC_DISTRIBUTION_ENERGY_H

src/distribution_spatial.h

@@ -14,8 +14,10 @@ namespace openmc {
 
 class SpatialDistribution {
 public:
-  virtual Position sample() const = 0;
   virtual ~SpatialDistribution() = default;
+
+  //! Sample a position from the distribution
+  virtual Position sample() const = 0;
 };
 
 //==============================================================================
@@ -27,6 +29,7 @@ public:
   explicit CartesianIndependent(pugi::xml_node node);
 
   //! Sample a position from the distribution
+  //! \return Sampled position
   Position sample() const;
 private:
   UPtrDist x_; //!< Distribution of x coordinates
@@ -43,11 +46,12 @@ public:
   explicit SpatialBox(pugi::xml_node node);
 
   //! Sample a position from the distribution
+  //! \return Sampled position
   Position sample() const;
 private:
-  Position lower_left_;
-  Position upper_right_;
-  bool only_fissionable {false};
+  Position lower_left_; //!< Lower-left coordinates of box
+  Position upper_right_; //!< Upper-right coordinates of box
+  bool only_fissionable {false}; //!< Only accept sites in fissionable region?
 };
 
 //==============================================================================
@@ -59,9 +63,10 @@ public:
   explicit SpatialPoint(pugi::xml_node node);
 
   //! Sample a position from the distribution
+  //! \return Sampled position
   Position sample() const;
 private:
-  Position r_;
+  Position r_; //!< Single position at which sites are generated
 };
 
 } // namespace openmc

src/endf.cpp

@@ -12,6 +12,10 @@
 
 namespace openmc {
 
+//==============================================================================
+// Functions
+//==============================================================================
+
 Interpolation int2interp(int i)
 {
   switch (i) {
@@ -140,4 +144,4 @@ double Tabulated1D::operator()(double x) const
   }
 }
 
-} // namespace openmc
+} // namespace openmc

src/endf.h

@@ -1,3 +1,6 @@
+//! \file endf.h
+//! Classes and functions related to the ENDF-6 format
+
 #ifndef OPENMC_ENDF_H
 #define OPENMC_ENDF_H
 
@@ -8,34 +11,66 @@
 
 namespace openmc {
 
+//! Convert integer representing interpolation law to enum
+//! \param[in] i Intereger (e.g. 1=histogram, 2=lin-lin)
+//! \return Corresponding enum value
 Interpolation int2interp(int i);
+
+//! Determine whether MT number corresponds to a fission reaction
+//! \param[in] MT ENDF MT value
+//! \return Whether corresponding reaction is a fission reaction
 bool is_fission(int MT);
 
+//==============================================================================
+//! Abstract one-dimensional function
+//==============================================================================
+
 class Function1D {
 public:
   virtual double operator()(double x) const = 0;
 };
 
+//==============================================================================
+//! One-dimensional function expressed as a polynomial
+//==============================================================================
+
 class Polynomial : public Function1D {
 public:
+  //! Construct polynomial from HDF5 data
+  //! \param[in] dset Dataset containing coefficients
   explicit Polynomial(hid_t dset);
+
+  //! Evaluate the polynomials
+  //! \param[in] x independent variable
+  //! \return Polynomial evaluated at x
   double operator()(double x) const;
 private:
-  std::vector<double> coef_;
+  std::vector<double> coef_; //!< Polynomial coefficients
 };
 
+//==============================================================================
+//! One-dimensional interpolable function
+//==============================================================================
+
 class Tabulated1D : public Function1D {
 public:
   Tabulated1D() = default;
+
+  //! Construct function from HDF5 data
+  //! \param[in] dset Dataset containing tabulated data
   explicit Tabulated1D(hid_t dset);
+
+  //! Evaluate the tabulated function
+  //! \param[in] x independent variable
+  //! \return Function evaluated at x
   double operator()(double x) const;
 private:
-  std::size_t n_regions_ {0};
-  std::vector<int> nbt_;
-  std::vector<Interpolation> int_;
-  std::size_t n_pairs_;
-  std::vector<double> x_;
-  std::vector<double> y_;
+  std::size_t n_regions_ {0}; //!< number of interpolation regions
+  std::vector<int> nbt_; //!< values separating interpolation regions
+  std::vector<Interpolation> int_; //!< interpolation schemes
+  std::size_t n_pairs_; //!< number of (x,y) pairs
+  std::vector<double> x_; //!< values of abscissa
+  std::vector<double> y_; //!< values of ordinate
 };
 
 } // namespace openmc

src/reaction.cpp

@@ -59,7 +59,7 @@ Reaction::Reaction(hid_t group, const std::vector<int>& temperatures)
       if (p.particle_ == ParticleType::neutron) {
         for (auto& d : p.distribution_) {
           auto d_ = dynamic_cast<UncorrelatedAngleEnergy*>(d.get());
-          if (d_) d_->fission_ = true;
+          if (d_) d_->fission() = true;
         }
       }
     }
@@ -141,7 +141,7 @@ double reaction_sample_elastic_mu(Reaction* rx, double E)
   // Check if it is an uncorrelated angle-energy distribution
   auto d_ = dynamic_cast<UncorrelatedAngleEnergy*>(d.get());
   if (d_) {
-    return d_->sampleMu(E);
+    return d_->angle().sample(E);
   } else {
     return 2.0*prn() - 1.0;
   }

src/reaction.h

@@ -1,3 +1,6 @@
+//! \file reaction.h
+//! Data for an incident neutron reaction
+
 #ifndef OPENMC_REACTION_H
 #define OPENMC_REACTION_H
 
@@ -8,10 +11,20 @@
 
 namespace openmc {
 
+//==============================================================================
+//! Data for a single reaction including cross sections (possibly at multiple
+//! temperatures) and reaction products (with secondary angle-energy
+//! distributions)
+//==============================================================================
+
 class Reaction {
 public:
+  //! Construct reaction from HDF5 data
+  //! \param[in] group HDF5 group containing reaction data
+  //! \param[in] temperatures Desired temperatures for cross sections
   explicit Reaction(hid_t group, const std::vector<int>& temperatures);
 
+  //! Cross section at a single temperature
   struct TemperatureXS {
     int threshold;
     std::vector<double> value;
@@ -20,8 +33,8 @@ public:
   int mt_;             //!< ENDF MT value
   double q_value_;     //!< Reaction Q value in [eV]
   bool scatter_in_cm_; //!< scattering system in center-of-mass?
-  std::vector<TemperatureXS> xs_;
-  std::vector<ReactionProduct> products_;
+  std::vector<TemperatureXS> xs_; //!< Cross section at each temperature
+  std::vector<ReactionProduct> products_; //!< Reaction products
 };
 
 //==============================================================================
@@ -47,6 +60,6 @@ extern "C" {
   int reaction_xs_threshold(Reaction* xs, int temperature);
 }
 
-}
+} // namespace openmc
 
 #endif // OPENMC_REACTION_H

src/reaction_product.cpp

@@ -12,6 +12,10 @@
 
 namespace openmc {
 
+//==============================================================================
+// ReactionProduct implementation
+//==============================================================================
+
 ReactionProduct::ReactionProduct(hid_t group)
 {
   // Read particle type
@@ -100,4 +104,4 @@ void ReactionProduct::sample(double E_in, double& E_out, double& mu) const
   }
 }
 
-}
+}

src/reaction_product.h

@@ -1,3 +1,6 @@
+//! \file reaction_product.h
+//! Data for a reaction product
+
 #ifndef OPENMC_REACTION_PRODUCT_H
 #define OPENMC_REACTION_PRODUCT_H
 
@@ -11,11 +14,17 @@
 
 namespace openmc {
 
+//==============================================================================
+//! Data for a reaction product including its yield and angle-energy
+//! distributions, each of which has a given probability of occurring for a
+//! given incoming energy. In general, most products only have one angle-energy
+//! distribution, but for some cases (e.g., (n,2n) in certain nuclides) multiple
+//! distinct distributions exist.
+//==============================================================================
+
 class ReactionProduct {
 public:
-  explicit ReactionProduct(hid_t group);
-  void sample(double E_in, double& E_out, double& mu) const;
-
+  //! Emission mode for product
   enum class EmissionMode {
     prompt,  // Prompt emission of secondary particle
     total,   // Delayed emission of secondary particle
@@ -24,14 +33,24 @@ public:
 
   using Secondary = std::unique_ptr<AngleEnergy>;
 
-  ParticleType particle_;
-  EmissionMode emission_mode_;
-  double decay_rate_;
-  std::unique_ptr<Function1D> yield_;
-  std::vector<Tabulated1D> applicability_;
-  std::vector<Secondary> distribution_;
+  //! Construct reaction product from HDF5 data
+  //! \param[in] group HDF5 group containing data
+  explicit ReactionProduct(hid_t group);
+
+  //! Sample an outgoing angle and energy
+  //! \param[in] E_in Incoming energy in [eV]
+  //! \param[out] E_out Outgoing energy in [eV]
+  //! \param[out] mu Outgoing cosine with respect to current direction
+  void sample(double E_in, double& E_out, double& mu) const;
+
+  ParticleType particle_; //!< Particle type
+  EmissionMode emission_mode_; //!< Emission mode
+  double decay_rate_; //!< Decay rate (for delayed neutron precursors) in [1/s]
+  std::unique_ptr<Function1D> yield_; //!< Yield as a function of energy
+  std::vector<Tabulated1D> applicability_; //!< Applicability of distribution
+  std::vector<Secondary> distribution_; //!< Secondary angle-energy distribution
 };
 
-}
+} // namespace opemc
 
 #endif // OPENMC_REACTION_PRODUCT_H

src/search.h

@@ -1,3 +1,6 @@
+//! \file search.h
+//! Search algorithms
+
 #ifndef OPENMC_SEARCH_H
 #define OPENMC_SEARCH_H
 
@@ -5,6 +8,8 @@
 
 namespace openmc {
 
+//! Perform binary search
+
 template<class It, class T>
 typename std::iterator_traits<It>::difference_type
 lower_bound_index(It first, It last, const T& value)
@@ -13,6 +18,6 @@ lower_bound_index(It first, It last, const T& value)
   return (index == last) ? -1 : index - first;
 }
 
-}
+} // namespace openmc
 
-#endif // OPENMC_SEARCH_H
+#endif // OPENMC_SEARCH_H

src/secondary_correlated.cpp

@@ -14,6 +14,10 @@
 
 namespace openmc {
 
+//==============================================================================
+//! CorrelatedAngleEnergy implementation
+//==============================================================================
+
 CorrelatedAngleEnergy::CorrelatedAngleEnergy(hid_t group)
 {
   // Open incoming energy dataset
@@ -237,4 +241,4 @@ void CorrelatedAngleEnergy::sample(double E_in, double& E_out, double& mu) const
   }
 }
 
-}
+} // namespace openmc

src/secondary_correlated.h

@@ -1,3 +1,6 @@
+//! \file secondary_correlated.h
+//! Correlated angle-energy distribution
+
 #ifndef OPENMC_SECONDARY_CORRELATED_H
 #define OPENMC_SECONDARY_CORRELATED_H
 
@@ -11,27 +14,39 @@
 
 namespace openmc {
 
+//==============================================================================
+//! Correlated angle-energy distribution corresponding to ACE law 61 and ENDF
+//! File 6, LAW=1, LANG!=2.
+//==============================================================================
+
 class CorrelatedAngleEnergy : public AngleEnergy {
 public:
   explicit CorrelatedAngleEnergy(hid_t group);
+
+  //! Sample distribution for an angle and energy
+  //! \param[in] E_in Incoming energy in [eV]
+  //! \param[out] E_out Outgoing energy in [eV]
+  //! \param[out] mu Outgoing cosine with respect to current direction
   void sample(double E_in, double& E_out, double& mu) const;
 private:
+  //! Outgoing energy/angle at a single incoming energy
   struct CorrTable {
-    int n_discrete;
-    Interpolation interpolation;
-    xt::xtensor<double, 1> e_out;
-    xt::xtensor<double, 1> p;
-    xt::xtensor<double, 1> c;
-    std::vector<UPtrDist> angle;
+    int n_discrete; //!< Number of discrete lines
+    Interpolation interpolation; //!< Interpolation law
+    xt::xtensor<double, 1> e_out; //!< Outgoing energies [eV]
+    xt::xtensor<double, 1> p; //!< Probability density
+    xt::xtensor<double, 1> c; //!< Cumulative distribution
+    std::vector<UPtrDist> angle; //!< Angle distribution
   };
 
-  int n_region_;
-  std::vector<int> breakpoints_;
-  std::vector<Interpolation> interpolation_;
-  std::vector<double> energy_;
-  std::vector<CorrTable> distribution_;
+  int n_region_; //!< Number of interpolation regions
+  std::vector<int> breakpoints_; //!< Breakpoints between regions
+  std::vector<Interpolation> interpolation_; //!< Interpolation laws
+  std::vector<double> energy_; //!< Energies [eV] at which distributions
+                               //!< are tabulated
+  std::vector<CorrTable> distribution_; //!< Distribution at each energy
 };
 
-}
+} // namespace openmc
 
 #endif // OPENMC_SECONDARY_CORRELATED_H

src/secondary_kalbach.cpp

@@ -14,6 +14,10 @@
 
 namespace openmc {
 
+//==============================================================================
+//! KalbachMann implementation
+//==============================================================================
+
 KalbachMann::KalbachMann(hid_t group)
 {
   // Open incoming energy dataset
@@ -216,4 +220,4 @@ void KalbachMann::sample(double E_in, double& E_out, double& mu) const
   }
 }
 
-}
+}

src/secondary_kalbach.h

@@ -1,3 +1,6 @@
+//! \file secondary_kalbach.h
+//! Kalbach-Mann angle-energy distribution
+
 #ifndef OPENMC_SECONDARY_KALBACH_H
 #define OPENMC_SECONDARY_KALBACH_H
 
@@ -11,28 +14,41 @@
 
 namespace openmc {
 
+//==============================================================================
+//! Correlated angle-energy distribution with the angular distribution
+//! represented using Kalbach-Mann systematics. This corresponds to ACE law 44
+//! and ENDF File 6, LAW=1, LANG=2.
+//==============================================================================
+
 class KalbachMann : public AngleEnergy {
 public:
   explicit KalbachMann(hid_t group);
+
+  //! Sample distribution for an angle and energy
+  //! \param[in] E_in Incoming energy in [eV]
+  //! \param[out] E_out Outgoing energy in [eV]
+  //! \param[out] mu Outgoing cosine with respect to current direction
   void sample(double E_in, double& E_out, double& mu) const;
 private:
+  //! Outgoing energy/angle at a single incoming energy
   struct KMTable {
-    int n_discrete;
-    Interpolation interpolation;
-    xt::xtensor<double, 1> e_out;
-    xt::xtensor<double, 1> p;
-    xt::xtensor<double, 1> c;
-    xt::xtensor<double, 1> r;
-    xt::xtensor<double, 1> a;
+    int n_discrete; //!< Number of discrete lines
+    Interpolation interpolation; //!< Interpolation law
+    xt::xtensor<double, 1> e_out; //!< Outgoing energies [eV]
+    xt::xtensor<double, 1> p; //!< Probability density
+    xt::xtensor<double, 1> c; //!< Cumulative distribution
+    xt::xtensor<double, 1> r; //!< Pre-compound fraction
+    xt::xtensor<double, 1> a; //!< Parameterized function
   };
 
-  int n_region_;
-  std::vector<int> breakpoints_;
-  std::vector<Interpolation> interpolation_;
-  std::vector<double> energy_;
-  std::vector<KMTable> distribution_;
+  int n_region_; //!< Number of interpolation regions
+  std::vector<int> breakpoints_; //!< Breakpoints between regions
+  std::vector<Interpolation> interpolation_; //!< Interpolation laws
+  std::vector<double> energy_; //!< Energies [eV] at which distributions
+                               //!< are tabulated
+  std::vector<KMTable> distribution_; //!< Distribution at each energy
 };
 
-}
+} // namespace openmc
 
 #endif // OPENMC_SECONDARY_KALBACH_H

src/secondary_nbody.cpp

@@ -62,4 +62,4 @@ void NBodyPhaseSpace::sample(double E_in, double& E_out, double& mu) const
   E_out = E_max * v;
 }
 
-}
+} // namespace openmc

src/secondary_nbody.h

@@ -1,3 +1,6 @@
+//! \file secondary_nbody.h
+//! N-body phase space distribution
+
 #ifndef OPENMC_SECONDARY_NBODY_H
 #define OPENMC_SECONDARY_NBODY_H
 
@@ -7,17 +10,28 @@
 
 namespace openmc {
 
+//==============================================================================
+//! Angle-energy distribution for particles emitted from neutron and
+//! charged-particle reactions. This corresponds to ACE law 66 and ENDF File 6,
+//! LAW=6.
+//==============================================================================
+
 class NBodyPhaseSpace : public AngleEnergy {
 public:
   explicit NBodyPhaseSpace(hid_t group);
+
+  //! Sample distribution for an angle and energy
+  //! \param[in] E_in Incoming energy in [eV]
+  //! \param[out] E_out Outgoing energy in [eV]
+  //! \param[out] mu Outgoing cosine with respect to current direction
   void sample(double E_in, double& E_out, double& mu) const;
 private:
-  int n_bodies_;
-  double mass_ratio_;
-  double A_;
-  double Q_;
+  int n_bodies_; //!< Number of particles distributed
+  double mass_ratio_; //!< Total mass of particles [neutron mass]
+  double A_; //!< Atomic weight ratio
+  double Q_; //!< Reaction Q-value [eV]
 };
 
-}
+} // namespace openmc
 
 #endif // OPENMC_SECONDARY_NBODY_H

src/secondary_uncorrelated.cpp

@@ -71,4 +71,4 @@ UncorrelatedAngleEnergy::sample(double E_in, double& E_out, double& mu) const
   E_out = energy_->sample(E_in);
 }
 
-}
+} // namespace openmc

src/secondary_uncorrelated.h

@@ -1,3 +1,6 @@
+//! \file secondary_uncorrelated.h
+//! Uncorrelated angle-energy distribution
+
 #ifndef OPENMC_SECONDARY_UNCORRELATED_H
 #define OPENMC_SECONDARY_UNCORRELATED_H
 
@@ -11,18 +14,31 @@
 
 namespace openmc {
 
+//==============================================================================
+//! Uncorrelated angle-energy distribution. This corresponds to when an energy
+//! distribution is given in ENDF File 5/6 and an angular distribution is given
+//! in ENDF File 4.
+//==============================================================================
+
 class UncorrelatedAngleEnergy : public AngleEnergy {
 public:
   explicit UncorrelatedAngleEnergy(hid_t group);
-  void sample(double E_in, double& E_out, double& mu) const;
-  double sampleMu(double E) const { return angle_.sample(E); }
 
-  bool fission_ {false};
+  //! Sample distribution for an angle and energy
+  //! \param[in] E_in Incoming energy in [eV]
+  //! \param[out] E_out Outgoing energy in [eV]
+  //! \param[out] mu Outgoing cosine with respect to current direction
+  void sample(double E_in, double& E_out, double& mu) const;
+
+  // Accessors
+  AngleDistribution& angle() { return angle_; }
+  bool& fission() { return fission_; }
 private:
-  AngleDistribution angle_;
-  std::unique_ptr<EnergyDistribution> energy_;
+  AngleDistribution angle_; //!< Angle distribution
+  std::unique_ptr<EnergyDistribution> energy_; //!< Energy distribution
+  bool fission_ {false}; //!< Whether distribution is use for fission
 };
 
-}
+} // namespace openmc
 
 #endif // OPENMC_SECONDARY_UNCORRELATED_H