Commit 190134e7 authored by David Frank's avatar David Frank
Browse files

#64 Replace all occurrence of \doxygentag with @doxygentag

Clang-format can't really handle the doxygen tags with a blackshlash.
Therefore, replace them with the @-prefix.

Add CI job, to check for consistency, but allow it to fail, to prevent
false positives. Let's observe it for a bit, and then we can change it
later.
parent 3a7b73e7
Pipeline #472688 passed with stages
in 46 minutes and 48 seconds
......@@ -25,8 +25,8 @@ variables:
# Caches should only be used for caching
# between pipelines not jobs, artifacts should be prefered for that
# We store the CPM cache, for a given branch.
# TODO dfrank: Is it possible to cache it project wide?
# We store the CPM cache, for a given branch.
# TODO dfrank: Is it possible to cache it project wide?
cache:
key: "$CI_COMMIT_REF_SLUG"
paths:
......@@ -150,6 +150,17 @@ clang-tidy:
- elsa
- clang
comment-formating:
<<: *run_always
stage: static-test
image: $CLANG_FORMAT_IMAGE
script:
./tools/ci_scripts/check-comment-style.sh
allow_failure: true
tags:
- linux
- elsa
- clang
### compile jobs ###
......
/**
* \file test_BenchmarkDataContainerConstruction.cpp
* @file test_BenchmarkDataContainerConstruction.cpp
*
* \brief Benchmarks for constructing an empty DataContainer
* @brief Benchmarks for constructing an empty DataContainer
*
* \author Jens Petit
* @author Jens Petit
*/
#define CATCH_CONFIG_ENABLE_BENCHMARKING
......
/**
* \file test_BenchmarkExpressionTemplates.cpp
* @file test_BenchmarkExpressionTemplates.cpp
*
* \brief Benchmarks for expression templates
* @brief Benchmarks for expression templates
*
* \author Jens Petit
* @author Jens Petit
*/
#define CATCH_CONFIG_ENABLE_BENCHMARKING
......
/**
* \file test_RayGenerationBench.cpp
* @file test_RayGenerationBench.cpp
*
* \brief Benchmarks for projectors
* @brief Benchmarks for projectors
*
* \author David Frank
* @author David Frank
*/
#define CATCH_CONFIG_ENABLE_BENCHMARKING
......
/**
* \file test_RayGenerationBench.cpp
* @file test_RayGenerationBench.cpp
*
* \brief Benchmarks for projectors
* @brief Benchmarks for projectors
*
* \author David Frank
* @author David Frank
*/
#define CATCH_CONFIG_ENABLE_BENCHMARKING
......
/**
* \file test_RayGenerationBench.cpp
* @file test_RayGenerationBench.cpp
*
* \brief Benchmarks for ray generation
* @brief Benchmarks for ray generation
*
* \author David Frank
* @author David Frank
*/
#define CATCH_CONFIG_ENABLE_BENCHMARKING
......
......@@ -5,10 +5,10 @@
namespace elsa
{
/**
* \brief Class implementing polymorphic clones with smart pointers and CRTP, as well as
* @brief Class implementing polymorphic clones with smart pointers and CRTP, as well as
* comparison operators.
*
* \author Tobias Lasser
* @author Tobias Lasser
*
* This class provides a clone method using CRTP to support covariance with smart pointers.
* For details see
......
......@@ -21,15 +21,15 @@ namespace elsa
{
/**
* \brief class representing and storing a linearized n-dimensional signal
* @brief class representing and storing a linearized n-dimensional signal
*
* \author Matthias Wieczorek - initial code
* \author Tobias Lasser - rewrite, modularization, modernization
* \author David Frank - added DataHandler concept, iterators
* \author Nikola Dinev - add block support
* \author Jens Petit - expression templates
* @author Matthias Wieczorek - initial code
* @author Tobias Lasser - rewrite, modularization, modernization
* @author David Frank - added DataHandler concept, iterators
* @author Nikola Dinev - add block support
* @author Jens Petit - expression templates
*
* \tparam data_t - data type that is stored in the DataContainer, defaulting to real_t.
* @tparam data_t - data type that is stored in the DataContainer, defaulting to real_t.
*
* This class provides a container for a signal that is stored in memory. This signal can
* be n-dimensional, and will be stored in memory in a linearized fashion. The information
......@@ -43,36 +43,36 @@ namespace elsa
DataContainer() = delete;
/**
* \brief Constructor for empty DataContainer, no initialisation is performed
* @brief Constructor for empty DataContainer, no initialisation is performed
*
* \param[in] dataDescriptor containing the associated metadata
* \param[in] handlerType the data handler (default: CPU)
* @param[in] dataDescriptor containing the associated metadata
* @param[in] handlerType the data handler (default: CPU)
*/
explicit DataContainer(const DataDescriptor& dataDescriptor,
DataHandlerType handlerType = defaultHandlerType);
/**
* \brief Constructor for DataContainer, initializing it with a DataVector
* @brief Constructor for DataContainer, initializing it with a DataVector
*
* \param[in] dataDescriptor containing the associated metadata
* \param[in] data vector containing the initialization data
* \param[in] handlerType the data handler (default: CPU)
* @param[in] dataDescriptor containing the associated metadata
* @param[in] data vector containing the initialization data
* @param[in] handlerType the data handler (default: CPU)
*/
DataContainer(const DataDescriptor& dataDescriptor,
const Eigen::Matrix<data_t, Eigen::Dynamic, 1>& data,
DataHandlerType handlerType = defaultHandlerType);
/**
* \brief Copy constructor for DataContainer
* @brief Copy constructor for DataContainer
*
* \param[in] other DataContainer to copy
* @param[in] other DataContainer to copy
*/
DataContainer(const DataContainer<data_t>& other);
/**
* \brief copy assignment for DataContainer
* @brief copy assignment for DataContainer
*
* \param[in] other DataContainer to copy
* @param[in] other DataContainer to copy
*
* Note that a copy assignment with a DataContainer on a different device (CPU vs GPU) will
* result in an "infectious" copy which means that afterwards the current container will use
......@@ -81,9 +81,9 @@ namespace elsa
DataContainer<data_t>& operator=(const DataContainer<data_t>& other);
/**
* \brief Move constructor for DataContainer
* @brief Move constructor for DataContainer
*
* \param[in] other DataContainer to move from
* @param[in] other DataContainer to move from
*
* The moved-from objects remains in a valid state. However, as preconditions are not
* fulfilled for any member functions, the object should not be used. After move- or copy-
......@@ -92,9 +92,9 @@ namespace elsa
DataContainer(DataContainer<data_t>&& other) noexcept;
/**
* \brief Move assignment for DataContainer
* @brief Move assignment for DataContainer
*
* \param[in] other DataContainer to move from
* @param[in] other DataContainer to move from
*
* The moved-from objects remains in a valid state. However, as preconditions are not
* fulfilled for any member functions, the object should not be used. After move- or copy-
......@@ -107,9 +107,9 @@ namespace elsa
DataContainer<data_t>& operator=(DataContainer<data_t>&& other);
/**
* \brief Expression evaluation assignment for DataContainer
* @brief Expression evaluation assignment for DataContainer
*
* \param[in] source expression to evaluate
* @param[in] source expression to evaluate
*
* This evaluates an expression template term into the underlying data member of
* the DataHandler in use.
......@@ -137,9 +137,9 @@ namespace elsa
}
/**
* \brief Expression constructor
* @brief Expression constructor
*
* \param[in] source expression to evaluate
* @param[in] source expression to evaluate
*
* It creates a new DataContainer out of an expression. For this the meta information which
* is saved in the expression is used.
......@@ -387,9 +387,9 @@ namespace elsa
friend constexpr auto evaluateOrReturn(Operand const& operand);
/**
* \brief Factory function which returns GPU based DataContainers
* @brief Factory function which returns GPU based DataContainers
*
* \return the GPU based DataContainer
* @return the GPU based DataContainer
*
* Note that if this function is called on a container which is already GPU based, it will
* throw an exception.
......@@ -397,9 +397,9 @@ namespace elsa
DataContainer loadToGPU();
/**
* \brief Factory function which returns CPU based DataContainers
* @brief Factory function which returns CPU based DataContainers
*
* \return the CPU based DataContainer
* @return the CPU based DataContainer
*
* Note that if this function is called on a container which is already CPU based, it will
* throw an exception.
......@@ -428,12 +428,12 @@ namespace elsa
DataHandlerType dataType = defaultHandlerType);
/**
* \brief Helper function to indicate if a regular assignment or a clone should be performed
* @brief Helper function to indicate if a regular assignment or a clone should be performed
*
* \param[in] handlerType the member variable of the other container in
* @param[in] handlerType the member variable of the other container in
* copy-/move-assignment
*
* \return true if a regular assignment of the pointed to DataHandlers should be done
* @return true if a regular assignment of the pointed to DataHandlers should be done
*
* An assignment operation with a DataContainer which does not use the same device (CPU /
* GPU) has to be handled differently. This helper function indicates if a regular
......
......@@ -5,12 +5,12 @@
namespace elsa::detail
{
/**
* \brief iterator which uses a non-owning raw pointer to iterate over a container. The iterator
* @brief iterator which uses a non-owning raw pointer to iterate over a container. The iterator
* is random access and assumes contiguous memory layout.
*
* \author David Frank - initial implementation
* @author David Frank - initial implementation
*
* \tparam T - the type of the container
* @tparam T - the type of the container
*
* Note: comparing iterators from different containers is undefined behavior, so we do not check
* for it.
......@@ -119,13 +119,13 @@ namespace elsa::detail
};
/**
* \brief constant iterator which uses a non-owning raw pointer to iterate over a container. The
* @brief constant iterator which uses a non-owning raw pointer to iterate over a container. The
* iterator is random access and assumes contiguous memory layout. It is const in the sense that
* it cannot mutate the state of the object it iterates over.
*
* \author David Frank - initial implementation
* @author David Frank - initial implementation
*
* \tparam T - the type of the container
* @tparam T - the type of the container
*
* Note: comparing iterators from different containers is undefined behavior, so we do not check
* for it.
......
......@@ -8,12 +8,12 @@ namespace elsa
{
/**
* \brief Abstract class defining the interface of all block descriptors.
* @brief Abstract class defining the interface of all block descriptors.
*
* \author Matthias Wieczorek - initial code
* \author David Frank - rewrite
* \author Tobias Lasser - rewrite, modularization, modernization
* \author Nikola Dinev - rework into abstract class
* @author Matthias Wieczorek - initial code
* @author David Frank - rewrite
* @author Tobias Lasser - rewrite, modularization, modernization
* @author Nikola Dinev - rework into abstract class
*
* A block descriptor provides metadata about a signal that is stored in memory (typically a
* DataContainer). This signal can be n-dimensional, and will be stored in memory in a
......
......@@ -9,13 +9,13 @@ namespace elsa
{
/**
* \brief Base class for representing metadata for linearized n-dimensional signal stored in
* @brief Base class for representing metadata for linearized n-dimensional signal stored in
* memory
*
* \author Matthias Wieczorek - initial code
* \author Tobias Lasser - modularization, modernization
* \author Maximilian Hornung - various enhancements
* \author David Frank - inheritance restructuring
* @author Matthias Wieczorek - initial code
* @author Tobias Lasser - modularization, modernization
* @author Maximilian Hornung - various enhancements
* @author David Frank - inheritance restructuring
*
* This class provides an interface for metadata about a signal that is stored in memory. This
* base class provides other descriptor subclasses with a fundamental interface to access the
......@@ -32,23 +32,23 @@ namespace elsa
virtual ~DataDescriptor() = 0;
/**
* \brief Constructor for DataDescriptor, accepts dimension and size
* @brief Constructor for DataDescriptor, accepts dimension and size
*
* \param[in] numberOfCoefficientsPerDimension vector containing the number of coefficients
* @param[in] numberOfCoefficientsPerDimension vector containing the number of coefficients
* per dimension, (dimension is set implicitly from the size of the vector)
*
* \throw InvalidArgumentError if any number of coefficients is non-positive
* @throw InvalidArgumentError if any number of coefficients is non-positive
*/
explicit DataDescriptor(IndexVector_t numberOfCoefficientsPerDimension);
/**
* \brief Constructor for DataDescriptor, accepts dimension, size and spacing
* @brief Constructor for DataDescriptor, accepts dimension, size and spacing
*
* \param[in] numberOfCoefficientsPerDimension vector containing the number of coefficients
* @param[in] numberOfCoefficientsPerDimension vector containing the number of coefficients
* per dimension, (dimension is set implicitly from the size of the vector)
* \param[in] spacingPerDimension vector containing the spacing per dimension
* @param[in] spacingPerDimension vector containing the spacing per dimension
*
* \throw InvalidArgumentError if any number of coefficients is non-positive,
* @throw InvalidArgumentError if any number of coefficients is non-positive,
* or sizes of numberOfCoefficientsPerDimension and spacingPerDimension do not match
*/
explicit DataDescriptor(IndexVector_t numberOfCoefficientsPerDimension,
......@@ -70,10 +70,10 @@ namespace elsa
RealVector_t getLocationOfOrigin() const;
/**
* \brief computes the linearized index in the data vector from local coordinates
* @brief computes the linearized index in the data vector from local coordinates
*
* \param[in] coordinate vector containing the local coordinate
* \return the index into the linearized data vector
* @param[in] coordinate vector containing the local coordinate
* @return the index into the linearized data vector
*
* The local coordinates are integers, running from 0 to
* _numberOfCoefficientsPerDimension[i]-1 for every dimension i = 0,...,_numberOfDimensions.
......@@ -82,10 +82,10 @@ namespace elsa
index_t getIndexFromCoordinate(IndexVector_t coordinate) const;
/**
* \brief computes the local coordinates from a linearized index
* @brief computes the local coordinates from a linearized index
*
* \param[in] index into the linearized data vector
* \return the local coordinate corresponding to the index
* @param[in] index into the linearized data vector
* @return the local coordinate corresponding to the index
*
* The local coordinates are integers, running from 0 to
* _numberOfCoefficientsPerDimension[i]-1 for every dimension i = 0,...,_numberOfDimensions.
......
......@@ -5,14 +5,14 @@
namespace elsa
{
/**
* \brief Finds the descriptor with the same number of coefficients as the descriptors in
* @brief Finds the descriptor with the same number of coefficients as the descriptors in
* the list that retains as much information as possible
*
* \param[in] descriptorList a vector of plain pointers to DataDescriptor
* @param[in] descriptorList a vector of plain pointers to DataDescriptor
*
* \return std::unique_ptr<DataDescriptor> the best common descriptor
* @return std::unique_ptr<DataDescriptor> the best common descriptor
*
* \throw InvalidArgumentError if the vector is empty or the descriptors in the vector
* @throw InvalidArgumentError if the vector is empty or the descriptors in the vector
* don't all have the same size
*
* If all descriptors are equal, a clone of the first descriptor in the list is returned.
......
......@@ -6,10 +6,10 @@
namespace elsa
{
/**
* \brief Class representing a series of identical descriptors concatenated along a new
* @brief Class representing a series of identical descriptors concatenated along a new
* dimension (the last dimension of the full descriptor).
*
* \author Nikola Dinev
* @author Nikola Dinev
*
* The blocks are, essentially, slices (though not necessarily two-dimensional) of the full
* descriptor along its last dimension. The last dimension of the full descriptor serves solely
......@@ -22,15 +22,15 @@ namespace elsa
{
public:
/**
* \brief Create a new descriptor, replicating the dataDescriptor numberOfBlocks times
* @brief Create a new descriptor, replicating the dataDescriptor numberOfBlocks times
* along a new dimension
*
* \param[in] numberOfBlocks is the desired number of blocks
* \param[in] dataDescriptor is the descriptor that will be replicated numberOfBlocks
* @param[in] numberOfBlocks is the desired number of blocks
* @param[in] dataDescriptor is the descriptor that will be replicated numberOfBlocks
* times
* along a new dimension
*
* \throw InvalidArgumentError if numberOfBlocks is non-positive
* @throw InvalidArgumentError if numberOfBlocks is non-positive
*/
IdenticalBlocksDescriptor(index_t numberOfBlocks, const DataDescriptor& dataDescriptor);
......
......@@ -6,10 +6,10 @@
namespace elsa
{
/**
* \brief Class representing a descriptor obtained after the partition of a normal data
* @brief Class representing a descriptor obtained after the partition of a normal data
* descriptor into blocks.
*
* \author Nikola Dinev
* @author Nikola Dinev
*
* A single block of the PartitionDescriptor represents a linear segment containing one or more
* slices of the original descriptor, taken along its last dimension. This also means that the
......@@ -22,13 +22,13 @@ namespace elsa
{
public:
/**
* \brief Construct a PartitionDescriptor by partitioning a given descriptor into blocks of
* @brief Construct a PartitionDescriptor by partitioning a given descriptor into blocks of
* fairly equal sizes
*
* \param[in] dataDescriptor the descriptor to be partitioned
* \param[in] numberOfBlocks the number of blocks
* @param[in] dataDescriptor the descriptor to be partitioned
* @param[in] numberOfBlocks the number of blocks
*
* \throw InvalidArgumentError if numberOfBlocks is less than 2 or greater than the number
* @throw InvalidArgumentError if numberOfBlocks is less than 2 or greater than the number
* of coefficients in the last dimension
*
* If the given descriptor has a size of \f$ N \f$ in its last dimension, when dividing it
......@@ -42,13 +42,13 @@ namespace elsa
PartitionDescriptor(const DataDescriptor& dataDescriptor, index_t numberOfBlocks);
/**
* \brief Construct a PartitionDescriptor by specifying the number of slices contained in
* @brief Construct a PartitionDescriptor by specifying the number of slices contained in
* each block
*
* \param[in] dataDescriptor the descriptor to be partitioned
* \param[in] slicesInBlock the number of slices in each block
* @param[in] dataDescriptor the descriptor to be partitioned
* @param[in] slicesInBlock the number of slices in each block
*
* \throw InvalidArgumentError if slicesInBlock does not specify a valid partition scheme
* @throw InvalidArgumentError if slicesInBlock does not specify a valid partition scheme
* for the given descriptor
*
* Note: if the passed in DataDescriptor is a block descriptor, the block information
......
......@@ -7,13 +7,13 @@
namespace elsa
{
/**
* \brief Class representing a block descriptor whose different blocks may have completely
* @brief Class representing a block descriptor whose different blocks may have completely
* different descriptors.
*
* \author Matthias Wieczorek - initial code
* \author David Frank - rewrite
* \author Nikola Dinev - various enhancements
* \author Tobias Lasser - rewrite, modularization, modernization
* @author Matthias Wieczorek - initial code
* @author David Frank - rewrite
* @author Nikola Dinev - various enhancements
* @author Tobias Lasser - rewrite, modularization, modernization
*
* There are no restrictions whatsoever imposed on the descriptors of different blocks.
* Different blocks may even have different number of dimensions.
......@@ -26,21 +26,21 @@ namespace elsa
{
public:
/**
* \brief Construct a RandomBlocksDescriptor from a list of descriptors
* @brief Construct a RandomBlocksDescriptor from a list of descriptors
*
* \param[in] blockDescriptors the list of descriptors of each block
* @param[in] blockDescriptors the list of descriptors of each block
*
* \throw InvalidArgumentError if the list is empty
* @throw InvalidArgumentError if the list is empty
*/
RandomBlocksDescriptor(
const std::vector<std::unique_ptr<DataDescriptor>>& blockDescriptors);
/**
* \brief Construct a RandomBlocksDescriptor from a list of descriptors
* @brief Construct a RandomBlocksDescriptor from a list of descriptors
*
* \param[in] blockDescriptors the list of descriptors of each block
* @param[in] blockDescriptors the list of descriptors of each block
*
* \throw InvalidArgumentError if the list is empty
* @throw InvalidArgumentError if the list is empty
*/
RandomBlocksDescriptor(std::vector<std::unique_ptr<DataDescriptor>>&& blockDescriptors);
......
......@@ -6,12 +6,12 @@ namespace elsa
{
/**
* \brief Class representing metadata for linearized n-dimensional signal stored in memory
* @brief Class representing metadata for linearized n-dimensional signal stored in memory
*
* \author Matthias Wieczorek - initial code
* \author Tobias Lasser - modularization, modernization
* \author Maximilian Hornung - various enhancements
* \author David Frank - inheritance restructuring
* @author Matthias Wieczorek - initial code
* @author Tobias Lasser - modularization, modernization
* @author Maximilian Hornung - various enhancements
* @author David Frank - inheritance restructuring
*
* This class provides metadata about a signal that is stored in memory (typically a
* DataContainer). This signal can be n-dimensional, and will be stored in memory in a
......@@ -27,48 +27,48 @@ namespace elsa
~VolumeDescriptor() override = default;
/**
* \brief Constructor for DataDescriptor, accepts vector for coefficients per dimensions
* @brief Constructor for DataDescriptor, accepts vector for coefficients per dimensions
*
* \param[in] numberOfCoefficientsPerDimension vector containing the number of coefficients
* @param[in] numberOfCoefficientsPerDimension vector containing the number of coefficients
* per dimension, (dimension is set implicitly from the size of the vector)
*
* \throw InvalidArgumentError if any number of coefficients is non-positive
* @throw InvalidArgumentError if any number of coefficients is non-positive
*/
explicit VolumeDescriptor(IndexVector_t numberOfCoefficientsPerDimension);
/**
* \brief Constructs VolumeDescriptor from initializer list for the coefficients per
* @brief Constructs VolumeDescriptor from initializer list for the coefficients per
* dimensions
*
* \param[in] numberOfCoefficientsPerDimension initializer list containing the number of
* @param[in] numberOfCoefficientsPerDimension initializer list containing the number of
* coefficients per dimension (dimension is set implicitly from the size of the list)
*
* \throw InvalidArgumentError if any number of coefficients is non-positive
* @throw InvalidArgumentError if any number of coefficients is non-positive
*/
explicit VolumeDescriptor(std::initializer_list<index_t> numberOfCoefficientsPerDimension);
/**
* \brief Constructor for DataDescriptor, accepts vectors for coefficients and spacing
* @brief Constructor for DataDescriptor, accepts vectors for coefficients and spacing
*
* \param[in] numberOfCoefficientsPerDimension vector containing the number of coefficients
* @param[in] numberOfCoefficientsPerDimension vector containing the number of coefficients
* per dimension, (dimension is set implicitly from the size of the vector)
* \param[in] spacingPerDimension vector containing the spacing per dimension
* @param[in] spacingPerDimension vector containing the spacing per dimension
*
* \throw InvalidArgumentError if any number of coefficients or spacing is non-positive,
* @throw InvalidArgumentError if any number of coefficients or spacing is non-positive,
* or sizes of numberOfCoefficientsPerDimension and spacingPerDimension do not match
*/
explicit VolumeDescriptor(IndexVector_t numberOfCoefficientsPerDimension,
RealVector_t spacingPerDimension);
/**
* \brief Constructs VolumeDescriptor from two initializer lists for coefficients and
* @brief Constructs VolumeDescriptor from two initializer lists for coefficients and
* spacing
*
* \param[in] numberOfCoefficientsPerDimension initializer list containing the number of
* @param[in] numberOfCoefficientsPerDimension initializer list containing the number of
* coefficients per dimension (dimension is set implicitly from the size of the list)
* \param[in] spacingPerDimension initializer list containing the spacing per dimension
* @param[in] spacingPerDimension initializer list containing the spacing per dimension
*
* \throw InvalidArgumentError if any number of coefficients or spacing is non-positive,
* @throw InvalidArgumentError if any number of coefficients or spacing is non-positive,