Fix doxygen documentation for release (#895)

All the files with public API are now parsed correctly.

doc/Doxyfile.in

@@ -814,7 +814,6 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 INPUT                  =  ${DLAF_SOURCE_DIR}/doc/mainpage.dox
 INPUT                  += ${DLAF_SOURCE_DIR}/include
-INPUT                  += ${DLAF_SOURCE_DIR}/src
 
 # 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
@@ -2149,6 +2148,7 @@ PREDEFINED             =  DLAF_DOXYGEN
 PREDEFINED             += DLAF_ASSERT_ENABLE
 PREDEFINED             += DLAF_ASSERT_MODERATE_ENABLE
 PREDEFINED             += DLAF_ASSERT_HEAVY_ENABLE
+PREDEFINED             += DLAF_WITH_GPU
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

include/dlaf/auxiliary.h

@@ -9,4 +9,7 @@
 //
 #pragma once
 
+/// @file
+/// Includes all auxiliary algorithms such as norms.
+
 #include "dlaf/auxiliary/norm.h"

include/dlaf/auxiliary/norm.h

@@ -9,6 +9,8 @@
 //
 #pragma once
 
+/// @file
+
 #include "dlaf/auxiliary/norm/api.h"
 #include "dlaf/blas/enum_output.h"
 #include "dlaf/common/assert.h"

include/dlaf/auxiliary/norm/api.h

@@ -27,7 +27,7 @@ struct Norm<Backend::MC, Device::CPU, T> {
                                  Matrix<const T, Device::CPU>& matrix);
 };
 
-/// ---- ETI
+// ETI
 #define DLAF_NORM_ETI(KWORD, DATATYPE) KWORD template struct Norm<Backend::MC, Device::CPU, DATATYPE>;
 
 DLAF_NORM_ETI(extern, float)

include/dlaf/blas/enum_output.h

@@ -10,6 +10,8 @@
 
 #pragma once
 
+/// @file
+
 #include <ostream>
 
 #include <blas.hh>

include/dlaf/blas/scal.h

@@ -13,13 +13,12 @@
 #include <complex>
 
 /// @file
-
-namespace blas {
-
-/// Provides overloads for mixed real complex variants missing in blaspp.
+/// Provides overloads for mixed real complex variants of scal missing in blaspp.
 /// - csscal
 /// - zdscal
 
+namespace blas {
+
 void scal(std::int64_t n, float a, std::complex<float>* x, std::int64_t incx) noexcept;
 void scal(std::int64_t n, double a, std::complex<double>* x, std::int64_t incx) noexcept;
 

include/dlaf/blas/tile.h

@@ -9,6 +9,9 @@
 //
 #pragma once
 
+/// @file
+/// Provides `Tile` wrappers for BLAS operations.
+
 #include <cstddef>
 
 #include <blas.hh>
@@ -169,16 +172,12 @@ template <Backend B, class T, Device D>
 void gemm(const blas::Op op_a, const blas::Op op_b, const T alpha, const Tile<const T, D>& a,
           const Tile<const T, D>& b, const T beta, const Tile<T, D>& c);
 
-/// \overload gemm
-///
 /// This overload takes a policy argument and a sender which must send all required arguments for the
 /// algorithm. Returns a sender which signals a connected receiver when the algorithm is done.
 template <Backend B, typename Sender,
           typename = std::enable_if_t<pika::execution::experimental::is_sender_v<Sender>>>
 auto gemm(const dlaf::internal::Policy<B>& p, Sender&& s);
 
-/// \overload gemm
-///
 /// This overload partially applies the algorithm with a policy for later use with operator| with a
 /// sender on the left-hand side.
 template <Backend B>
@@ -191,16 +190,12 @@ template <Backend B, class T, Device D>
 void hemm(const blas::Side side, const blas::Uplo uplo, const T alpha, const Tile<const T, D>& a,
           const Tile<const T, D>& b, const T beta, const Tile<T, D>& c);
 
-/// \overload hemm
-///
 /// This overload takes a policy argument and a sender which must send all required arguments for the
 /// algorithm. Returns a sender which signals a connected receiver when the algorithm is done.
 template <Backend B, typename Sender,
           typename = std::enable_if_t<pika::execution::experimental::is_sender_v<Sender>>>
 auto hemm(const dlaf::internal::Policy<B>& p, Sender&& s);
 
-/// \overload hemm
-///
 /// This overload partially applies the algorithm with a policy for later use with operator| with a
 /// sender on the left-hand side.
 template <Backend B>
@@ -213,16 +208,12 @@ template <Backend B, class T, Device D>
 void her2k(const blas::Uplo uplo, const blas::Op op, const T alpha, const Tile<const T, D>& a,
            const Tile<const T, D>& b, const BaseType<T> beta, const Tile<T, D>& c);
 
-/// \overload her2k
-///
 /// This overload takes a policy argument and a sender which must send all required arguments for the
 /// algorithm. Returns a sender which signals a connected receiver when the algorithm is done.
 template <Backend B, typename Sender,
           typename = std::enable_if_t<pika::execution::experimental::is_sender_v<Sender>>>
 auto her2k(const dlaf::internal::Policy<B>& p, Sender&& s);
 
-/// \overload her2k
-///
 /// This overload partially applies the algorithm with a policy for later use with operator| with a
 /// sender on the left-hand side.
 template <Backend B>
@@ -235,16 +226,12 @@ template <Backend B, class T, Device D>
 void herk(const blas::Uplo uplo, const blas::Op op, const BaseType<T> alpha, const Tile<const T, D>& a,
           const BaseType<T> beta, const Tile<T, D>& c);
 
-/// \overload herk
-///
 /// This overload takes a policy argument and a sender which must send all required arguments for the
 /// algorithm. Returns a sender which signals a connected receiver when the algorithm is done.
 template <Backend B, typename Sender,
           typename = std::enable_if_t<pika::execution::experimental::is_sender_v<Sender>>>
 auto herk(const dlaf::internal::Policy<B>& p, Sender&& s);
 
-/// \overload herk
-///
 /// This overload partially applies the algorithm with a policy for later use with operator| with a
 /// sender on the left-hand side.
 template <Backend B>
@@ -258,16 +245,12 @@ void trmm(const dlaf::internal::Policy<B>& policy, const blas::Side side, const
           const blas::Op op, const blas::Diag diag, const T alpha, const Tile<const T, D>& a,
           const Tile<T, D>& b);
 
-/// \overload trmm
-///
 /// This overload takes a policy argument and a sender which must send all required arguments for the
 /// algorithm. Returns a sender which signals a connected receiver when the algorithm is done.
 template <Backend B, typename Sender,
           typename = std::enable_if_t<pika::execution::experimental::is_sender_v<Sender>>>
 auto trmm(const dlaf::internal::Policy<B>& p, Sender&& s);
 
-/// \overload trmm
-///
 /// This overload partially applies the algorithm with a policy for later use with operator| with a
 /// sender on the left-hand side.
 template <Backend B>
@@ -282,16 +265,12 @@ void trmm3(const dlaf::internal::Policy<B>& policy, const blas::Side side, const
            const blas::Op op, const blas::Diag diag, const T alpha, const Tile<const T, D>& a,
            const Tile<const T, D>& b, const Tile<T, D>& c);
 
-/// \overload trmm3
-///
 /// This overload takes a policy argument and a sender which must send all required arguments for the
 /// algorithm. Returns a sender which signals a connected receiver when the algorithm is done.
 template <Backend B, typename Sender,
           typename = std::enable_if_t<pika::execution::experimental::is_sender_v<Sender>>>
 auto trmm3(const dlaf::internal::Policy<B>& p, Sender&& s);
 
-/// \overload trmm3
-///
 /// This overload partially applies the algorithm with a policy for later use with operator| with a
 /// sender on the left-hand side.
 template <Backend B>
@@ -305,16 +284,12 @@ void trsm(const dlaf::internal::Policy<B>& policy, const blas::Side side, const
           const blas::Op op, const blas::Diag diag, const T alpha, const Tile<const T, D>& a,
           const Tile<T, D>& b);
 
-/// \overload trsm
-///
 /// This overload takes a policy argument and a sender which must send all required arguments for the
 /// algorithm. Returns a sender which signals a connected receiver when the algorithm is done.
 template <Backend B, typename Sender,
           typename = std::enable_if_t<pika::execution::experimental::is_sender_v<Sender>>>
 auto trsm(const dlaf::internal::Policy<B>& p, Sender&& s);
 
-/// \overload trsm
-///
 /// This overload partially applies the algorithm with a policy for later use with operator| with a
 /// sender on the left-hand side.
 template <Backend B>

include/dlaf/blas/tile_extensions.h

@@ -9,6 +9,9 @@
 //
 #pragma once
 
+/// @file
+/// Provides `Tile` wrappers for extra basic linear algebra operations not covered by BLAS.
+
 #include <blas.hh>
 
 #include "dlaf/blas/tile.h"
@@ -39,16 +42,12 @@ using matrix::Tile;
 template <Backend B, class T, Device D>
 void add(T alpha, const matrix::Tile<const T, D>& tile_b, const matrix::Tile<T, D>& tile_a);
 
-/// \overload add
-///
 /// This overload takes a policy argument and a sender which must send all required arguments for the
 /// algorithm. Returns a sender which signals a connected receiver when the algorithm is done.
 template <Backend B, typename Sender,
           typename = std::enable_if_t<pika::execution::experimental::is_sender_v<Sender>>>
 auto add(const dlaf::internal::Policy<B>& p, Sender&& s);
 
-/// \overload add
-///
 /// This overload partially applies the algorithm with a policy for later use with operator| with a
 /// sender on the left-hand side.
 template <Backend B>

include/dlaf/common/assert.h

@@ -10,8 +10,6 @@
 
 #pragma once
 
-/// @file
-
 #include <exception>
 #include <iostream>
 #include <memory>
@@ -130,7 +128,7 @@ void silenceUnusedWarningFor(Args&&...) {}
 
 #define DLAF_STATIC_FAIL(DummyType, Msg) static_assert(sizeof(DummyType) == 0, Msg)
 
-/// Returns a fake object of type T (specified by __VA_ARGS__) dereferencing a null pointer.
+/// Returns a fake object of type T (specified by @p __VA_ARGS__ ) dereferencing a null pointer.
 ///
 /// At runtime the program is exited with an error before dereferencing the null pointer.
 /// This macro is useful when a return statement is needed in unreachable branches,

include/dlaf/common/callable_object.h

@@ -10,6 +10,8 @@
 
 #pragma once
 
+/// @file
+
 /// Given a function name @fname generates a constexpr object with name fname_o
 /// with type fname_t. The generated type has one static operator() which
 /// transparently forwards all arguments to a call to fname. This macro is

include/dlaf/common/data.h

@@ -23,7 +23,15 @@
 namespace dlaf {
 namespace common {
 
+#ifdef DLAF_DOXYGEN
+
 /// Traits for verifying if the given type is an implementation of the Data concept.
+///
+/// Derive from @p std::true_type or @p std::false_type.
+template <class Data>
+struct is_data {};
+
+#else
 template <class Data, class = void>
 struct is_data : std::false_type {};
 
@@ -37,6 +45,7 @@ struct is_data<
                      std::is_same_v<decltype(data_count(std::declval<const Data&>())), SizeType> &&
                      std::is_same_v<decltype(data_iscontiguous(std::declval<const Data&>())), bool>>>
     : std::true_type {};
+#endif
 
 template <class T>
 inline constexpr bool is_data_v = is_data<T>::value;

include/dlaf/common/data_descriptor.h

@@ -138,7 +138,7 @@ struct DataDescriptor {
   SizeType stride_;
 };
 
-/// Helper class for creatig a DataDescriptor from a bounded C-array.
+/// Helper class for creating a DataDescriptor from a bounded C-array.
 template <class T, std::size_t N>
 struct DataDescriptor<T[N]> : DataDescriptor<T> {
   /// Create a Data from a given bounded C-array.

include/dlaf/common/index2d.h

@@ -26,7 +26,7 @@ namespace dlaf {
 
 enum class Coord { Row, Col };
 
-// Given a Coord, returns its orthogonal
+/// Given a Coord, returns its orthogonal
 constexpr Coord orthogonal(const Coord rc) {
   return rc == Coord::Row ? Coord::Col : Coord::Row;
 }

include/dlaf/common/pipeline.h

@@ -10,6 +10,8 @@
 
 #pragma once
 
+/// @file
+
 #include <pika/async_rw_mutex.hpp>
 #include <pika/execution.hpp>
 #include <dlaf/common/assert.h>

include/dlaf/common/round_robin.h

@@ -9,6 +9,8 @@
 //
 #pragma once
 
+/// @file
+
 #include <vector>
 
 namespace dlaf {

include/dlaf/common/single_threaded_blas.h

@@ -10,6 +10,8 @@
 
 #pragma once
 
+/// @file
+
 #ifdef DLAF_ASSERT_MODERATE_ENABLE
 #include <thread>
 #endif

include/dlaf/common/timer.h

@@ -10,6 +10,8 @@
 
 #pragma once
 
+/// @file
+
 #include <chrono>
 
 namespace dlaf {

include/dlaf/common/unwrap.h

@@ -9,6 +9,8 @@
 //
 #pragma once
 
+/// @file
+
 #include <pika/async_rw_mutex.hpp>
 #include <pika/execution.hpp>
 

include/dlaf/common/vector.h

@@ -10,6 +10,8 @@
 
 #pragma once
 
+/// @file
+
 #include <vector>
 #include "dlaf/types.h"
 

include/dlaf/communication/communicator.h

@@ -10,6 +10,8 @@
 
 #pragma once
 
+/// @file
+
 #include <memory>
 #include "dlaf/communication/error.h"
 

include/dlaf/communication/datatypes.h

@@ -10,6 +10,8 @@
 
 #pragma once
 
+/// @file
+
 #include "dlaf/communication/error.h"
 
 #include <complex>

include/dlaf/communication/functions_sync.h

@@ -10,6 +10,8 @@
 
 #pragma once
 
+/// @file
+
 #include "dlaf/communication/sync/all_reduce.h"
 #include "dlaf/communication/sync/basic.h"
 #include "dlaf/communication/sync/broadcast.h"

include/dlaf/communication/init.h

@@ -9,6 +9,8 @@
 //
 #pragma once
 
+/// @file
+
 #include <iostream>
 #include <mutex>
 

include/dlaf/communication/kernels.h

@@ -10,6 +10,8 @@
 
 #pragma once
 
+/// @file
+
 #include "dlaf/communication/kernels/all_reduce.h"
 #include "dlaf/communication/kernels/broadcast.h"
 #include "dlaf/communication/kernels/p2p.h"