Update doxygen comments for Sphinx API documentation

src/core/CFDMesh.cpp

@@ -27,10 +27,6 @@
 namespace sierra {
 namespace nalu {
 
-/**
- * \param comm MPI Communicator object
- * \param filename Exodus database filename
- */
 CFDMesh::CFDMesh
 (
     stk::ParallelMachine& comm,

src/core/CFDMesh.h

@@ -46,9 +46,19 @@ typedef stk::search::Box<double> BoxType;
 class CFDMesh
 {
 public:
+    /**Create a CFD mesh instance from an existing mesh database
+     *
+     * \param comm MPI Communicator object
+     * \param filename Exodus database filename
+     */
     explicit CFDMesh(stk::ParallelMachine&,
             const std::string filename);
 
+    /**Create a CFD mesh instance from scratch
+     *
+     * \param comm MPI Communicator object
+     * \param ndim Dimensionality of mesh
+     */
     explicit CFDMesh(stk::ParallelMachine&,
                      const int ndim);
 
@@ -61,26 +71,42 @@ class CFDMesh
      */
     void init();
 
+    //! Reference to the MPI communicator object
     inline stk::ParallelMachine& comm() { return comm_; }
 
+    //! Reference to the stk::mesh::MetaData instance
     inline stk::mesh::MetaData& meta() { return meta_; }
 
+    //! Reference to the stk::mesh::BulkData instance
     inline stk::mesh::BulkData& bulk() { return bulk_; }
 
+    //! Reference to the STK mesh I/O instance
     inline stk::io::StkMeshIoBroker& stkio() { return stkio_; }
 
     /** Register a field for output during write
+     *
+     * \param Name of the field to be output
      */
     inline void add_output_field(const std::string field)
     {
         output_fields_.insert(field);
     }
 
     /** Write the Exodus results database with modifications
+     *
+     *  \param output_db Pathname to the output ExodusII database
+     *  \param time Timestep to write
+     *
+     *  \sa write_database_with_fields
      */
     void write_database(std::string output_db, double time=0.0);
 
     /** Write database with restart fields
+     *
+     *  Copies the restart data fields from the input Exodus database to the
+     *  output database.
+     *
+     *  \param output_db Pathname to the output ExodusII database
      */
     void write_database_with_fields(std::string output_db);
 
@@ -99,12 +125,18 @@ class CFDMesh
     BoxType calc_bounding_box(const stk::mesh::Selector, bool verbose=true);
 
     /** Set automatic mesh decomposition property
+     *
+     *  \param The decomposition type
+     *
+     *  Valid decomposition types are: rcb, rib, block, linear
      */
     inline void set_decomposition_type(std::string decompType)
     {
         stkio_.property_add(Ioss::Property("DECOMPOSITION_METHOD", decompType));
     }
 
+    /** Force output database to use 8-bit integers
+     */
     inline void set_64bit_flags()
     {
         stkio_.property_add(Ioss::Property("INTEGER_SIZE_DB",8));

src/core/LinearInterpolation.h

@@ -55,16 +55,29 @@ struct OutOfBounds
 template <typename T>
 using Array1D = std::vector<T>;
 
+/** Useful type definitions for tracking interpolation data
+ */
 template <typename T>
 struct InterpTraits
 {
   typedef typename Array1D<T>::size_type size_type;
+
+  /** A pair indicating whether the point to be interpolate is within bounds
+   * or out of bounds and a corresponding index. If the point is within bounds
+   * then the index returned is such that `xarray[i] <= xtarget <
+   * xarray[i+1]`. For out of bounds, the index is either 0 or IMAX-1.
+   */
   typedef typename std::pair<OutOfBounds::boundLimits, size_type> index_type;
 };
 
 /**
  * Determine whether the given value is within the limits of the interpolation
  * table
+ *
+ * \param xinp 1-D array of monotonically increasing values
+ * \param x The value to check for
+ *
+ * \result A std::pair containing the OutOfBounds flag and the index (0 or MAX)
  */
 template <typename T>
 inline typename InterpTraits<T>::index_type
@@ -90,7 +103,10 @@ check_bounds(const Array1D<T>& xinp, const T& x)
  * Return an index object corresponding to the x-value based on interpolation
  * table.
  *
- * The `std::pair` returned contains two values: the bounds indicator and the
+ * \param xinp 1-D array of monotonically increasing values
+ * \param x The value to check for
+ *
+ * \return The `std::pair` returned contains two values: the bounds indicator and the
  * index of the element in the interpolation table such that `xarray[i] <= x <
  * xarray[i+1]`
  */
@@ -115,7 +131,7 @@ find_index(const Array1D<T>& xinp, const T& x)
 /**
  * Perform a 1-D linear interpolation
  *
- * \param xinp A 1-d vector of x-values
+ * \param xinp A 1-d vector of monotonically increasing x-values
  * \param yinp Corresponding 1-d vector of y-values
  * \param xout Target x-value for interpolation
  * \param yout Interpolated value at `xout`

src/core/YamlUtils.h

@@ -23,6 +23,15 @@ namespace sierra {
 namespace nalu {
 namespace wind_utils {
 
+/** Fetch an optional entry from the YAML dictionary if it exists
+ *
+ *  The result parameter is unchanged if the entry is not found in the YAML
+ *  dictionary.
+ *
+ *  \param node The YAML::Node instance to be examined
+ *  \param key  The name of the variable to be extracted
+ *  \param result The variable that is updated with the value if it exists
+ */
 template<typename T>
 bool get_optional(const YAML::Node& node, const std::string& key, T& result)
 {
@@ -35,6 +44,18 @@ bool get_optional(const YAML::Node& node, const std::string& key, T& result)
     return found;
 }
 
+/** Fetch an optional entry from the YAML dictionary if it exists
+ *
+ *  The result parameter is updated with the value from the dictionary if it
+ *  exists, otherwise it is initialized with the default value provided.
+ *
+ *  \param node The YAML::Node instance to be examined
+ *  \param key  The name of the variable to be extracted
+ *  \param result The variable that is updated with the value if it exists
+ *
+ *  \param default_value The default value to be used if the parameter is not
+ *  found in the dictionary.
+ */
 template<typename T>
 bool get_optional(const YAML::Node& node, const std::string& key, T& result, const T& default_value)
 {

src/mesh/HexBlockMesh.h

@@ -39,12 +39,21 @@ class HexBlockMesh
         VERTICES       ///< Provide vertices for the cuboidal domain
     };
 
+    /**
+     * \param mesh A sierra::nalu::CFDMesh instance
+     * \param node The YAML::Node containing inputs for this task
+     */
     HexBlockMesh(CFDMesh&, const YAML::Node&);
 
     virtual ~HexBlockMesh();
 
+    /** Registers the element block and the sidesets to the STK MetaData instance
+     */
     virtual void initialize();
 
+    /** Creates the nodes and elements within the mesh block, processes
+     * sidesets, and initializes the coordinates of the mesh structure.
+     */
     virtual void run();
 
 private:
@@ -60,8 +69,13 @@ class HexBlockMesh
     //! Generate coordinates
     void generate_coordinates(const std::vector<stk::mesh::EntityId>&);
 
+    //! Generate the xmin and xmax sidesets
     void generate_x_boundary(const std::vector<stk::mesh::EntityId>&, const int);
+
+    //! Generate the ymin and ymax sidesets
     void generate_y_boundary(const std::vector<stk::mesh::EntityId>&, const int);
+
+    //! Generate the zmin and zmax sidesets
     void generate_z_boundary(const std::vector<stk::mesh::EntityId>&, const int);
 
     //! STK Metadata object
@@ -84,11 +98,22 @@ class HexBlockMesh
 
     // Names for the boundary sidesets
 
+    //! Name of the XMIN sideset
     std::string ss_xmin_name_{"west"};
+
+    //! Name of the XMAX sideset
     std::string ss_xmax_name_{"east"};
+
+    //! Name of the YMIN sideset
     std::string ss_ymin_name_{"south"};
+
+    //! Name of the YMAX sideset
     std::string ss_ymax_name_{"north"};
+
+    //! Name of the ZMIN sideset
     std::string ss_zmin_name_{"terrain"};
+
+    //! Name of the ZMAX sideset
     std::string ss_zmax_name_{"top"};
 
     //! Flag indicating user selection of domain extents

src/preprocessing/ABLFields.h

@@ -61,6 +61,10 @@ class ABLFields: public PreProcessingTask
     template<typename T>
     using Array2D = std::vector<std::vector<T>>;
 
+    /**
+     * \param mesh A sierra::nalu::CFDMesh instance
+     * \param node The YAML::Node containing inputs for this task
+     */
     ABLFields(CFDMesh&, const YAML::Node&);
 
     virtual ~ABLFields() {}

src/preprocessing/BdyIOPlanes.h

@@ -30,6 +30,10 @@ namespace nalu {
 class BdyIOPlanes: public PreProcessingTask
 {
 public:
+    /**
+     * \param mesh A sierra::nalu::CFDMesh instance
+     * \param node The YAML::Node containing inputs for this task
+     */
     BdyIOPlanes(CFDMesh&, const YAML::Node&);
 
     virtual ~BdyIOPlanes();

src/preprocessing/PreProcessingTask.h

@@ -48,14 +48,24 @@ class PreProcessingTask
 {
 public:
     /**
-     * \param mesh A CFDMesh instance
+     * \param mesh A sierra::nalu::CFDMesh instance
      */
     PreProcessingTask(CFDMesh& mesh) : mesh_(mesh) {}
 
     virtual ~PreProcessingTask() {}
 
+    /** Initialize the STK MetaData instance.
+     *
+     *  This method handles the registration and creation of new parts and
+     *  fields. All subclasses must implement this method.
+     */
     virtual void initialize() = 0;
 
+    /** Process the STK BulkData instance
+     *
+     *  This method handles the creating of new entities, manipulating
+     *  coordinates, and populating fields.
+     */
     virtual void run() = 0;
 
     DECLARE_INHERITANCE_REGISTRY