Merge pull request #1850 from DLR-AMR/src_documentation

Documentation: Fix doxygen errors in src

Author: Davknapp

src/t8.h

@@ -119,19 +119,25 @@ typedef uint64_t t8_linearidx_t;
 /** The MPI datatype of t8_linearidx_t */
 #define T8_MPI_LINEARIDX sc_MPI_UNSIGNED_LONG_LONG
 
+/** The padding size is the size of a void pointer*/
 #define T8_PADDING_SIZE (sizeof (void *))
 /** Compute the number of bytes that have to be added to a given byte_count
  * such that it is a multiple of the padding size */
 #define T8_ADD_PADDING(_x) ((T8_PADDING_SIZE - ((_x) % T8_PADDING_SIZE)) % T8_PADDING_SIZE)
 
-/** Define precisions for computations */
+/** Define machine precision for computations */
 #define T8_PRECISION_EPS SC_EPS
+/** Define square root of machine precision for computations */
 #define T8_PRECISION_SQRT_EPS sqrt (T8_PRECISION_EPS)
 
 /** Access multidimensional data on one-dimensional C arrays. */
+/** Access onedimensional data on one-dimensional C arrays. */
 #define T8_1D_TO_1D(nx, i) (i)
+/** Access twodimensional data on one-dimensional C arrays. */
 #define T8_2D_TO_1D(nx, ny, i, j) ((i) * (ny) + (j))
+/** Access threedimensional data on one-dimensional C arrays. */
 #define T8_3D_TO_1D(nx, ny, nz, i, j, k) (((i) * (ny) + (j)) * (nz) + (k))
+/** Access fourdimensional data on one-dimensional C arrays. */
 #define T8_4D_TO_1D(nx, ny, nz, nl, i, j, k, l) ((((i) * (ny) + (j)) * (nz) + (k)) * (nl) + (l))
 
 /** Communication tags used internal to t8code. */
@@ -283,11 +289,12 @@ void
 t8_init (int log_threshold);
 
 /** Return a pointer to an array element indexed by a t8_locidx_t.
+ * \param [in] array The array of elements.
  * \param [in] index needs to be in [0]..[elem_count-1].
- * \return           A void * pointing to entry \a it in \a array.
+ * \return           A void * pointing to entry \a index in \a array.
  */
 void *
-t8_sc_array_index_locidx (const sc_array_t *array, const t8_locidx_t it);
+t8_sc_array_index_locidx (const sc_array_t *array, const t8_locidx_t index);
 
 /* call this at the end of a header file to match T8_EXTERN_C_BEGIN (). */
 T8_EXTERN_C_END ();

src/t8_cmesh.h

@@ -33,7 +33,7 @@
 #include <t8_element.h>
 #include <t8_schemes/t8_scheme.h>
 
-/* Forward pointer reference to hidden cmesh implementation.
+/** Forward pointer reference to hidden cmesh implementation.
  * This reference needs to be known by t8_geometry, hence we 
  * put it before the include. */
 typedef struct t8_cmesh *t8_cmesh_t;
@@ -54,9 +54,11 @@ typedef struct t8_cmesh *t8_cmesh_t;
  *       edit: This should be achieved now.
  */
 
-/* Forward pointer references to hidden implementations of
- * tree and ghost tree. */
+/** Forward pointer references to hidden implementations of
+ * tree. */
 typedef struct t8_ctree *t8_ctree_t;
+/** Forward pointer references to hidden implementations of
+ * ghost tree. */
 typedef struct t8_cghost *t8_cghost_t;
 
 T8_EXTERN_C_BEGIN ();
@@ -146,7 +148,7 @@ t8_cmesh_set_derive (t8_cmesh_t cmesh, t8_cmesh_t set_from);
  * \param [in]      mpisize The number of processes.
  * \param [in]      comm    The MPI communicator to use. Its mpisize must match \a mpisize.
  *                  The shared memory type must have been set. Best practice would be
- *                  calling \ref sc_shmem_set_type (comm, T8_SHMEM_BEST_TYPE).
+ *                  calling sc_shmem_set_type (comm, T8_SHMEM_BEST_TYPE).
  * \return          A t8_shmem_array struct that stores \a mpisize + 1 t8_gloidx_t entries.
  * \see t8_shmem.h
  */
@@ -751,7 +753,7 @@ t8_cmesh_get_partition_table (t8_cmesh_t cmesh);
 /** Calculate the section of a uniform forest for the current rank.
  * \param [in]    cmesh         The cmesh to be considered.
  * \param [in]    level         The uniform refinement level to be created.
- * \param [in]    scheme            The element scheme for which to compute the bounds.
+ * \param [in]    tree_scheme      The element scheme for which to compute the bounds.
  * \param [out]   first_local_tree  The first tree that contains elements belonging to the calling processor.
  * \param [out]   child_in_tree_begin The tree-local index of the first element belonging to the calling processor. Not computed if NULL.
  * \param [out]   last_local_tree  The last tree that contains elements belonging to the calling processor.
@@ -770,7 +772,7 @@ t8_cmesh_uniform_bounds_equal_element_count (t8_cmesh_t cmesh, const int level,
 /**
  * Calculate the section of a uniform hybrid forest for the current rank. Needed for hybrid meshes, especially 
  * meshes where not all elements refine into 1:2^dim manner. The section is calculated without assuming such refinement
- * and each process computes its number of elements on the given \var level, communicates the number to other processes,
+ * and each process computes its number of elements on the given \a level, communicates the number to other processes,
  * and the correct section is computed based on this information. 
  * 
  * \param [in] cmesh        The cmesh to be considered.
@@ -819,7 +821,6 @@ t8_cmesh_unref (t8_cmesh_t *pcmesh);
  * \param [in,out]  pcmesh      This cmesh must have a reference count of one.
  *                              It can be in any state (committed or not).
  *                              Then it effectively calls \ref t8_cmesh_unref.
- * \param [in]      comm        A mpi communicator that is valid with \a cmesh.
  */
 void
 t8_cmesh_destroy (t8_cmesh_t *pcmesh);

src/t8_element.h

@@ -40,13 +40,13 @@ T8_EXTERN_C_BEGIN ();
 typedef struct t8_element t8_element_t;
 
 /** This array holds the reference coordinates of each vertex of each element.
- *  It can e.g. be used with the \ref t8_element_reference_coords function.
+ *  It can e.g. be used with the \ref t8_scheme::element_get_reference_coords function.
  *  Usage: t8_element_corner_ref_coords[eclass][vertex][dimension]
  */
 extern const double t8_element_corner_ref_coords[T8_ECLASS_COUNT][T8_ECLASS_MAX_CORNERS][3];
 
 /** This array holds the reference coordinates of the centroid of each element.
- *  It can e.g. be used with the \ref t8_element_reference_coords function.
+ *  It can e.g. be used with the \ref t8_scheme::element_get_reference_coords function.
  *  Usage: t8_element_centroid_ref_coords[eclass][dimension]
  */
 extern const double t8_element_centroid_ref_coords[T8_ECLASS_COUNT][3];

src/t8_element_shape.h

@@ -45,7 +45,7 @@ typedef t8_eclass_t t8_element_shape_t;
 /** The maximum number of cornes a 3-dimensional element class can have. */
 #define T8_ELEMENT_SHAPE_MAX_CORNERS 8
 
-/* Maximum possible number of corner nodes of an element in a specific dimension */
+/** Maximum possible number of corner nodes of an element in a specific dimension */
 extern const int t8_element_shape_max_num_corner[T8_ECLASS_MAX_DIM + 1];
 
 /** The number of codimension-one boundaries of an element class. */

src/t8_mat.h

@@ -114,7 +114,7 @@ t8_mat_mult_vec (const double mat[3][3], const double a[3], double b[3])
 /** Apply matrix-matrix multiplication: C = A*B.
  * \param [in]        A     3x3-matrix.
  * \param [in]        B     3x3-matrix.
- * \param [int,out]   C     3x3-matrix.
+ * \param [in,out]    C     3x3-matrix.
  */
 static inline void
 t8_mat_mult_mat (const double A[3][3], const double B[3][3], double C[3][3])

src/t8_netcdf.h

@@ -47,14 +47,20 @@ typedef enum t8_netcdf_variable_type {
   T8_NETCDF_DOUBLE = 2
 } t8_netcdf_variable_type_t;
 
-/* Struct for elementwise data variable for a NetCDF file */
+/** Struct for elementwise data variable for a NetCDF file */
 typedef struct
 {
+  /** short name of the variable*/
   const char *variable_name;
+  /** long name of the variable*/
   const char *variable_long_name;
+  /** unit of the variable*/
   const char *variable_units;
+  /** datatype of the variable*/
   t8_netcdf_variable_type_t datatype;
+  /** The unique identifier netCDF assigns to this variable once it is defined in the file*/
   int var_user_dimid;
+  /** user data for the variable*/
   sc_array_t *var_user_data;
 } t8_netcdf_variable_t;
 
@@ -64,7 +70,6 @@ typedef struct
  * \param [in]  var_long_name    A string describing the variable a bit more and what it is about.
  * \param [in]  var_unit    The units in which the data is provided.
  * \param [in]  var_data    A sc_array_t holding the elementwise data of the variable.
- * \param [in]  num_extern_netcdf_vars    The number of extern user-defined variables which hold elementwise data (if none, set it to 0).
  */
 t8_netcdf_variable_t *
 t8_netcdf_create_var (t8_netcdf_variable_type_t var_type, const char *var_name, const char *var_long_name,
@@ -75,7 +80,6 @@ t8_netcdf_create_var (t8_netcdf_variable_type_t var_type, const char *var_name,
  * \param [in]  var_long_name    A string describing the variable a bit more and what it is about.
  * \param [in]  var_unit    The units in which the data is provided.
  * \param [in]  var_data    A sc_array_t holding the elementwise data of the variable.
- * \param [in]  num_extern_netcdf_vars    The number of extern user-defined variables which hold elementwise data (if none, set it to 0).
  */
 t8_netcdf_variable_t *
 t8_netcdf_create_integer_var (const char *var_name, const char *var_long_name, const char *var_unit,
@@ -86,7 +90,6 @@ t8_netcdf_create_integer_var (const char *var_name, const char *var_long_name, c
  * \param [in]  var_long_name    A string describing the variable a bit more and what it is about.
  * \param [in]  var_unit    The units in which the data is provided.
  * \param [in]  var_data    A sc_array_t holding the elementwise data of the variable.
- * \param [in]  num_extern_netcdf_vars    The number of extern user-defined variables which hold elementwise data (if none, set it to 0).
  */
 t8_netcdf_variable_t *
 t8_netcdf_create_double_var (const char *var_name, const char *var_long_name, const char *var_unit,

src/t8_version.h

@@ -51,9 +51,11 @@
 #include <t8_config.h>
 #endif
 
-/* In order to convert a macro to a string, we
+/** In order to convert a macro to a string, we
  * need to pass it through these two helper macros. */
 #define T8_STRINGIFY(arg) #arg
+/** In order to convert a macro to a string, we
+ * need to pass it through these two helper macros. */
 #define T8_STRINGIFY_MIDDLE(arg) T8_STRINGIFY (arg)
 
 /** The T8_VERSION_POINT macro as a string */