From f060b4eb72a2952e2a1b6b7529953611b58d6857 Mon Sep 17 00:00:00 2001
From: Sterling Harper <smharper@mit.edu>
Date: Sun, 18 Oct 2020 16:39:19 -0600
Subject: [PATCH] Add docstrings to boundary_condition.h

---
 include/openmc/boundary_condition.h | 45 ++++++++++++++++++++++++++---
 1 file changed, 41 insertions(+), 4 deletions(-)

diff --git a/include/openmc/boundary_condition.h b/include/openmc/boundary_condition.h
index caf83b6117..d40c645695 100644
--- a/include/openmc/boundary_condition.h
+++ b/include/openmc/boundary_condition.h
@@ -5,22 +5,33 @@
 
 namespace openmc {
 
-//==============================================================================
-// Global variables
-//==============================================================================
-
+// Forward declare some types used in function arguments.
 class Particle;
 class Surface;
 
+//==============================================================================
+//! A class that tells particles what to do after they strike an outer boundary.
+//==============================================================================
+
 class BoundaryCondition
 {
 public:
+  //! Perform tracking operations for a particle that strikes the boundary.
+  //! \param p The particle that struck the boundary.  This class is not meant
+  //!   to directly modify anything about the particle, but it will do so
+  //!   indirectly by calling the particle's appropriate cross*bc function.
+  //! \param surf The specific surface on the boundary the particle struck.
   virtual void
   handle_particle(Particle& p, const Surface& surf) const = 0;
 
+  //! Return a string classification of this BC.
   virtual std::string type() const = 0;
 };
 
+//==============================================================================
+//! A BC that kills particles, indicating they left the problem.
+//==============================================================================
+
 class VacuumBC : public BoundaryCondition
 {
 public:
@@ -30,6 +41,10 @@ public:
   std::string type() const override {return "vacuum";}
 };
 
+//==============================================================================
+//! A BC that returns particles via specular reflection.
+//==============================================================================
+
 class ReflectiveBC : public BoundaryCondition
 {
 public:
@@ -39,6 +54,10 @@ public:
   std::string type() const override {return "reflective";}
 };
 
+//==============================================================================
+//! A BC that returns particles via diffuse reflection.
+//==============================================================================
+
 class WhiteBC : public BoundaryCondition
 {
 public:
@@ -48,6 +67,10 @@ public:
   std::string type() const override {return "white";}
 };
 
+//==============================================================================
+//! A BC that moves particles to another part of the problem.
+//==============================================================================
+
 class PeriodicBC : public BoundaryCondition
 {
 public:
@@ -62,6 +85,10 @@ protected:
   int j_surf_;
 };
 
+//==============================================================================
+//! A BC that moves particles to another part of the problem without rotation.
+//==============================================================================
+
 class TranslationalPeriodicBC : public PeriodicBC
 {
 public:
@@ -71,9 +98,16 @@ public:
   handle_particle(Particle& p, const Surface& surf) const override;
 
 protected:
+  //! Vector along which incident particles will be moved
   Position translation_;
 };
 
+//==============================================================================
+//! A BC that rotates particles about a global axis.
+//
+//! Currently only rotations about the z-axis are supported.
+//==============================================================================
+
 class RotationalPeriodicBC : public PeriodicBC
 {
 public:
@@ -83,7 +117,10 @@ public:
   handle_particle(Particle& p, const Surface& surf) const override;
 
 protected:
+  //! Angle about the axis by which particle coordinates will be rotated
   double angle_;
+
+  //! Whether or not the boundary normal vector reverses after a rotation
   bool aligned_normals_;
 };