Documentation: Document all function in test headers properly

doc/Doxyfile.in

@@ -958,7 +958,7 @@ WARN_FORMAT            = "$file:$line: $text"
 # Example:
 # WARN_LINE_FORMAT = "'vi $file +$line'"
 # See also: WARN_FORMAT
-# The default value is: at line $line of file $file.
+# The default value is: at line $line of file $file.test
 
 WARN_LINE_FORMAT       = "at line $line of file $file"
 
@@ -982,7 +982,8 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = @top_srcdir@/src \
-                         @top_srcdir@/mesh_handle
+                         @top_srcdir@/mesh_handle \
+                         @top_srcdir@/test
 
 # This tag can be used to specify the character encoding of the source files
 # that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1053,7 +1054,10 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS = */test/*.cxx \
+                   */test/*.c \
+                   */test/*.f90 \
+
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

test/t8_cmesh_generator/t8_cmesh_example_sets.hxx

@@ -20,6 +20,9 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
+/** \file t8_cmesh_example_sets.hxx
+ * Define macro that includes all the cmesh example sets. Each example set should be defined in a separate file and included here.
+ */
 #ifndef T8_GTEST_CMESH_COMM_CREATOR_HXX
 #define T8_GTEST_CMESH_COMM_CREATOR_HXX
 
@@ -41,15 +44,18 @@
 T8_EXTERN_C_BEGIN ();
 
 /**
- * lambda to pass to an INSTANTIATE_TEST_SUITE_P to print the current cmesh_example_base
- * 
+ * lambda to pass to an INSTANTIATE_TEST_SUITE_P to print the current \ref cmesh_example_base.
  */
 auto pretty_print_base_example = [] (const testing::TestParamInfo<cmesh_example_base *> &info) {
   std::string name;
   info.param->param_to_string (name);
   return name;
 };
 
+/**
+ * lambda to pass to an INSTANTIATE_TEST_SUITE_P to print the current \ref cmesh_example_base and the scheme.
+ * 
+ */
 auto pretty_print_base_example_scheme = [] (const testing::TestParamInfo<std::tuple<int, cmesh_example_base *>> &info) {
   std::string name;
   std::get<1> (info.param)->param_to_string (name);
@@ -59,6 +65,7 @@ auto pretty_print_base_example_scheme = [] (const testing::TestParamInfo<std::tu
 
 namespace cmesh_list
 {
+/** Vector of all example cmesh sets. */
 std::vector<example_set *> cart_prod_vec = { new_from_class::cmesh_example,
                                              new_prism_cake::cmesh_example,
                                              new_bigmesh::cmesh_example,
@@ -71,10 +78,12 @@ std::vector<example_set *> cart_prod_vec = { new_from_class::cmesh_example,
                                              new_empty::cmesh_example,
                                              new_periodic::cmesh_example };
 
+/** Constructs cmeshes according to \ref cart_prod_vec. */
 cmesh_sum_of_sets cmesh_sums (cart_prod_vec);
 
 }  // namespace cmesh_list
 
+/** Macro that includes all cmesh example sets. */
 #define AllCmeshsParam \
   ::testing::ValuesIn (cmesh_list::cmesh_sums.cmesh_examples.begin (), cmesh_list::cmesh_sums.cmesh_examples.end ())
 

test/t8_cmesh_generator/t8_cmesh_parameterized_examples/t8_cmesh_new_bigmesh_param.hxx

@@ -20,6 +20,9 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
+/** \file t8_cmesh_new_bigmesh_param.hxx 
+ * Parameterized example cmeshes providing a big mesh for test purpose.
+ */
 #ifndef T8_CMESH_NEW_BIGMESH_PARAM_HXX
 #define T8_CMESH_NEW_BIGMESH_PARAM_HXX
 
@@ -30,8 +33,14 @@
 
 namespace new_bigmesh
 {
+/** Wrapper function for t8_cmesh_new_bigmesh. */
 std::function<t8_cmesh_t (t8_eclass_t, int, sc_MPI_Comm)> bigmesh = t8_cmesh_new_bigmesh;
 
+/** Function to convert parameter values to a string.
+ * \param [in] eclass The eclass of the mesh.
+ * \param [in] num_trees The number of trees of the mesh.
+ * \param [in] comm The communicator.
+ */
 std::string
 make_param_string (const t8_eclass_t eclass, const int num_trees, const sc_MPI_Comm comm)
 {
@@ -41,9 +50,11 @@ make_param_string (const t8_eclass_t eclass, const int num_trees, const sc_MPI_C
   return params;
 }
 
+/** Wrapper function for \ref make_param_string. */
 std::function<std::string (const t8_eclass_t, const int, const sc_MPI_Comm)> make_param_string_wrapper
   = make_param_string;
 
+/** Example cmesh set of bigmesh cmeshes. */
 example_set *cmesh_example
   = (example_set *) new cmesh_cartesian_product_params<decltype (cmesh_params::eclasses.begin ()),
                                                        decltype (cmesh_params::large_mesh.begin ()),

test/t8_cmesh_generator/t8_cmesh_parameterized_examples/t8_cmesh_new_comm.hxx

@@ -20,6 +20,10 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
+/** \file t8_cmesh_new_comm.hxx 
+ * Parameterized example cmeshes by MPI communicators.
+ */
+
 #ifndef T8_CMESH_NEW_COMM
 #define T8_CMESH_NEW_COMM
 
@@ -29,6 +33,10 @@
 
 namespace new_cmesh_comm
 {
+
+/** Function to convert parameter values to a string.
+ * \param [in] comm The communicator used.
+ */
 std::string
 make_param_string (const sc_MPI_Comm &comm)
 {
@@ -37,8 +45,10 @@ make_param_string (const sc_MPI_Comm &comm)
   return params;
 }
 
+/** Wrapper function for \ref make_param_string. */
 std::function<std::string (const sc_MPI_Comm)> print_function = make_param_string;
 
+/** Vector with functions to construct a cmesh from a communicator parameter. */
 std::vector<std::function<t8_cmesh_t (sc_MPI_Comm)>> cmesh_functions = { t8_cmesh_new_periodic_tri,
                                                                          t8_cmesh_new_periodic_hybrid,
                                                                          t8_cmesh_new_periodic_line_more_trees,
@@ -51,7 +61,7 @@ std::vector<std::function<t8_cmesh_t (sc_MPI_Comm)>> cmesh_functions = { t8_cmes
                                                                          t8_cmesh_new_hybrid_gate,
                                                                          t8_cmesh_new_hybrid_gate_deformed,
                                                                          t8_cmesh_new_full_hybrid };
-
+/** Names of the example sets of constructed cmeshes.*/
 std::vector<std::string> names = { "t8_cmesh_new_periodic_tri",
                                    "t8_cmesh_new_periodic_hybrid",
                                    "t8_cmesh_new_periodic_line_more_trees",
@@ -65,6 +75,7 @@ std::vector<std::string> names = { "t8_cmesh_new_periodic_tri",
                                    "t8_cmesh_new_hybrid_gate_deformed",
                                    "t8_cmesh_new_full_hybrid" };
 
+/** Example cmesh set with different communicators. */
 example_set *cmesh_example
   = (example_set *) new cmesh_cartesian_product_params<decltype (cmesh_params::my_comms.begin ())> (
     std::make_pair (cmesh_params::my_comms.begin (), cmesh_params::my_comms.end ()), cmesh_functions, print_function,

test/t8_cmesh_generator/t8_cmesh_parameterized_examples/t8_cmesh_new_disjoint_bricks_param.hxx

@@ -20,34 +20,50 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
+/** \file t8_cmesh_new_disjoint_bricks_param.hxx 
+ * Parameterized example cmeshes with disjoint bricks.
+ */
+#ifndef T8_CMESH_NEW_DISJOINT_BRICKS_PARAM_HXX
+#define T8_CMESH_NEW_DISJOINT_BRICKS_PARAM_HXX
+
 #include "test/t8_cmesh_generator/t8_gtest_cmesh_cartesian_product.hxx"
 #include "test/t8_cmesh_generator/t8_cmesh_parameterized_examples/t8_cmesh_params.hxx"
 #include "t8_cmesh/t8_cmesh_examples.h"
 
-#ifndef T8_CMESH_NEW_DISJOINT_BRICKS_PARAM_HXX
-#define T8_CMESH_NEW_DISJOINT_BRICKS_PARAM_HXX
-
 namespace new_disjoint_bricks
 {
+/** Wrapper function for t8_cmesh_new_disjoint_bricks. */
 std::function<t8_cmesh_t (t8_gloidx_t, t8_gloidx_t, t8_gloidx_t, int, int, int, sc_MPI_Comm)> disjoint_bricks
   = t8_cmesh_new_disjoint_bricks;
 
+/** Function to convert parameter values to a string.
+ * \param [in] num_x       The number of trees in x direction for this rank.
+ * \param [in] num_y       The number of trees in y direction for this rank.
+ * \param [in] num_z       The number of trees in z direction for this rank.
+ *                         If nonzero, the cmesh is 3 dimensional.
+ * \param [in] x_periodic  If nonzero, the local brick connectivity is periodic in x direction.
+ * \param [in] y_periodic  If nonzero, the local brick connectivity is periodic in y direction.
+ * \param [in] z_periodic  If nonzero and \a num_z > 0, the local brick connectivity is periodic in z direction.
+ * \param [in] comm        The MPI communicator used to commit the cmesh.
+ */
 std::string
-make_param_string (const t8_gloidx_t num_x, const t8_gloidx_t num_y, const t8_gloidx_t num_z, const int num_x_periodic,
-                   const int num_y_periodic, const int num_z_periodic, sc_MPI_Comm comm)
+make_param_string (const t8_gloidx_t num_x, const t8_gloidx_t num_y, const t8_gloidx_t num_z, const int x_periodic,
+                   const int y_periodic, const int z_periodic, sc_MPI_Comm comm)
 {
   std::string delimiter = std::string ("_");
   std::string params = delimiter + std::to_string (num_x) + delimiter + std::to_string (num_y) + delimiter
-                       + std::to_string (num_z) + delimiter + std::to_string (num_x_periodic) + delimiter
-                       + std::to_string (num_y_periodic) + delimiter + std::to_string (num_z_periodic) + delimiter
+                       + std::to_string (num_z) + delimiter + std::to_string (x_periodic) + delimiter
+                       + std::to_string (y_periodic) + delimiter + std::to_string (z_periodic) + delimiter
                        + cmesh_params::comm_to_string (comm);
   return params;
 }
 
+/** Wrapper function for \ref make_param_string. */
 std::function<std::string (const t8_gloidx_t, const t8_gloidx_t, const t8_gloidx_t, const int, const int, const int,
                            const sc_MPI_Comm)>
   make_param_string_wrapper = make_param_string;
 
+/** Example disjoint bricks cmesh set with different parameter combinations. */
 example_set *cmesh_example = (example_set *) new cmesh_cartesian_product_params<
   decltype (cmesh_params::elems_per_dim.begin ()), decltype (cmesh_params::elems_per_dim.begin ()),
   decltype (cmesh_params::elems_per_dim.begin ()), decltype (cmesh_params::periodic.begin ()),

test/t8_cmesh_generator/t8_cmesh_parameterized_examples/t8_cmesh_new_empty.hxx

@@ -20,6 +20,9 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
+/** \file t8_cmesh_new_empty.hxx 
+ * Parameterized empty example cmeshes.
+ */
 #ifndef T8_CMESH_NEW_EMPTY_HXX
 #define T8_CMESH_NEW_EMPTY_HXX
 
@@ -30,7 +33,11 @@
 
 namespace new_empty
 {
-
+/** Function to convert parameter values to a string.
+ * \param [in] comm  Mpi communicator to be used with the new cmesh.
+ * \param [in] do_partition Flag whether the cmesh should be partitioned or not.
+ * \param [in] dim An empty cmesh requires a dimension nevertheless. 0 <= tree dimension <= 3.
+ */
 std::string
 make_param_string (const sc_MPI_Comm &comm, const int do_partition, const int dim)
 {
@@ -40,11 +47,13 @@ make_param_string (const sc_MPI_Comm &comm, const int do_partition, const int di
     = delimiter + cmesh_params::comm_to_string (comm) + delimiter + partition + delimiter + std::to_string (dim);
   return params;
 }
-
+/** Wrapper function for \ref make_param_string. */
 std::function<std::string (const sc_MPI_Comm &, const int, const int)> print_function = make_param_string;
 
+/** Wrapper function for t8_cmesh_new_empty. */
 std::function<t8_cmesh_t (sc_MPI_Comm, const int, const int)> new_from_class_wrapper = t8_cmesh_new_empty;
 
+/** Example empty cmesh set with different parameter combinations. */
 example_set *cmesh_example
   = (example_set *) new cmesh_cartesian_product_params<decltype (cmesh_params::my_comms.begin ()),
                                                        decltype (cmesh_params::partition.begin ()),

test/t8_cmesh_generator/t8_cmesh_parameterized_examples/t8_cmesh_new_from_class_param.hxx

@@ -20,17 +20,23 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
+/** \file t8_cmesh_new_disjoint_bricks_param.hxx 
+ * Parameterized example cmeshes that consists only of one tree of a given element class.
+ */
+#ifndef T8_CMESH_NEW_FROM_CLASS_PARAM
+#define T8_CMESH_NEW_FROM_CLASS_PARAM
+
 #include "test/t8_cmesh_generator/t8_gtest_cmesh_cartesian_product.hxx"
 #include "test/t8_cmesh_generator/t8_cmesh_parameterized_examples/t8_cmesh_params.hxx"
 #include <t8_cmesh/t8_cmesh_examples.h>
 #include <t8_eclass.h>
 
-#ifndef T8_CMESH_NEW_FROM_CLASS_PARAM
-#define T8_CMESH_NEW_FROM_CLASS_PARAM
-
 namespace new_from_class
 {
-
+/** Function to convert parameter values to a string.
+ * \param [in] eclass The element class.
+ * \param [in] comm Mpi communicator to be used with the new cmesh.
+ */
 std::string
 make_param_string (const t8_eclass_t &eclass, const sc_MPI_Comm &comm)
 {
@@ -39,11 +45,13 @@ make_param_string (const t8_eclass_t &eclass, const sc_MPI_Comm &comm)
     = delimiter + std::string (t8_eclass_to_string[eclass]) + delimiter + cmesh_params::comm_to_string (comm);
   return params;
 }
-
+/** Wrapper function for make_param_string. */
 std::function<std::string (const t8_eclass_t &, const sc_MPI_Comm &)> print_function = make_param_string;
 
+/** Wrapper function for t8_cmesh_new_from_class. */
 std::function<t8_cmesh_t (t8_eclass_t, sc_MPI_Comm)> new_from_class_wrapper = t8_cmesh_new_from_class;
 
+/** Example cmesh set with different parameter combinations using the new_from_class function. */
 example_set *cmesh_example
   = (example_set *) new cmesh_cartesian_product_params<decltype (cmesh_params::eclasses.begin ()),
                                                        decltype (cmesh_params::my_comms.begin ())> (