From 4b6402104e0cbccc9cfdd23aeec78e85f5e8d595 Mon Sep 17 00:00:00 2001
From: Sterling Harper <smharper@mit.edu>
Date: Thu, 14 Dec 2017 16:19:26 -0500
Subject: [PATCH] Switch C++ RNG to Doxygen-style comments

---
 src/random_lcg.h | 46 ++++++++++++++++++++++++++++++++--------------
 1 file changed, 32 insertions(+), 14 deletions(-)

diff --git a/src/random_lcg.h b/src/random_lcg.h
index ca8dfd826..04191254f 100644
--- a/src/random_lcg.h
+++ b/src/random_lcg.h
@@ -15,45 +15,57 @@ extern "C" const int STREAM_URR_PTABLE;
 extern "C" const int STREAM_VOLUME;
 
 //==============================================================================
-// PRN generates a pseudo-random number using a linear congruential generator.
+//! Generate a pseudo-random number using a linear congruential generator.
+//! @return A random number between 0 and 1
 //==============================================================================
 
 extern "C" double prn();
 
 //==============================================================================
-// FUTURE_PRN generates a pseudo-random number which is 'n' times ahead from the
-// current seed.
+//! Generate a random number which is 'n' times ahead from the current seed.
+//!
+//! The result of this function will be the same as the result from calling
+//! `prn()` 'n' times.
+//! @param n The number of RNG seeds to skip ahead by
+//! @return A random number between 0 and 1
 //==============================================================================
 
 extern "C" double future_prn(int64_t n);
 
 //==============================================================================
-// SET_PARTICLE_SEED sets the seed to a unique value based on the ID of the
-// particle.
+//! Set the RNG seed to a unique value based on the ID of the particle.
+//! @param id The particle ID
 //==============================================================================
 
 extern "C" void set_particle_seed(int64_t id);
 
 //==============================================================================
-// ADVANCE_PRN_SEED advances the random number seed 'n' times from the current
-// seed.
+//! Advance the random number seed 'n' times from the current seed.
+//! @param n The number of RNG seeds to skip ahead by
 //==============================================================================
 
 extern "C" void advance_prn_seed(int64_t n);
 
 //==============================================================================
-// FUTURE_SEED advances the random number seed 'skip' times. This is usually
-// used to skip a fixed number of random numbers (the stride) so that a given
-// particle always has the same starting seed regardless of how many processors
-// are used.
+//! Advance a random number seed 'n' times.
+//!
+//! This is usually used to skip a fixed number of random numbers (the stride)
+//! so that a given particle always has the same starting seed regardless of
+//! how many processors are used.
+//! @param n The number of RNG seeds to skip ahead by
+//! @param seed The starting to seed to advance from
 //==============================================================================
 
 uint64_t future_seed(uint64_t n, uint64_t seed);
 
 //==============================================================================
-// PRN_SET_STREAM changes the random number stream. If random numbers are needed
-// in routines not used directly for tracking (e.g. physics), this allows the
-// numbers to be generated without affecting reproducibility of the physics.
+//! Switch the RNG to a different stream of random numbers.
+//!
+//! If random numbers are needed in routines not used directly for tracking
+//! (e.g. physics), this allows the numbers to be generated without affecting
+//! reproducibility of the physics.
+//! @param n The RNG stream to switch to. Use the constants such as
+//! `STREAM_TRACKING` and `STREAM_TALLIES` for this argument.
 //==============================================================================
 
 extern "C" void prn_set_stream(int n);
@@ -62,6 +74,12 @@ extern "C" void prn_set_stream(int n);
 //                               API FUNCTIONS
 //==============================================================================
 
+//==============================================================================
+//! Set OpenMC's master seed.
+//! @param new_seed The master seed. All other seeds will be derived from this
+//! one.
+//==============================================================================
+
 extern "C" int openmc_set_seed(int64_t new_seed);
 
 #endif // RANDOM_LCG_H