Merge branch 'documentation' into 'master'

Documentation maintenance

See merge request walberla/walberla!479

src/core/grid_generator/SCIterator.h

@@ -31,7 +31,7 @@ namespace grid_generator {
 
 /// Helper class to generate points in a simple cubic structure within a certain domain.
 /// The lattice is fixed by a point of reference (x).
-/// \code
+/// \code{.unparsed}
 /// . . . . . . . .
 ///        +-----+
 /// . . . .|. . .|.

src/core/logging/CMakeDefs.in.h

 //======================================================================================================================
 /*!
- *  \file   CMakeDefs.h
+ *  \file   CMakeDefs.in.h
  *  \brief  Definitions for core/logging configured by cmake
  */
 //======================================================================================================================

src/core/logging/Initialization.cpp

@@ -73,7 +73,7 @@ static void parseIgnoreBlocks( const Config::Blocks & ignoreBlocks, std::vector<
 *   This initialization function reads data stored in a configuration file and uses thi data to configure the logging
 *   singleton.
 *   The structure of the configuration file which is recognized by this function must look like as follows:
-*   \code
+*   \code{.unparsed}
 *   Logging { // the whole 'Logging' block is optional
 *
 *      logLevel       warning|info|progress|detail|tracing; // optional, default=info
@@ -102,7 +102,7 @@ static void parseIgnoreBlocks( const Config::Blocks & ignoreBlocks, std::vector<
 *
 *   Log messages can be ignored by specifying a regular expression on the filename and line number of the source
 *   file the log message originates from. The regex has to be specified in an ignore block as the parameter
-*   callerPathPattern. If the regular expression is found somewhere in the string <filename>:<line number>,
+*   callerPathPattern. If the regular expression is found somewhere in the string `<filename>:<line number>`,
 *   the log message is ignored. To divide components of your path always uses slashes!
 *   They will automatically be converted to the regex (/|\\), matching slashes and back-slashes. For fancy regexes
 *   you can use perl regex syntax.
@@ -110,11 +110,13 @@ static void parseIgnoreBlocks( const Config::Blocks & ignoreBlocks, std::vector<
 *   Note that you cannot ignore Errors since they abort your program!
 *
 *   Examples:
+*   \code{.unparsed}
 *   ignore { callerPathPattern /src/core/; } // ignores log messages from core
 *   ignore { callerPathPattern /src/vtk/; } // ignores log messages from vtk
 *   ignore { callerPathPattern (/src/core/|/src/vtk/); } // ignores log messages from core & vtk
 *   ignore { callerPathPattern /src/core/FILENAME.h:416; } // ignores a specific log message
 *   ignoreWarning { callerPathPattern /src/core/FILENAME.h:212; } // ignores a specific warning
+*   \endcode{.unparsed}
 *
 *   \param config The configuration
 */

src/core/math/CMakeDefs.in.h

 //======================================================================================================================
 /*!
- *  \file   CMakeDefs.h
+ *  \file   CMakeDefs.in.h
  *  \brief  Definitions for core/math configured by cmake
  */
 //======================================================================================================================

src/core/math/GenericAABB.h

@@ -132,9 +132,9 @@ public:
    inline value_type intersectionVolume( const GenericAABB & other ) const;
    inline GenericAABB getIntersection( const GenericAABB & other ) const;
 
-   inline bool isIdentical( const GenericAABB & rhs ) const;
+   inline bool isIdentical( const GenericAABB & other ) const;
 
-   inline bool isEqual( const GenericAABB & rhs ) const;
+   inline bool isEqual( const GenericAABB & other ) const;
 
    inline value_type sqDistance( const vector_type & point ) const;
    inline value_type sqSignedDistance( const vector_type & point ) const;

src/core/math/GenericAABB.impl.h

@@ -230,8 +230,8 @@ GenericAABB< T >::GenericAABB( const value_type minX, const value_type minY, con
 /**
  * \brief Builds a GenericAABB from a min- and a maxCorner
  *
- * \param minCorner corner with minimal values
- * \param maxCorner corner with maximal values
+ * \param theMinCorner corner with minimal values
+ * \param theMaxCorner corner with maximal values
  *
  * \pre minCorner.x <= maxCorner.x && minCorner.y <= maxCorner.y && minCorner.z <= maxCorner.z
  */
@@ -751,8 +751,8 @@ GenericAABB< T > GenericAABB< T >::getScaled( const value_type factor ) const
 /**
  * \brief Creates a new GenericAABB by scaling this one
  *
- * \param factor Vector of scaling factors by which the bounding box gets scaled on the
- *               respective axises.
+ * \param factors Vector of scaling factors by which the bounding box gets scaled on the
+ *                respective axises.
  *
  * \returns The scaled GenericAABB
  */
@@ -1450,10 +1450,14 @@ void GenericAABB< T >::init( InputIterator first, InputIterator last )
 /**
  * \brief Reinitializes this GenericAABB from a min- and a maxCorner
  *
- * \param minCorner corner with minimal values
- * \param maxCorner corner with maximal values
+ * \param minX  x-coordinate of the minCorner
+ * \param minY  y-coordinate of the minCorner
+ * \param minZ  z-coordinate of the minCorner
+ * \param maxX  x-coordinate of the maxCorner
+ * \param maxY  y-coordinate of the maxCorner
+ * \param maxZ  z-coordinate of the maxCorner
  *
- * \pre minCorner.x <= maxCorner.x && minCorner.y <= maxCorner.y && minCorner.z <= maxCorner.z
+ * \pre minX <= maxX && minY <= maxY && minZ <= maxZ
  */
 template< typename T >
 void GenericAABB< T >::initMinMaxCorner( const value_type minX, const value_type minY, const value_type minZ,
@@ -1475,14 +1479,10 @@ void GenericAABB< T >::initMinMaxCorner( const value_type minX, const value_type
 /**
  * \brief Reinitializes this GenericAABB from a min- and a maxCorner
  *
- * \param minX  x-coordinate of the minCorner
- * \param minY  y-coordinate of the minCorner
- * \param minZ  z-coordinate of the minCorner
- * \param maxX  x-coordinate of the maxCorner
- * \param maxY  y-coordinate of the maxCorner
- * \param maxZ  z-coordinate of the maxCorner
+ * \param theMinCorner corner with minimal values
+ * \param theMaxCorner corner with maximal values
  *
- * \pre x0 <= x1 && y0 <= y1 && z0 <= z1
+ * \pre theMinCorner.x <= theMaxCorner.x && theMinCorner.y <= theMaxCorner.y && theMinCorner.z <= theMaxCorner.z
  */
 template< typename T >
 void GenericAABB< T >::initMinMaxCorner( const vector_type & theMinCorner, const vector_type & theMaxCorner )
@@ -1498,7 +1498,7 @@ void GenericAABB< T >::initMinMaxCorner( const vector_type & theMinCorner, const
  * \brief Sets the minimum and maximum for one axis
  *
  * \param index   0 for x, 1 for y, 2 for z axis
- * \param value*  the smaller of the two values is taken as minimum, the other as maximum
+ * \param value1,value2  the smaller of the two values is taken as minimum, the other as maximum
  */
 template< typename T >
 void GenericAABB< T >::setAxisBounds( const uint_t index, const value_type value1, const value_type value2 )
@@ -1567,7 +1567,7 @@ void GenericAABB< T >::extend( const vector_type & eps )
  *
  * AABB gets translated such that its center matches the given center.
  *
- * \param new center location
+ * \param center new center location
  */
 template< typename T >
 void GenericAABB< T >::setCenter( const vector_type & center )
@@ -1616,8 +1616,8 @@ void GenericAABB< T >::scale( const value_type factor )
 /**
  * \brief Scales this GenericAABB
  *
- * \param factor Vector of scaling factors by which the bounding box gets scaled on the
- *               respective axises.
+ * \param factors Vector of scaling factors by which the bounding box gets scaled on the
+ *                respective axises.
  */
 template< typename T >
 void GenericAABB< T >::scale( const vector_type & factors )

src/core/math/Sample.cpp

@@ -115,7 +115,7 @@ real_t Sample::median() const
  * The variance calculated here is the _uncorrected_ variance.
  * See: http://en.wikipedia.org/w/index.php?title=Bessel%27s_correction&oldid=526066331
  *
- * \param    mean   the mean()
+ * \param    theMean   the mean()
  *
  * \returns  The uncorrected variance.
  **********************************************************************************************************************/

src/core/mpi/BufferSystem.impl.h

@@ -13,7 +13,7 @@
 //  You should have received a copy of the GNU General Public License along
 //  with waLBerla (see COPYING.txt). If not, see <http://www.gnu.org/licenses/>.
 //
-//! \file GenericBufferSystem.cpp
+//! \file BufferSystem.impl.h
 //! \ingroup core
 //! \author Martin Bauer <martin.bauer@fau.de>
 //

src/core/mpi/BufferSystemHelper.h

@@ -83,7 +83,7 @@ namespace internal {
       /*************************************************************************************************************//**
       * Waits for the next receive to complete and returns.
       *
-      * \param recvInfo  the same receive info that was passed to scheduleReceives()
+      * \param recvInfos  the same receive info that was passed to scheduleReceives()
       *
       * \return The rank where the data was received -> recvInfos[rank] is now valid
       *         INVALID_RANK if all messages were received.

src/core/mpi/BufferSystemHelper.impl.h

@@ -13,7 +13,7 @@
 //  You should have received a copy of the GNU General Public License along
 //  with waLBerla (see COPYING.txt). If not, see <http://www.gnu.org/licenses/>.
 //
-//! \file BufferSystemHelper.cpp
+//! \file BufferSystemHelper.impl.h
 //! \ingroup core
 //! \author Martin Bauer <martin.bauer@fau.de>
 //

src/core/mpi/Gatherv.h

@@ -198,11 +198,11 @@ std::vector< std::string > allGatherv( const std::vector< std::string > & values
 * - the buffer contents are gathered on process with targetRank
 * - buffer contents are sorted by rank and stored consecutively in a mpi::RecvBuffer
 *
-* \param sendBuffer [in]  sendBuffer with (possibly) different size on each process
-* \param recvBuffer [out] recvBuffer which is left unchanged on all processes but targetRank
+* \param[in]  sendBuffer  sendBuffer with (possibly) different size on each process
+* \param[out] recvBuffer  recvBuffer which is left unchanged on all processes but targetRank
 *                         on targetRank  recvBuffer holds the gathered result
-* \param targetRank [in]  rank of the process where data is gathered
-* \param comm       [in]  mpi communicator to use
+* \param[in]  targetRank  rank of the process where data is gathered
+* \param[in]  comm        mpi communicator to use
 */
 //*******************************************************************************************************************
 void gathervBuffer( const mpi::SendBuffer & sendBuffer, mpi::RecvBuffer & recvBuffer, int targetRank = 0, MPI_Comm comm = MPI_COMM_WORLD );

src/core/mpi/MPIIO.cpp

@@ -13,7 +13,7 @@
 //  You should have received a copy of the GNU General Public License along
 //  with waLBerla (see COPYING.txt). If not, see <http://www.gnu.org/licenses/>.
 //
-//! \file MPIIO.cppp
+//! \file MPIIO.cpp
 //! \ingroup core
 //! \author Florian Schornbaum <florian.schornbaum@fau.de>
 //! \author Martin Bauer <martin.bauer@fau.de>

src/core/mpi/MPITextFile.cpp

@@ -40,6 +40,7 @@ namespace mpi
  *
  *  \param filename          The name of the file to be written
  *  \param processLocalPart  The part of the file belonging to the calling process (size may differ among processes)
+ *  \param comm              The MPI communicator used for communication
  */
 //======================================================================================================================
 void writeMPITextFile(const std::string& filename, const std::string& processLocalPart,

src/core/mpi/OpenMPBufferSystem.impl.h

@@ -13,7 +13,7 @@
 //  You should have received a copy of the GNU General Public License along
 //  with waLBerla (see COPYING.txt). If not, see <http://www.gnu.org/licenses/>.
 //
-//! \file OpenMPBufferSystem.cpp
+//! \file OpenMPBufferSystem.impl.h
 //! \ingroup core
 //! \author Martin Bauer <martin.bauer@fau.de>
 //

src/core/mpi/Reduce.h

@@ -434,10 +434,10 @@ void allReduceInplace( std::vector<T> & values, Operation operation, MPI_Comm co
 //======================================================================================================================
 /*!
  *  \brief Reduces values in a std::vector<bool> over all processes in-place
- *  		  
+ *
  *  Specialization of allReduceInplace<T>
- *  		  
- *  \param values     The boolean values to be reduced
+ *
+ *  \param bools      The boolean values to be reduced
  *  \param operation  The operation to be performed (one of BITWISE_AND, BITWISE_OR or BITWISE_XOR)
  *  \param comm       The MPI communicator used for communication
  */

src/core/selectable/AllSetSelectableObject.h

@@ -37,7 +37,7 @@ namespace selectable {
 *   \brief Implementation of SelectableObject using sets (see "AllSet.h") as selection attributes
 *
 *   AllSetSelectableObject is an implementation of SelectableObject that stores objects of type T which are attached
-*   with selection attributes of type AllSet<U>. For information on which objects are selected given a certain set as
+*   with selection attributes of type `AllSet<U>`. For information on which objects are selected given a certain set as
 *   selection request see the documentation of the function "select".
 */
 //**********************************************************************************************************************

src/core/selectable/SetSelectableObject.h

@@ -38,8 +38,8 @@ namespace selectable {
 *          selection attributes, and objects of type Set (see "Set.h") as selector
 *
 *   SetSelectableObject is an implementation of SelectableObject that stores objects of type T which are attached with
-*   selection attributes of type SetSelectionPair<U>. Every object of type SetSelectionPair<U> contains two sets of
-*   type Set<U> - one "include" and one "exclude" set. For information on which objects are selected given a certain
+*   selection attributes of type `SetSelectionPair<U>`. Every object of type `SetSelectionPair<U>` contains two sets of
+*   type `Set<U>` - one "include" and one "exclude" set. For information on which objects are selected given a certain
 *   selection request see the documentation of the function "select".
 */
 //**********************************************************************************************************************

src/core/timing/Timer.h

@@ -204,11 +204,11 @@ inline Timer<TP>::Timer()
 //**********************************************************************************************************************
 /*!\brief Constructor of the Timer class.
 // Initializes the timer with
-// \param counter      number of timing measurements already done
-// \param min          the minimum time of the measurements
-// \param max          the maximum time of the measurements
-// \param total        the total time of all measurements
-// \param sumOfSquares each measurement time squared, then summed
+// \param _counter      number of timing measurements already done
+// \param _min          the minimum time of the measurements
+// \param _max          the maximum time of the measurements
+// \param _total        the total time of all measurements
+// \param _sumOfSquares each measurement time squared, then summed
 */
 template< typename TP>
 inline Timer<TP>::Timer( uint_t _counter, double _min, double _max,

src/core/waLBerlaBuildInfo.in.cpp

 //======================================================================================================================
 /*!
- *  \file   waLBerlaBuildInfo.cpp
+ *  \file   waLBerlaBuildInfo.in.cpp
  *  \brief  Configured by CMake, contains information about the current build
  */
 //======================================================================================================================

src/cuda/ExecutionTreeGPU.h

@@ -13,7 +13,7 @@
 //  You should have received a copy of the GNU General Public License along
 //  with waLBerla (see COPYING.txt). If not, see <http://www.gnu.org/licenses/>.
 //
-//! \file TaskTree.h
+//! \file ExecutionTreeGPU.h
 //! \ingroup cuda
 //! \author Martin Bauer <martin.bauer@fau.de>
 //