Merge pull request #668 from streeve/doxygen_updates

Doxygen updates for file and return types

cajita/src/Cajita_Array.hpp

@@ -179,6 +179,7 @@ struct is_array_layout<const ArrayLayout<EntityType, MeshType>>
   \brief Create an array layout over the entities of a local grid.
   \param local_grid The local grid over which to create the layout.
   \param dofs_per_entity The number of degrees-of-freedom per grid entity.
+  \return Shared pointer to an ArrayLayout.
   \note EntityType The entity: Cell, Node, Face, or Edge
 */
 template <class EntityType, class MeshType>
@@ -199,6 +200,7 @@ createArrayLayout( const std::shared_ptr<LocalGrid<MeshType>>& local_grid,
   \param halo_cell_width The number of halo cells surrounding the locally owned
   cells.
   \param dofs_per_entity The number of degrees-of-freedom per grid entity.
+  \return Shared pointer to an ArrayLayout.
   \note EntityType The entity: Cell, Node, Face, or Edge
 */
 template <class EntityType, class MeshType>
@@ -340,6 +342,7 @@ struct is_array<const Array<Scalar, EntityType, MeshType, Params...>>
   over the ghosted index space of the layout.
   \param label A label for the view.
   \param layout The array layout over which to construct the view.
+  \return Shared pointer to an Array.
 */
 template <class Scalar, class... Params, class EntityType, class MeshType>
 std::shared_ptr<Array<Scalar, EntityType, MeshType, Params...>>
@@ -359,6 +362,7 @@ createArray( const std::string& label,
   \param array The array from which to create a subarray
   \param dof_min The minimum degree-of-freedom index of the subarray.
   \param dof_max The maximum degree-of-freedom index of the subarray.
+  \return Shared pointer to a new Array.
 */
 template <class Scalar, class EntityType, class MeshType, class... Params>
 std::shared_ptr<Array<

cajita/src/Cajita_GlobalGrid.hpp

@@ -190,6 +190,7 @@ class GlobalGrid
   \param global_mesh The global mesh data.
   \param periodic Whether each logical dimension is periodic.
   \param partitioner The grid partitioner.
+  \return Shared pointer to a GlobalGrid.
 */
 template <class MeshType>
 std::shared_ptr<GlobalGrid<MeshType>>
@@ -208,6 +209,7 @@ createGlobalGrid( MPI_Comm comm,
   \param global_mesh The global mesh data.
   \param periodic Whether each logical dimension is periodic.
   \param partitioner The grid partitioner.
+  \return Shared pointer to a GlobalGrid.
 */
 template <class Scalar, std::size_t NumSpaceDim>
 std::shared_ptr<GlobalGrid<SparseMesh<Scalar, NumSpaceDim>>> createGlobalGrid(

cajita/src/Cajita_GlobalMesh.hpp

@@ -181,6 +181,7 @@ class GlobalMesh
 
   \param global_low_corner, global_high_corner Location of the mesh corner.
   \param cell_size Uniform cell size for every dimension.
+  \return Shared pointer to a GlobalMesh.
 */
 template <class Scalar, std::size_t NumSpaceDim>
 std::shared_ptr<GlobalMesh<UniformMesh<Scalar, NumSpaceDim>>>
@@ -201,6 +202,7 @@ createUniformGlobalMesh(
 
   \param global_low_corner, global_high_corner Location of the mesh corner.
   \param cell_size %Array ofuniform cell size per dimension.
+  \return Shared pointer to a GlobalMesh.
 */
 template <class Scalar, std::size_t NumSpaceDim>
 std::shared_ptr<GlobalMesh<UniformMesh<Scalar, NumSpaceDim>>>
@@ -221,6 +223,7 @@ createUniformGlobalMesh(
 
   \param global_low_corner, global_high_corner Location of the mesh corner.
   \param global_num_cell %Array ofnumber of cells per dimension.
+  \return Shared pointer to a GlobalMesh.
 */
 template <class Scalar, std::size_t NumSpaceDim>
 std::shared_ptr<GlobalMesh<UniformMesh<Scalar, NumSpaceDim>>>
@@ -242,6 +245,7 @@ createUniformGlobalMesh(
 
   \param global_low_corner, global_high_corner Location of the mesh corner.
   \param cell_size Uniform cell size for every dimension.
+  \return Shared pointer to a GlobalMesh.
 */
 template <class Scalar, std::size_t NumSpaceDim>
 std::shared_ptr<GlobalMesh<SparseMesh<Scalar, NumSpaceDim>>>
@@ -262,6 +266,7 @@ createSparseGlobalMesh(
 
   \param global_low_corner, global_high_corner Location of the mesh corner.
   \param cell_size %Array ofuniform cell size per dimension.
+  \return Shared pointer to a GlobalMesh.
 */
 template <class Scalar, std::size_t NumSpaceDim>
 std::shared_ptr<GlobalMesh<SparseMesh<Scalar, NumSpaceDim>>>
@@ -282,6 +287,7 @@ createSparseGlobalMesh(
 
   \param global_low_corner, global_high_corner Location of the mesh corner.
   \param global_num_cell %Array ofnumber of cells per dimension.
+  \return Shared pointer to a GlobalMesh.
 */
 template <class Scalar, std::size_t NumSpaceDim>
 std::shared_ptr<GlobalMesh<SparseMesh<Scalar, NumSpaceDim>>>
@@ -373,6 +379,7 @@ class GlobalMesh<NonUniformMesh<Scalar, 3>>
   \brief Create a non-uniform 3D mesh.
   \param i_edges, j_edges, k_edges List of edges defining the mesh in each
   dimension.
+  \return Shared pointer to a GlobalMesh.
 */
 template <class Scalar>
 std::shared_ptr<GlobalMesh<NonUniformMesh<Scalar, 3>>>
@@ -462,6 +469,7 @@ class GlobalMesh<NonUniformMesh<Scalar, 2>>
   \brief Create a non-uniform 2D mesh.
   \tparam Scalar Mesh scalar type.
   \param i_edges, j_edges List of edges defining the mesh in each dimension.
+  \return Shared pointer to a GlobalMesh.
 */
 template <class Scalar>
 std::shared_ptr<GlobalMesh<NonUniformMesh<Scalar, 2>>>

cajita/src/Cajita_Halo.hpp

@@ -947,6 +947,7 @@ struct ArrayPackMemorySpace
   \param pattern The pattern to build the halo from.
   \param width Must be less than or equal to the width of the array halo.
   \param arrays The arrays over which to build the halo.
+  \return Shared pointer to a Halo.
 */
 template <class Pattern, class... ArrayTypes>
 auto createHalo( const Pattern& pattern, const int width,

cajita/src/Cajita_HypreStructuredSolver.hpp

@@ -1364,6 +1364,7 @@ class HypreStructDiagonal
 // Builders
 //---------------------------------------------------------------------------//
 //! Create a HYPRE PCG structured solver.
+//! \return Shared pointer to HypreStructPCG.
 template <class Scalar, class MemorySpace, class ArrayLayout_t>
 std::shared_ptr<
     HypreStructPCG<Scalar, typename ArrayLayout_t::entity_type, MemorySpace>>
@@ -1378,6 +1379,7 @@ createHypreStructPCG( const ArrayLayout_t& layout,
 }
 
 //! Create a HYPRE GMRES structured solver.
+//! \return Shared pointer to HypreStructGMRES.
 template <class Scalar, class MemorySpace, class ArrayLayout_t>
 std::shared_ptr<
     HypreStructGMRES<Scalar, typename ArrayLayout_t::entity_type, MemorySpace>>
@@ -1392,6 +1394,7 @@ createHypreStructGMRES( const ArrayLayout_t& layout,
 }
 
 //! Create a HYPRE BiCGSTAB structured solver.
+//! \return Shared pointer to HypreStructBiCGSTAB.
 template <class Scalar, class MemorySpace, class ArrayLayout_t>
 std::shared_ptr<HypreStructBiCGSTAB<Scalar, typename ArrayLayout_t::entity_type,
                                     MemorySpace>>
@@ -1406,6 +1409,7 @@ createHypreStructBiCGSTAB( const ArrayLayout_t& layout,
 }
 
 //! Create a HYPRE PFMG structured solver.
+//! \return Shared pointer to HypreStructPFMG.
 template <class Scalar, class MemorySpace, class ArrayLayout_t>
 std::shared_ptr<
     HypreStructPFMG<Scalar, typename ArrayLayout_t::entity_type, MemorySpace>>
@@ -1420,6 +1424,7 @@ createHypreStructPFMG( const ArrayLayout_t& layout,
 }
 
 //! Create a HYPRE SMG structured solver.
+//! \return Shared pointer to HypreStructSMG.
 template <class Scalar, class MemorySpace, class ArrayLayout_t>
 std::shared_ptr<
     HypreStructSMG<Scalar, typename ArrayLayout_t::entity_type, MemorySpace>>
@@ -1434,6 +1439,7 @@ createHypreStructSMG( const ArrayLayout_t& layout,
 }
 
 //! Create a HYPRE Jacobi structured solver.
+//! \return Shared pointer to HypreStructJacobi.
 template <class Scalar, class MemorySpace, class ArrayLayout_t>
 std::shared_ptr<
     HypreStructJacobi<Scalar, typename ArrayLayout_t::entity_type, MemorySpace>>
@@ -1448,6 +1454,7 @@ createHypreStructJacobi( const ArrayLayout_t& layout,
 }
 
 //! Create a HYPRE Diagonal structured solver.
+//! \return Shared pointer to HypreStructDiagonal.
 template <class Scalar, class MemorySpace, class ArrayLayout_t>
 std::shared_ptr<HypreStructDiagonal<Scalar, typename ArrayLayout_t::entity_type,
                                     MemorySpace>>
@@ -1470,6 +1477,7 @@ createHypreStructDiagonal( const ArrayLayout_t& layout,
   \param solver_type Solver name.
   \param layout The ArrayLayout defining the vector space of the solver.
   \param is_preconditioner Use as a preconditioner.
+  \return Shared pointer to a HypreStructuredSolver.
 */
 template <class Scalar, class MemorySpace, class ArrayLayout_t>
 std::shared_ptr<HypreStructuredSolver<

cajita/src/Cajita_IndexConversion.hpp

@@ -162,6 +162,7 @@ struct L2G
 
 //---------------------------------------------------------------------------//
 //! Creation function for local-to-global indexer.
+//! \return L2G
 template <class MeshType, class EntityType>
 L2G<MeshType, EntityType> createL2G( const LocalGrid<MeshType>& local_grid,
                                      EntityType )

cajita/src/Cajita_IndexSpace.hpp

@@ -163,7 +163,7 @@ class IndexSpace
 //---------------------------------------------------------------------------//
 /*!
   \brief Create a multi-dimensional execution policy over an index space.
-
+  \return Kokkos::RangePolicy
   Rank-1 specialization.
 */
 template <class ExecutionSpace>
@@ -177,6 +177,7 @@ createExecutionPolicy( const IndexSpace<1>& index_space, const ExecutionSpace& )
 //---------------------------------------------------------------------------//
 /*!
   \brief Create a multi-dimensional execution policy over an index space.
+  \return Kokkos::RangePolicy
 
   Rank-1 specialization with a work tag.
 */
@@ -192,6 +193,7 @@ createExecutionPolicy( const IndexSpace<1>& index_space, const ExecutionSpace&,
 //---------------------------------------------------------------------------//
 /*!
   \brief Create a multi-dimensional execution policy over an index space.
+  \return Kokkos::MDRangePolicy
 */
 template <class IndexSpace_t, class ExecutionSpace>
 Kokkos::MDRangePolicy<ExecutionSpace, Kokkos::Rank<IndexSpace_t::Rank>>
@@ -206,6 +208,7 @@ createExecutionPolicy( const IndexSpace_t& index_space, const ExecutionSpace& )
 /*!
   \brief Create a multi-dimensional execution policy over an index space with
   a work tag.
+  \return Kokkos::MDRangePolicy
 */
 template <class IndexSpace_t, class ExecutionSpace, class WorkTag>
 Kokkos::MDRangePolicy<ExecutionSpace, WorkTag, Kokkos::Rank<IndexSpace_t::Rank>>
@@ -219,8 +222,8 @@ createExecutionPolicy( const IndexSpace_t& index_space, const ExecutionSpace&,
 
 //---------------------------------------------------------------------------//
 /*!
-  \brief Given an index space create a view over the extent of that index
-  space.
+  \brief Given an index space create a view over the extent of that index space.
+  \return Uninitialized Kokkos::View
 
   Rank-1 specialization.
 */
@@ -237,6 +240,7 @@ Kokkos::View<Scalar*, Params...> createView( const std::string& label,
 /*!
   \brief Given an index space and a data pointer create an unmanaged view over
   the extent of that index space.
+  \return Unmanaged Kokkos::View
 
   Rank-1 specialization.
 */
@@ -252,6 +256,7 @@ createView( const IndexSpace<1>& index_space, Scalar* data )
 /*!
   \brief Given an index space create a view over the extent of that index
   space.
+  \return Uninitialized Kokkos::View
 
   Rank-2 specialization.
 */
@@ -268,6 +273,7 @@ Kokkos::View<Scalar**, Params...> createView( const std::string& label,
 /*!
   \brief Given an index space and a data pointer create an unmanaged view over
   the extent of that index space.
+  \return Unmanaged Kokkos::View
 
   Rank-2 specialization.
 */
@@ -283,6 +289,7 @@ createView( const IndexSpace<2>& index_space, Scalar* data )
 /*!
   \brief Given an index space create a view over the extent of that index
   space.
+  \return Uninitialized Kokkos::View
 
   Rank-3 specialization.
 */
@@ -300,6 +307,7 @@ createView( const std::string& label, const IndexSpace<3>& index_space )
 /*!
   \brief Given an index space and a data pointer create an unmanaged view over
   the extent of that index space.
+  \return Unmanaged Kokkos::View
 
   Rank-3 specialization.
 */
@@ -314,8 +322,8 @@ createView( const IndexSpace<3>& index_space, Scalar* data )
 
 //---------------------------------------------------------------------------//
 /*!
-  \brief Given an index space create a view over the extent of that index
-  space.
+  \brief Given an index space create a view over the extent of that index space.
+  \return Uninitialized Kokkos::View
 
   Rank-4 specialization.
 */
@@ -333,6 +341,7 @@ createView( const std::string& label, const IndexSpace<4>& index_space )
 /*!
   \brief Given an index space and a data pointer create an unmanaged view over
   the extent of that index space.
+  \return Unmanaged Kokkos::View
 
   Rank-4 specialization.
 */
@@ -348,6 +357,7 @@ createView( const IndexSpace<4>& index_space, Scalar* data )
 //---------------------------------------------------------------------------//
 /*!
   \brief Given a view create a subview over the given index space.
+  \return subview of the original Kokkos::View
 
   Rank-1 specialization.
 */
@@ -363,6 +373,7 @@ KOKKOS_INLINE_FUNCTION auto createSubview( const ViewType& view,
 //---------------------------------------------------------------------------//
 /*!
   \brief Given a view create a subview over the given index space.
+  \return subview of the original Kokkos::View
 
   Rank-2 specialization.
 */
@@ -380,6 +391,7 @@ KOKKOS_INLINE_FUNCTION auto createSubview( const ViewType& view,
 //---------------------------------------------------------------------------//
 /*!
   \brief Given a view create a subview over the given index space.
+  \return subview of the original Kokkos::View
 
   Rank-3 specialization.
 */
@@ -398,6 +410,7 @@ KOKKOS_INLINE_FUNCTION auto createSubview( const ViewType& view,
 //---------------------------------------------------------------------------//
 /*!
   \brief Given a view create a subview over the given index space.
+  \return subview of the original Kokkos::View
 
   Rank-4 specialization.
 */
@@ -417,8 +430,9 @@ KOKKOS_INLINE_FUNCTION auto createSubview( const ViewType& view,
 
 //---------------------------------------------------------------------------//
 /*!
-  Given an N-dimensional index space append an additional dimension with the
-  given size.
+  \brief Given an N-dimensional index space append an additional dimension with
+  the given size.
+  \return IndexSpace with dimension N+1.
 */
 template <long N>
 IndexSpace<N + 1> appendDimension( const IndexSpace<N>& index_space,
@@ -439,8 +453,9 @@ IndexSpace<N + 1> appendDimension( const IndexSpace<N>& index_space,
 
 //---------------------------------------------------------------------------//
 /*!
-  Given an N-dimensional index space append an additional dimension with the
-  given range.
+  \brief Given an N-dimensional index space append an additional dimension with
+  the given range.
+  \return IndexSpace with dimension N+1.
 */
 template <long N>
 IndexSpace<N + 1> appendDimension( const IndexSpace<N>& index_space,