Added docstrings to member functions of variableAttributes and variab…

…leAttributeLoader

include/variableAttributeLoader.h

@@ -13,64 +13,149 @@ using EvalFlags = dealii::EvaluationFlags::EvaluationFlags;
 class variableAttributeLoader
 {
 public:
-  // Constructor
+  // Constructor. Executes the user-facing functions and constructs the variable
+  // attributes.
   variableAttributeLoader();
 
-  // Methods where the attributes are set
+  // User-facing method where the variable attributes are set.
   void
   loadVariableAttributes();
+  // User-facing method where the postprocessing variable attributes are set.
   void
   loadPostProcessorVariableAttributes();
 
   // Methods to set the parameter_attributes
+  /**
+   * \brief Set the name of the variable at `index` to `name`.
+   *
+   * \param index Index of variable
+   * \param name Name of variable at `index`
+   */
   void
   set_variable_name(const unsigned int &index, const std::string &name);
 
+  /**
+   * \brief Set the field type of the variable at `index` to `var_type` where `var_type`
+   * can be `SCALAR` or `VECTOR`.
+   *
+   * \param index Index of variable
+   * \param var_type Field type of variable at `index` (`SCALAR` or `VECTOR`).
+   */
   void
-  set_variable_type(const unsigned int &index, const fieldType &);
-
+  set_variable_type(const unsigned int &index, const fieldType &var_type);
+
+  /**
+   * \brief Set the PDE type of the variable at `index` to `var_eq_type` where
+   *`var_eq_type`can be
+   * `EXPLICIT_TIME_DEPENDENT`, `IMPLICIT_TIME_DEPENDENT`, `TIME_INDEPENDENT`,
+   *`AUXILIARY`.
+   *
+   * \param index Index of variable
+   * \param var_eq_type PDE type of variable at `index`.
+   */
   void
-  set_variable_equation_type(const unsigned int &index, const PDEType &);
-
+  set_variable_equation_type(const unsigned int &index, const PDEType &var_eq_type);
+
+  /**
+   * \brief Set the dependencies for the value term of the RHS equation of the variable at
+   * `index`.
+   *
+   * \param index Index of variable
+   * \param dependencies String containing comma-separated list of dependencies for
+   * variable at `index` Hint: "variable, grad(variable), hess(variable)"
+   */
   void
   set_dependencies_value_term_RHS(const unsigned int &index,
                                   const std::string  &dependencies);
 
+  /**
+   * \brief Set the dependencies for the gradient term of the RHS equation of the variable
+   * at `index`.
+   *
+   * \param index Index of variable
+   * \param dependencies String containing comma-separated list of dependencies for
+   * variable at `index` Hint: "variable, grad(variable), hess(variable)"
+   */
   void
   set_dependencies_gradient_term_RHS(const unsigned int &index,
                                      const std::string  &dependencies);
 
+  /**
+   * \brief Set the dependencies for the value term of the LHS equation of the variable at
+   * `index`.
+   *
+   * \param index Index of variable
+   * \param dependencies String containing comma-separated list of dependencies for
+   * variable at `index` Hint: "variable, grad(variable), hess(variable)"
+   */
   void
   set_dependencies_value_term_LHS(const unsigned int &index,
                                   const std::string  &dependencies);
 
+  /**
+   * \brief Set the dependencies for the gradient term of the LHS equation of the variable
+   * at `index`.
+   *
+   * \param index Index of variable
+   * \param dependencies String containing comma-separated list of dependencies for
+   * variable at `index` Hint: "variable, grad(variable), hess(variable)"
+   */
   void
   set_dependencies_gradient_term_LHS(const unsigned int &index,
                                      const std::string  &dependencies);
 
+  /**
+   * \brief Flag whether the variable at `index` is needed to calculate the nucleation
+   * probability.
+   *
+   * \param index Index of variable
+   * \param flag true: variable is needed, false: variable is not needed.
+   */
   void
-  set_need_value_nucleation(const unsigned int &index, const bool &);
-
+  set_need_value_nucleation(const unsigned int &index, const bool &flag);
+
+  /**
+   * \brief Flag whether the variable at `index` is can have a nucleation event.
+   *
+   * \param index Index of variable
+   * \param flag true: variable can nucleate, false: variable can not nucleate.
+   */
   void
-  set_allowed_to_nucleate(const unsigned int &index, const bool &);
-
+  set_allowed_to_nucleate(const unsigned int &index, const bool &flag);
+
+  /**
+   * \brief (Postprocess only) Flag whether the postprocessing variable at `index` should
+   * have its domain integral calculated and output.
+   *
+   * \param index Index of variable
+   * \param flag true: calculate and output the integral of the field over the domain,
+   * false: do nothing
+   */
   void
-  set_output_integral(const unsigned int &index, const bool &);
+  set_output_integral(const unsigned int &index, const bool &flag);
+
+  // The solutions variable attributes
+  std::map<uint, variableAttributes> attributes;
+  // The postprocessing variable attributes
+  std::map<uint, variableAttributes> pp_attributes;
+  // Useful pointer for setting whether solution or postprocessiong variables are being
+  // loaded
+  std::map<uint, variableAttributes> *relevant_attributes = nullptr;
 
-  void
-  format_dependencies();
+private:
+  /**
+   * \brief Perform a suite of assertions on attributes and pp_attributes to ensure that
+   * the user's inputs are well-formed
+   */
   void
   validate_attributes();
+
+  /**
+   * \brief Utility to remove whitespace from strings
+   */
   std::string
   strip_whitespace(const std::string &text);
-
-  // Members
-  std::map<uint, variableAttributes>  attributes;
-  std::map<uint, variableAttributes>  pp_attributes;
-  std::map<uint, variableAttributes> *relevant_attributes = nullptr;
-
-  unsigned int number_of_variables;
-  unsigned int pp_number_of_variables;
+  // The above function should be moved to a 'utilities' module
 };
 
 #endif

include/variableAttributes.h

@@ -7,14 +7,15 @@
 
 #include "varTypeEnums.h"
 
+#include <map>
 #include <set>
 #include <string>
 
 using EvalFlags = dealii::EvaluationFlags::EvaluationFlags;
 
 struct variableAttributes
 {
-  // Variable inputs (v2.0)
+  // Variable attributes
   std::string name                  = "";
   fieldType   var_type              = UNDEFINED_FIELD;
   PDEType     eq_type               = UNDEFINED_PDE;
@@ -25,6 +26,7 @@ struct variableAttributes
   bool        calc_integral         = false;
   bool        output_integral       = false;
 
+  // This variable's dependencies
   std::set<std::string> dependencies_value_RHS;
   std::set<std::string> dependencies_gradient_RHS;
   std::set<std::string> dependencies_RHS;
@@ -37,6 +39,8 @@ struct variableAttributes
 
   std::set<std::string> dependency_set;
 
+  // Evaluation Flags. Tells deal.ii whether or not to retrieve the value, grad, hess,
+  // etc. for equations
   EvalFlags eval_flags_explicit_RHS    = dealii::EvaluationFlags::nothing;
   EvalFlags eval_flags_nonexplicit_RHS = dealii::EvaluationFlags::nothing;
   EvalFlags eval_flags_nonexplicit_LHS = dealii::EvaluationFlags::nothing;
@@ -50,14 +54,32 @@ struct variableAttributes
   EvalFlags eval_flags_postprocess          = dealii::EvaluationFlags::nothing;
   EvalFlags eval_flags_residual_postprocess = dealii::EvaluationFlags::nothing;
 
+  /**
+   * \brief Combine 'value' and 'gradient' dependencies to one dependency set per RHS,
+   * LHS, PP.
+   */
   void
   format_dependencies();
+
+  /**
+   * \brief Take user-defined dependency sets to set the evaluation flags for each
+   * variable.
+   */
   void
   parse_dependencies(std::map<uint, variableAttributes> &other_var_attributes);
 
+  /**
+   * \brief Take user-defined dependency sets to set the residual flags for each
+   * variable.
+   */
   void
   parse_residual_dependencies();
 
+  /**
+   * \brief Helper function that returns a set of pointers to the flags that need to be
+   * set when `other_variable` is dependent on this variable.
+   * \param other_variable Variable that is dependent on this variable.
+   */
   std::set<EvalFlags *>
   eval_flags_for_eq_type(const variableAttributes &other_variable);