Merge branch 'documentation' into 'master'

Documentation maintenance

See merge request !479

src/cuda/FieldAccessor.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 SimpleFieldAccessor.h
+//! \file FieldAccessor.h
 //! \ingroup cuda
 //! \author Martin Bauer <martin.bauer@fau.de>
 //

src/cuda/FieldIndexing.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 SimpleFieldIndexing.h
+//! \file FieldIndexing.h
 //! \ingroup cuda
 //! \author Martin Bauer <martin.bauer@fau.de>
 //! \brief Indexing Scheme that executes all elements of inner coordinate within on thread block

src/cuda/FieldIndexing.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 SimpleFieldIndexing.cpp
+//! \file FieldIndexing.impl.h
 //! \ingroup cuda
 //! \author Martin Bauer <martin.bauer@fau.de>
 //

src/cuda/FieldIndexing3D.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 FieldIndexing3D.cpp
+//! \file FieldIndexing3D.impl.h
 //! \ingroup cuda
 //! \author Paulo Carvalho <prcjunior@inf.ufpr.br>
 //

src/cuda/FieldIndexingXYZ.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 FieldIndexingXYZ.cpp
+//! \file FieldIndexingXYZ.impl.h
 //! \ingroup cuda
 //! \author Martin Bauer <martin.bauer@fau.de>
 //

src/cuda/GPUCopy.h

@@ -40,9 +40,10 @@ namespace cuda {
  * \param src           source buffer
  * \param dstOffset     (x, y, z, f)-tuple containing the coordinate of the interval start point in the destination buffer
  * \param srcOffset     (x, y, z, f)-tuple containing the coordinate of the interval start point in the source buffer
- * \param dstAllocSizeY allocation size in y direction of the destination buffer
- * \param srcAllocSizeY allocation size in y direction of the source buffer
+ * \param dstAllocSizeZ allocation size in z direction of the destination buffer
+ * \param srcAllocSizeZ allocation size in z direction of the source buffer
  * \param typeSize      size of an f element
+ * \param intervalSize  interval size
  * \param copyStream    CUDA stream, if not NULL copy operations will be performed asynchronously
  *****************************************************************************************************************************/
 void copyDevToDevFZYX( const cudaPitchedPtr& dst, const cudaPitchedPtr& src,
@@ -62,6 +63,7 @@ void copyDevToDevFZYX( const cudaPitchedPtr& dst, const cudaPitchedPtr& src,
  * \param dstAllocSizeY allocation size in y direction of the destination buffer
  * \param srcAllocSizeY allocation size in y direction of the source buffer
  * \param typeSize      size of an f element
+ * \param intervalSize  interval size
  * \param copyStream    CUDA stream, if not NULL copy operations will be performed asynchronously
  *****************************************************************************************************************************/
 void copyDevToDevZYXF( const cudaPitchedPtr& dst, const cudaPitchedPtr& src,
@@ -72,7 +74,7 @@ void copyDevToDevZYXF( const cudaPitchedPtr& dst, const cudaPitchedPtr& src,
                        cudaStream_t copyStream );
 
 //*******************************************************************************************************************
-/*! Copy a 4D interval of a host buffer to a device buffer with fzyx memory layout. See copyDevToDevFZYX() for
+/*! Copy a 4D interval of a host buffer to a device buffer with fzyx memory layout. See \ref copyDevToDevFZYX() for
  * parameter information.
  *******************************************************************************************************************/
 void copyHostToDevFZYX( const cudaPitchedPtr& dst, unsigned char* src,
@@ -83,7 +85,7 @@ void copyHostToDevFZYX( const cudaPitchedPtr& dst, unsigned char* src,
                         cudaStream_t copyStream );
 
 //*******************************************************************************************************************
-/*! Copy a 4D interval of a host buffer to a device buffer with zyxf memory layout. See copyDevToDevZYXF() for
+/*! Copy a 4D interval of a host buffer to a device buffer with zyxf memory layout. See \ref copyDevToDevZYXF() for
  * parameter information.
  *******************************************************************************************************************/
 void copyHostToDevZYXF( const cudaPitchedPtr& dst, unsigned char* src,
@@ -94,7 +96,7 @@ void copyHostToDevZYXF( const cudaPitchedPtr& dst, unsigned char* src,
                         cudaStream_t copyStream );
 
 //*******************************************************************************************************************
-/*! Copy a 4D interval of a device buffer to a host buffer with fzyx memory layout. See copyDevToDevFZYX() for
+/*! Copy a 4D interval of a device buffer to a host buffer with fzyx memory layout. See \ref copyDevToDevFZYX() for
  * parameter information.
  *******************************************************************************************************************/
 void copyDevToHostFZYX( unsigned char* dst, const cudaPitchedPtr& src,
@@ -105,7 +107,7 @@ void copyDevToHostFZYX( unsigned char* dst, const cudaPitchedPtr& src,
                         cudaStream_t copyStream );
 
 //*******************************************************************************************************************
-/*! Copy a 4D interval of a device buffer to a host buffer with zyxf memory layout. See copyDevToDevZYXF() for
+/*! Copy a 4D interval of a device buffer to a host buffer with zyxf memory layout. See \ref copyDevToDevZYXF() for
  * parameter information.
  *******************************************************************************************************************/
 void copyDevToHostZYXF( unsigned char* dst, const cudaPitchedPtr& src,

src/cuda/GPUField.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 GPUField.cpp
+//! \file GPUField.impl.h
 //! \ingroup cuda
 //! \author Martin Bauer <martin.bauer@fau.de>
 //

src/cuda/HostFieldAllocator.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 CudaHostFieldAllocator.h
+//! \file HostFieldAllocator.h
 //! \ingroup cuda
 //! \author Martin Bauer <martin.bauer@fau.de>
 //! \brief Allocator that allocates a CPU! field using cudaHostAlloc

src/cuda/communication/CustomMemoryBuffer.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 BasicBuffer.h
+//! \file CustomMemoryBuffer.h
 //! \ingroup cuda
 //! \author Martin Bauer <martin.bauer@fau.de>
 //! \brief Basic Buffer supporting different memory spaces

src/cuda/communication/CustomMemoryBuffer.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 BasicBuffer.h
+//! \file CustomMemoryBuffer.impl.h
 //! \ingroup cuda
 //! \author Martin Bauer <martin.bauer@fau.de>
 //

src/executiontree/ExecutionTree.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 TaskTree.cpp
+//! \file ExecutionTree.cpp
 //! \ingroup executiontree
 //! \author Martin Bauer <martin.bauer@fau.de>
 //

src/executiontree/ExecutionTree.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 ExecutionTree.h
 //! \ingroup executiontree
 //! \author Martin Bauer <martin.bauer@fau.de>
 //
@@ -57,7 +57,7 @@ template< typename FunctorType > class SharedSweep;
 
 /*! Creates a functor node around any callable object. The wrapped functor is copied.
  *
- * \param any callable object. The object is copied - if its state has to be modified later, pass a shared_ptr to a functor instead
+ * \param t callable object. The object is copied - if its state has to be modified later, pass a shared_ptr to a functor instead
  * \param name optional name of the functor node
  * \param timingTree optional timing tree object to time all executions of this functor
  */
@@ -86,7 +86,7 @@ shared_ptr< Sequence > parallelSequence( std::initializer_list< IFunctionNodePtr
 /*! Note that runs its contents only every n'th call
  *
  * \param node task that is only run every n'th call
- * \param name the interval i.e. "n"
+ * \param interval the interval i.e. "n"
  * \param onFirst if false the task is not run at the first call
  * \param startValue initial call counter
  */

src/executiontree/ExecutionTree.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 TaskTree.impl.h
+//! \file ExecutionTree.impl.h
 //! \ingroup executiontree
 //! \author Martin Bauer <martin.bauer@fau.de>
 //

src/executiontree/ExecutionTreeSweep.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 ExecutionTreeSweep.h
 //! \ingroup executiontree
 //! \author Martin Bauer <martin.bauer@fau.de>
 //

src/field/AddToStorage.h

@@ -223,11 +223,9 @@ BlockDataID addToStorage( const shared_ptr< BlockStorage_T > & blocks,
 //**********************************************************************************************************************
 /*! Adds a copy of an existing field to BlockStorage
 *
-* Template parameters:
-*   Field_T         the type of the field that should be cloned ( and the type that is created )
-*   BlockStorage_T  the type of the BlockStorage ( will be deduced automatically )
+*   \tparam Field_T         the type of the field that should be cloned ( and the type that is created )
+*   \tparam BlockStorage_T  the type of the BlockStorage ( will be deduced automatically )
 *
-* Parameters:
 *   \param blocks        BlockStorage where the original field is stored and the new one is created
 *   \param fieldToClone  BlockDataID of the Field that is cloned
 *   \param identifier    name for new the field ( displayed in GUI and debugging functions )
@@ -253,11 +251,9 @@ BlockDataID addCloneToStorage( const shared_ptr< BlockStorage_T > & blocks,
 //**********************************************************************************************************************
 /*! Adds a flattened shallow copy of an existing field to BlockStorage
 *
-* Template parameters:
-*   Field_T         the type of the field that should be cloned and flattened
-*   BlockStorage_T  the type of the BlockStorage ( will be deduced automatically )
+*   \tparam Field_T         the type of the field that should be cloned and flattened
+*   \tparam BlockStorage_T  the type of the BlockStorage ( will be deduced automatically )
 *
-* Parameters:
 *   \param blocks        BlockStorage where the original field is stored and the new one is created
 *   \param fieldToClone  BlockDataID of the Field that is cloned
 *   \param identifier    name for new the field ( displayed in GUI and debugging functions )

src/field/CMakeDefs.in.h

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

src/field/Field.impl.h

@@ -54,10 +54,10 @@ namespace field {
    //*******************************************************************************************************************
    /*!Creates an uninitialized field of given size
     *
-    * \param xSize  size of x dimension
-    * \param ySize  size of y dimension
-    * \param zSize  size of z dimension
-    * \param layout memory layout of the field (see Field::Layout)
+    * \param _xSize  size of x dimension
+    * \param _ySize  size of y dimension
+    * \param _zSize  size of z dimension
+    * \param l       memory layout of the field (see Field::Layout)
     * \param alloc  class that describes how to allocate memory for the field, see FieldAllocator
     *******************************************************************************************************************/
    template<typename T, uint_t fSize_>
@@ -72,11 +72,11 @@ namespace field {
    //*******************************************************************************************************************
    /*! Creates a field and initializes it with constant
     *
-    * \param xSize   size of x dimension
-    * \param ySize   size of y dimension
-    * \param zSize   size of z dimension
+    * \param _xSize  size of x dimension
+    * \param _ySize  size of y dimension
+    * \param _zSize  size of z dimension
     * \param initVal every element of the field is set to initVal
-    * \param layout  memory layout of the field (see Field::Layout)
+    * \param l       memory layout of the field (see Field::Layout)
     * \param alloc  class that describes how to allocate memory for the field, see FieldAllocator
     *******************************************************************************************************************/
    template<typename T, uint_t fSize_>
@@ -92,11 +92,11 @@ namespace field {
    //*******************************************************************************************************************
    /*! Creates a field and initializes f coordinate with vector values
     *
-    * \param xSize   size of x dimension
-    * \param ySize   size of y dimension
-    * \param zSize   size of z dimension
+    * \param _xSize  size of x dimension
+    * \param _ySize  size of y dimension
+    * \param _zSize  size of z dimension
     * \param fValues initializes f coordinate with values from vector (see set(std::vector&) )
-    * \param layout  memory layout of the field (see Field::Layout)
+    * \param l       memory layout of the field (see Field::Layout)
     * \param alloc  class that describes how to allocate memory for the field, see FieldAllocator
     *******************************************************************************************************************/
    template<typename T, uint_t fSize_>
@@ -114,6 +114,9 @@ namespace field {
    /*! Deletes all stored data, and resizes the field
     *
     *  The resized field is uninitialized.
+    * \param _xSize  size of x dimension
+    * \param _ySize  size of y dimension
+    * \param _zSize  size of z dimension
     *******************************************************************************************************************/
    template<typename T, uint_t fSize_>
    void Field<T,fSize_>::resize( uint_t _xSize, uint_t _ySize, uint_t _zSize )
@@ -294,10 +297,10 @@ namespace field {
     * Must be called exactly once!  This is automatically called by all constructors
     * that take at least one argument
     *
-    * \param xSize   size of x dimension
-    * \param ySize   size of y dimension
-    * \param zSize   size of z dimension
-    * \param layout  memory layout of the field (see Field::Layout)
+    * \param _xSize  size of x dimension
+    * \param _ySize  size of y dimension
+    * \param _zSize  size of z dimension
+    * \param l       memory layout of the field (see Field::Layout)
     * \param alloc   the allocator to use. If a NULL shared pointer is given, a sensible default is selected,
     *                depending on layout
     * \param innerGhostLayerSizeForAlignedAlloc
@@ -1082,8 +1085,12 @@ namespace field {
     * This is used for example in the constructor of the GhostLayerField
     *
     * Internally this is implementing by adding an offset to the values_ pointer, and by adapting the size_ members.
-    * \param xOff The x coordinate that is afterwards mapped to zero
-    * \param xs   The new size of the x coordinate. Has to be smaller than (old xSize())-xOff
+    * \param xOffset The x coordinate that is afterwards mapped to zero
+    * \param xs      The new size of the x coordinate. Has to be smaller than (old xSize())-xOffset
+    * \param yOffset The y coordinate that is afterwards mapped to zero
+    * \param ys      The new size of the y coordinate. Has to be smaller than (old ySize())-yOffset
+    * \param zOffset The z coordinate that is afterwards mapped to zero
+    * \param zs      The new size of the z coordinate. Has to be smaller than (old zSize())-zOffset
     *******************************************************************************************************************/
    template<typename T, uint_t fSize_>
    void Field<T,fSize_>::setOffsets(uint_t xOffset, uint_t xs,

src/field/FlagField.impl.h

@@ -48,9 +48,9 @@ namespace field {
    //*******************************************************************************************************************
    /*!\brief Constructor. Initializes field with 0 (no flags set).
     *
-    * \param xSize  size of x dimension without ghost layers
-    * \param ySize  size of y dimension without ghost layers
-    * \param zSize  size of z dimension without ghost layers
+    * \param xs     size of x dimension without ghost layers
+    * \param ys     size of y dimension without ghost layers
+    * \param zs     size of z dimension without ghost layers
     * \param gl     number of ghost layers
     * \param alloc  class that describes how to allocate memory for the field, see FieldAllocator
     *******************************************************************************************************************/
@@ -139,8 +139,8 @@ namespace field {
    //*******************************************************************************************************************
    /*!\brief Adds every (inner) cell where at least all bits of mask are set to the CellVector (in inner coordinates)
     *
-    * \param mask [in]  bit mask. Test if a cell is added: (content & mask) == true
-    * \param cv   [out] cell vector where the cells are added to, in inner coordinates
+    * \param[in]  mask  bit mask. Test if a cell is added: (content & mask) == true
+    * \param[out] cv    cell vector where the cells are added to, in inner coordinates
     *******************************************************************************************************************/
    template<typename T>
    void  FlagField<T>::getCellsWhereMaskIsSet(T mask, CellVector & cv) const
@@ -195,7 +195,7 @@ namespace field {
    //*******************************************************************************************************************
    /*!\brief Registers a flag. Uses the next free bit in the field.
     *
-    * \param uid    uid of the flag
+    * \param uid    UID for the flag
     * \return       Mask, that has exactly one bit set to one.
     *******************************************************************************************************************/
    template<typename T>
@@ -230,7 +230,7 @@ namespace field {
     *
     * If bitNr is not important use registerFlag(name) which assigns the next free bit to the flag.
     *
-    * \param name   string identifier for the flag
+    * \param uid    UID for the flag
     * \param bitNr  The bit nr associated with the flag (NOT the mask!). Has to be smaller than sizeof(flag_type)*8
     *               There exists also a function where this information is not needed, and the next free bit is used.
     * \return       Mask, that has the given bit set to one i.e. 1 << bitNr
@@ -484,7 +484,8 @@ namespace field {
     //******************************************************************************************************************
     /*!\brief Ores the neighborhood of the specified stencil and checks whether the bits of mask are set
      *
-     * \param mask [in]  bit mask. Test if a cell is added: (content & mask) == true
+     * \param[in] i     field pointer.
+     * \param[in] mask  bit mask. Test if a cell is added: (content & mask) == true
      ******************************************************************************************************************/
     template<class Sten, typename FieldPtrOrIterator>
     inline bool isFlagInNeighborhood(const FieldPtrOrIterator & i, typename FieldPtrOrIterator::value_type mask)
@@ -507,6 +508,7 @@ namespace field {
 
     //******************************************************************************************************************
     /*!\brief Ores the neighborhood of the specified stencil and returns mask
+     * \param[in] i     field pointer.
      ******************************************************************************************************************/
     template<class Sten, typename FieldPtrOrIterator>
     inline typename std::remove_const<typename FieldPtrOrIterator::value_type>::type

src/field/GhostLayerField.impl.h

@@ -53,11 +53,11 @@ namespace field {
    //*******************************************************************************************************************
    /*!\brief Creates an uninitialized field of given size
     *
-    * \param xSize  size of x dimension without ghost layers
-    * \param ySize  size of y dimension without ghost layers
-    * \param zSize  size of z dimension without ghost layers
+    * \param _xSize size of x dimension without ghost layers
+    * \param _ySize size of y dimension without ghost layers
+    * \param _zSize size of z dimension without ghost layers
     * \param gl     number of ghost layers
-    * \param layout memory layout of the field (see Layout)
+    * \param l      memory layout of the field (see Layout)
     * \param alloc  class that describes how to allocate memory for the field, see FieldAllocator
     *******************************************************************************************************************/
    template<typename T, uint_t fSize_>
@@ -71,12 +71,12 @@ namespace field {
    //*******************************************************************************************************************
    /*!\brief Creates a field and initializes it with constant value
     *
-    * \param xSize   size of x dimension without ghost layers
-    * \param ySize   size of y dimension without ghost layers
-    * \param zSize   size of z dimension without ghost layers
+    * \param _xSize  size of x dimension without ghost layers
+    * \param _ySize  size of y dimension without ghost layers
+    * \param _zSize  size of z dimension without ghost layers
     * \param gl      number of ghost layers
     * \param initVal every element of the field is set to initVal (also ghost layers)
-    * \param layout  memory layout of the field (see Layout)
+    * \param l       memory layout of the field (see Layout)
     * \param alloc  class that describes how to allocate memory for the field, see FieldAllocator
     *******************************************************************************************************************/
    template<typename T, uint_t fSize_>
@@ -92,12 +92,12 @@ namespace field {
    //*******************************************************************************************************************
    /*!\brief Creates a field and initializes f coordinate with vector values
     *
-    * \param xSize   size of x dimension
-    * \param ySize   size of y dimension
-    * \param zSize   size of z dimension
+    * \param _xSize  size of x dimension
+    * \param _ySize  size of y dimension
+    * \param _zSize  size of z dimension
     * \param gl      number of ghost layers
     * \param fValues initializes f coordinate with values from vector (see set(std::vector&) ) also ghost layers
-    * \param layout  memory layout of the field (see Layout)
+    * \param l       memory layout of the field (see Layout)
     * \param alloc   class that describes how to allocate memory for the field, see FieldAllocator
     *******************************************************************************************************************/
    template<typename T, uint_t fSize_>
@@ -116,11 +116,11 @@ namespace field {
     *
     * Is automatically called by constructors that take at least one argument
     *
-    * \param xSize  size of x dimension without ghost layers
-    * \param ySize  size of y dimension without ghost layers
-    * \param zSize  size of z dimension without ghost layers
+    * \param _xSize size of x dimension without ghost layers
+    * \param _ySize size of y dimension without ghost layers
+    * \param _zSize size of z dimension without ghost layers
     * \param gl     number of ghost layers
-    * \param layout memory layout of the field (see Layout)
+    * \param l      memory layout of the field (see Layout)
     * \param alloc  class that describes how to allocate memory for the field, see FieldAllocator
     *******************************************************************************************************************/
     template<typename T, uint_t fSize_>

src/field/GhostRegions.h

@@ -31,6 +31,7 @@ namespace field {
 //*******************************************************************************************************************
 /*!\brief Constructs CellInterval containing the ghost region in the specified direction
  *
+ * \param f   field
  * \param d   direction of the ghost layer  For W,E,N,S,T,B   a slice is returned
  *                                          for NW, NE, ..    an edge is returned
  *                                          for TBE, TNW, ... a corner ( single cell ) is returned
@@ -72,6 +73,7 @@ CellInterval getGhostRegion( const GhostLayerField_T & f, stencil::Direction d,
 /*!\brief Constructs CellInterval containing the last slice before the ghost layer begins
  *        for a given direction.
  *
+ * \param f   field
  * \param d   direction of the border .     For W,E,N,S,T,B   a slice is returned
  *                                          for NW, NE, ..    an edge is returned
  *                                          for TBE, TNW, ... a corner ( single cell ) is returned