Documentation: doxygen documentation for tutorials

doc/Doxyfile.in

@@ -984,7 +984,7 @@ WARN_LOGFILE           =
 INPUT                  = @top_srcdir@/src \
                          @top_srcdir@/mesh_handle \
                          @top_srcdir@/test \
-                         @top_srcdir@/tutorials/mesh_handle
+                         @top_srcdir@/tutorials
 
 # 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

tutorials/features/t8_features_curved_meshes.cxx

@@ -20,7 +20,8 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/* See also: https://github.com/DLR-AMR/t8code/wiki/Feature---Curved-meshes
+/** \file t8_features_curved_meshes.cxx
+ * See also: https://github.com/DLR-AMR/t8code/wiki/Feature---Curved-meshes
  *
  * This is a feature tutorial about curved meshes.
  * In the following we will generate an input mesh and input geometry in Gmsh.
@@ -50,14 +51,14 @@
 #include <string>                                      /* std::string */
 #include <array>                                       /* std::array */
 
-/* We use this data to control to which level the elements at which
+/** We use this data to control to which level the elements at which
  * geometry get refined. */
 struct t8_naca_geometry_adapt_data
 {
-  int level;        /** Uniform refinement level of the forest */
-  int n_geometries; /** Amount of geometries we want to refine */
-  int *geometries;  /** Array with geometry indices */
-  int *levels;      /** Array with refinement levels */
+  int level;        /**< Uniform refinement level of the forest */
+  int n_geometries; /**< Amount of geometries we want to refine */
+  int *geometries;  /**< Array with geometry indices */
+  int *levels;      /**< Array with refinement levels */
 };
 
 #if T8_ENABLE_OCC
@@ -80,6 +81,7 @@ struct t8_naca_geometry_adapt_data
  * \param [in] forest       The current forest that is in construction.
  * \param [in] forest_from  The forest from which we adapt the current forest (in our case, the uniform forest)
  * \param [in] which_tree   The process local id of the current tree.
+ * \param [in] tree_class   The eclass of \a which_tree.
  * \param [in] lelement_id  The tree local index of the current element (or the first of the family).
  * \param [in] scheme           The refinement scheme for this tree's element class.
  * \param [in] is_family    if 1, the first \a num_elements entries in \a elements form a family. If 0, they do not.
@@ -142,6 +144,7 @@ t8_naca_geometry_adapt_callback (t8_forest_t forest, t8_forest_t forest_from, t8
  * \param [in] level            The uniform refinement level of the forest.
  * \param [in] rlevel_dorsal    The refinement level of the elements touching the dorsal side of the wing.
  * \param [in] rlevel_ventral   The refinement level of the elements touching the ventral side of the wing.
+ * \param [in] dim              The dimension.
  */
 int
 t8_naca_geometry_refinement (t8_forest_t forest, const std::string &fileprefix, int level, int rlevel_dorsal,
@@ -197,15 +200,16 @@ t8_naca_geometry_refinement (t8_forest_t forest, const std::string &fileprefix,
 }
 #endif
 
+/** Adaption parameter class used to specify the refinement in \ref t8_naca_plane_adapt_callback. */
 struct t8_naca_plane_adapt_data
 {
-  int t;        /* The time step we are in */
-  int steps;    /* The amount of time steps */
-  double x_min; /* The minimum x-coordinate of the profile */
-  double x_max; /* The maximum x-coordinate of the profile */
-  double dist;  /* The distance an element can have from the plane to still be refined */
-  int level;    /* The uniform refinement level */
-  int rlevel;   /* The max refinement level */
+  int t;        /**< The time step we are in */
+  int steps;    /**< The amount of time steps */
+  double x_min; /**< The minimum x-coordinate of the profile */
+  double x_max; /**< The maximum x-coordinate of the profile */
+  double dist;  /**< The distance an element can have from the plane to still be refined */
+  int level;    /**< The uniform refinement level */
+  int rlevel;   /**< The max refinement level */
 };
 
 /**
@@ -228,6 +232,7 @@ struct t8_naca_plane_adapt_data
  * \param [in] forest       The current forest that is in construction.
  * \param [in] forest_from  The forest from which we adapt the current forest (in our case, the uniform forest)
  * \param [in] which_tree   The process local id of the current tree.
+ * \param [in] tree_class   The eclass of \a which_tree.
  * \param [in] lelement_id  The tree local index of the current element (or the first of the family).
  * \param [in] scheme           The refinement scheme for this tree's element class.
  * \param [in] is_family    if 1, the first \a num_elements entries in \a elements form a family. If 0, they do not.

tutorials/general/t8_step0_helloworld.cxx

@@ -20,13 +20,15 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/* See also: https://github.com/DLR-AMR/t8code/wiki/Step-0---Hello-World
+/** \file t8_step0_helloworld.cxx
+ * See also: https://github.com/DLR-AMR/t8code/wiki/Step-0---Hello-World
  *
  * In this example we initialize t8code and print a small welcome message.
  * This is the t8code equivalent of HelloWorld. */
 
 #include <t8.h> /* General t8code header, always include this. */
 
+/** Entry point of the program. */
 int
 main (int argc, char **argv)
 {

tutorials/general/t8_step1_coarsemesh.cxx

@@ -20,7 +20,8 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/* See also: https://github.com/DLR-AMR/t8code/wiki/Step-1---Creating-a-coarse-mesh
+/** \file t8_step1_coarsemesh.cxx
+ * See also: https://github.com/DLR-AMR/t8code/wiki/Step-1---Creating-a-coarse-mesh
  *
  * In this example we build a coarse mesh with a cube geometry.
  * The cube is meshed with 6 coarse tetrahedra.
@@ -92,6 +93,7 @@ t8_step1_destroy_cmesh (t8_cmesh_t cmesh)
   t8_cmesh_destroy (&cmesh);
 }
 
+/** Entry point of the program. */
 int
 main (int argc, char **argv)
 {

tutorials/general/t8_step2_uniform_forest.cxx

@@ -20,7 +20,8 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/* See also: https://github.com/DLR-AMR/t8code/wiki/Step-2---Creating-a-uniform-forest
+/** \file t8_step2_uniform_forest.cxx
+ * See also: https://github.com/DLR-AMR/t8code/wiki/Step-2---Creating-a-uniform-forest
  *
  * After we learned how to create a cmesh in step1, we will
  * now build our first partitioned forest, get its local and global
@@ -116,6 +117,7 @@ t8_step2_destroy_forest (t8_forest_t forest)
   t8_forest_unref (&forest);
 }
 
+/** Entry point of the program. */
 int
 main (int argc, char **argv)
 {

tutorials/general/t8_step3.h

@@ -20,7 +20,7 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/** file t8_step3.h
+/** \file t8_step3.h
  * This is the header file to the step3 example of t8code. It collects
  * functions of t8_step3 that we reuse in other examples.
  * In this example we discuss how to adapt a forest.
@@ -48,13 +48,12 @@ t8_step3_main (int argc, char **argv);
 void
 t8_step3_print_forest_information (t8_forest_t forest);
 
-/* This is our own defined data that we will pass on to the
- * adaptation callback. */
+/** This is our own defined data that we will pass on to the adaptation callback. */
 struct t8_step3_adapt_data
 {
-  double midpoint[3];               /* The midpoint of our sphere. */
-  double refine_if_inside_radius;   /* if an element's center is smaller than this value, we refine the element. */
-  double coarsen_if_outside_radius; /* if an element's center is larger this value, we coarsen its family. */
+  double midpoint[3];               /**< The midpoint of our sphere. */
+  double refine_if_inside_radius;   /**< if an element's center is smaller than this value, we refine the element. */
+  double coarsen_if_outside_radius; /**< if an element's center is larger this value, we coarsen its family. */
 };
 
 /** Adapt a forest according to our t8_step3_adapt_callback function.
@@ -66,7 +65,7 @@ struct t8_step3_adapt_data
 t8_forest_t
 t8_step3_adapt_forest (t8_forest_t forest);
 
-/* The adaptation callback function. This will refine elements inside of a given sphere
+/** The adaptation callback function. This will refine elements inside of a given sphere
  * and coarsen the elements outside of a given sphere.
  * The necessary input data is of type t8_step3_adapt_data and should be passed to forest
  * via t8_forest_set_user_data before calling this function.

tutorials/general/t8_step3_adapt_forest.cxx

@@ -20,7 +20,8 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/* This is step3 of the t8code tutorials.
+/** \file t8_step3_adapt_forest.cxx
+ * This is step3 of the t8code tutorials.
  * After generating a coarse mesh (step1) and building a uniform forest
  * on it (step2), we will now adapt (= refine and coarsen) the forest
  * according to our own criterion.

tutorials/general/t8_step3_main.cxx

@@ -20,13 +20,15 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/* This file is part of the step3 example of t8code.
+/** \file t8_step3_main.cxx
+ * This file is part of the step3 example of t8code.
  * Here, we only wrap the main function. See t8_step3_adapt_forest.cxx for the documentation of
  * the step3 example.
  */
 
 #include <tutorials/general/t8_step3.h>
 
+/** Entry point of the program. */
 int
 main (int argc, char **argv)
 {

tutorials/general/t8_step4.h

@@ -20,7 +20,7 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/** file t8_step4.h
+/** \file t8_step4.h
  * This is the header file to the step4 example of t8code. It collects
  * functions of t8_step4 that we reuse in other examples.
  * In this example we discuss the forest creation process in more detail including

tutorials/general/t8_step4_main.cxx

@@ -20,13 +20,15 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/* This file is part of the step4 example of t8code.
+/** \file t8_step4_main.cxx
+ * This file is part of the step4 example of t8code.
  * Here, we only wrap the main function. See t8_step4_partition_balance_ghost.cxx for the documentation of
  * the step4 example.
  */
 
 #include <tutorials/general/t8_step4.h>
 
+/** Entry point of the program. */
 int
 main (int argc, char **argv)
 {

tutorials/general/t8_step4_partition_balance_ghost.cxx

@@ -20,7 +20,8 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/* See also: https://github.com/DLR-AMR/t8code/wiki/Step-4---Partition,-Balance,-Ghost
+/** \file t8_step4_partition_balance_ghost.cxx
+ * See also: https://github.com/DLR-AMR/t8code/wiki/Step-4---Partition,-Balance,-Ghost
  *
  * This is step4 of the t8code tutorials.
  * After generating a coarse mesh (step1), building a uniform forest

tutorials/general/t8_step5.h

@@ -20,7 +20,7 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/** file t8_step5.h
+/** \file t8_step5.h
  */
 
 #ifndef T8_STEP5_H

tutorials/general/t8_step5_element_data.cxx

@@ -20,7 +20,8 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/* See also: https://github.com/DLR-AMR/t8code/wiki/Step-5---Store-element-data
+/** \file t8_step5_element_data.cxx
+ * See also: https://github.com/DLR-AMR/t8code/wiki/Step-5---Store-element-data
  *
  * This is step5 of the t8code tutorials.
  * In the following we will store data in the individual elements of our forest.
@@ -53,14 +54,19 @@
 
 T8_EXTERN_C_BEGIN ();
 
-/* The data that we want to store for each element.
+/** The data that we want to store for each element.
  * In this example we want to store the element's level and volume. */
 struct t8_step5_data_per_element
 {
-  int level;
-  double volume;
+  int level;     /**< The level of the element. */
+  double volume; /**< The volume of the element. */
 };
 
+/** Build an adapted, partitioned and balanced forest with ghost elements as the initial forest, to which we will add
+ * element data in subsequent steps.
+ * \param [in] comm   The MPI communicator to use.
+ * \param [in] level  An initial uniform refinement level.
+ */
 static t8_forest_t
 t8_step5_build_forest (sc_MPI_Comm comm, int level)
 {
@@ -89,6 +95,9 @@ t8_step5_build_forest (sc_MPI_Comm comm, int level)
   return forest_apbg;
 }
 
+/** Create an array for the element data of the forest.
+ * \param [in] forest The forest we want to create data for.
+ */
 static struct t8_step5_data_per_element *
 t8_step5_create_element_data (t8_forest_t forest)
 {
@@ -163,7 +172,7 @@ t8_step5_create_element_data (t8_forest_t forest)
   return element_data;
 }
 
-/* Each process has computed the data entries for its local elements.
+/** Each process has computed the data entries for its local elements.
  * In order to get the values for the ghost elements, we use t8_forest_ghost_exchange_data.
  * Calling this function will fill all the ghost entries of our element data array with the
  * value on the process that owns the corresponding element. */
@@ -186,7 +195,7 @@ t8_step5_exchange_ghost_data (t8_forest_t forest, struct t8_step5_data_per_eleme
   sc_array_destroy (sc_array_wrapper);
 }
 
-/* Write the forest as vtu and also write the element's volumes in the file.
+/** Write the forest as vtu and also write the element's volumes in the file.
  *
  * t8code supports writing element based data to vtu as long as its stored
  * as doubles. Each of the data fields to write has to be provided in its own

tutorials/general/t8_step5_element_data_c_interface.c

@@ -20,7 +20,8 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/* See also: https://github.com/DLR-AMR/t8code/wiki/Step-5---Store-element-data
+/** \file t8_step5_element_data_c_interface.c
+ * See also: https://github.com/DLR-AMR/t8code/wiki/Step-5---Store-element-data
  *
  * This is step5 of the t8code tutorials using the C interface of t8code.
  * In the following we will store data in the individual elements of our forest.

tutorials/general/t8_step5_main.cxx

@@ -20,13 +20,14 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/* This file is part of the step5 example of t8code.
+/** \file t8_step5_main.cxx This file is part of the step5 example of t8code.
  * Here, we only wrap the main function. See t8_step5_element_data.cxx for the documentation of
  * the step5 example.
  */
 
 #include <tutorials/general/t8_step5.h>
 
+/** Entry point of the program. */
 int
 main (int argc, char **argv)
 {

tutorials/general/t8_step6.h

@@ -20,7 +20,7 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/** file t8_step6.h
+/** \file t8_step6.h
  */
 
 #ifndef T8_STEP6_H

tutorials/general/t8_step6_main.cxx

@@ -20,13 +20,15 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/* This file is part of the step6 example of t8code.
+/** \file t8_step6_main.cxx
+ * This file is part of the step6 example of t8code.
  * Here, we only wrap the main function. See t8_step6_stencil.cxx for the documentation of
  * the step6 example.
  */
 
 #include <tutorials/general/t8_step6.h>
 
+/** Entry point of the program. */
 int
 main (int argc, char **argv)
 {