From 5fb806bcb5ac222cd4e574b42809b69be7ca08e2 Mon Sep 17 00:00:00 2001
From: Sterling Harper <smharper@mit.edu>
Date: Mon, 26 Oct 2020 22:15:20 -0600
Subject: [PATCH] Add comments to periodic BC implementation

---
 include/openmc/particle.h | 14 ++++++++++++++
 src/surface.cpp           |  4 ++++
 2 files changed, 18 insertions(+)

diff --git a/include/openmc/particle.h b/include/openmc/particle.h
index f122455fc..f70faa611 100644
--- a/include/openmc/particle.h
+++ b/include/openmc/particle.h
@@ -241,12 +241,26 @@ public:
   void cross_surface();
 
   //! Cross a vacuum boundary condition.
+  //
+  //! \param surf The surface (with the vacuum boundary condition) that the
+  //!   particle struck.
   void cross_vacuum_bc(const Surface& surf);
 
   //! Cross a reflective boundary condition.
+  //
+  //! \param surf The surface (with the reflective boundary condition) that the
+  //!   particle struck.
+  //! \param new_u The direction of the particle after reflection.
   void cross_reflective_bc(const Surface& surf, Direction new_u);
 
   //! Cross a periodic boundary condition.
+  //
+  //! \param surf The surface (with the periodic boundary condition) that the
+  //!   particle struck.
+  //! \param new_r The position of the particle after translation/rotation.
+  //! \param new_u The direction of the particle after translation/rotation.
+  //! \param new_surface The signed index of the surface that the particle will
+  //!   reside on after translation/rotation.
   void cross_periodic_bc(const Surface& surf, Position new_r, Direction new_u,
                          int new_surface);
 
diff --git a/src/surface.cpp b/src/surface.cpp
index af3b0aa37..d3d0cb765 100644
--- a/src/surface.cpp
+++ b/src/surface.cpp
@@ -1148,10 +1148,14 @@ void read_surfaces(pugi::xml_node node)
     Surface& surf1 {*model::surfaces[i_surf]};
     Surface& surf2 {*model::surfaces[j_surf]};
 
+    // Compute the dot product of the surface normals
     Direction norm1 = surf1.normal({0, 0, 0});
     Direction norm2 = surf2.normal({0, 0, 0});
     double dot_prod = norm1.dot(norm2);
 
+    // If the dot product is 1 (to within floating point precision) then the
+    // planes are parallel which indicates a translational periodic boundary
+    // condition.  Otherwise, it is a rotational periodic BC.
     if (std::abs(1.0 - dot_prod) < FP_PRECISION) {
       surf1.bc_ = std::make_shared<TranslationalPeriodicBC>(i_surf, j_surf);
       surf2.bc_ = surf1.bc_;