From 4fa8754911e57c26db947f5754bab660f601b1d8 Mon Sep 17 00:00:00 2001
From: Nina Dzugasova <dzugasova.nina@gmail.com>
Date: Wed, 28 Nov 2018 13:37:49 +0100
Subject: [PATCH] Added documentation of Math, Assert and ParameterContainer.
---
src/TNL/Assert.h | 7 ++++++
src/TNL/Config/ParameterContainer.h | 29 ++++++++++++++++++----
src/TNL/Math.h | 37 +++++++++++++++++++++++++----
src/TNL/Object.h | 5 ++--
4 files changed, 68 insertions(+), 10 deletions(-)
diff --git a/src/TNL/Assert.h b/src/TNL/Assert.h
index 6d13e35b11..34b721fe6e 100644
--- a/src/TNL/Assert.h
+++ b/src/TNL/Assert.h
@@ -33,6 +33,13 @@
#if defined(NDEBUG) || defined(HAVE_MIC)
// empty macros for optimized build
+/**
+ * \brief Assert that the expression \e val evaluates to \e true.
+ *
+ * The assertion succeeds if, and only if, \e val evaluates to equal to \e true.
+ * On success the test continues without any side effects.
+ * On failure the test is terminated with the error message \e msg.
+ */
#define TNL_ASSERT_TRUE( val, msg )
#define TNL_ASSERT_FALSE( val, msg )
#define TNL_ASSERT_EQ( val1, val2, msg )
diff --git a/src/TNL/Config/ParameterContainer.h b/src/TNL/Config/ParameterContainer.h
index 55ef460d19..f524d29176 100644
--- a/src/TNL/Config/ParameterContainer.h
+++ b/src/TNL/Config/ParameterContainer.h
@@ -50,10 +50,11 @@ class ParameterContainer
ParameterContainer();
/**
- * \brief Adds parameter
- * @tparam T Type of parameter value.
- * @param name Name of the parameter.
- * @param value Value assigned to the parameter.
+ * \brief Adds new parameter to the ParameterContainer.
+ *
+ * \tparam T Type of parameter value.
+ * \param name Name of the new parameter.
+ * \param value Value assigned to the parameter.
*/
template< class T > bool addParameter( const String& name,
const T& value );
@@ -61,8 +62,20 @@ class ParameterContainer
bool addParameter( const String& name,
const String& value );
+ /**
+ * \brief Checks whether the parameter \e name already exists in ParameterContainer.
+ *
+ * \param name Name of the parameter.
+ */
bool checkParameter( const String& name ) const;
+ /**
+ * \brief Assigns new \e value to the parameter \e name.
+ *
+ * \tparam T Type of the parameter value.
+ * \param name Name of parameter.
+ * \param value Value of type T assigned to the parameter.
+ */
template< class T > bool setParameter( const String& name,
const T& value );
@@ -89,6 +102,11 @@ class ParameterContainer
return false;
}
+ /**
+ * \brief Returns parameter value.
+ *
+ * \param name Name of parameter.
+ */
template< class T > const T& getParameter( const String& name ) const
{
int i;
@@ -104,6 +122,9 @@ class ParameterContainer
//! Broadcast to other nodes in MPI cluster
// void MPIBcast( int root, MPI_Comm mpi_comm = MPI_COMM_WORLD );
+ /**
+ * \brief Basic destructor.
+ */
~ParameterContainer();
protected:
diff --git a/src/TNL/Math.h b/src/TNL/Math.h
index b32244c9ce..34cd91eebc 100644
--- a/src/TNL/Math.h
+++ b/src/TNL/Math.h
@@ -20,6 +20,7 @@ namespace TNL {
/***
* \brief This function returns minimum of two numbers.
+ *
* GPU device code uses the functions defined in the CUDA's math_functions.h,
* MIC uses trivial override and host uses the STL functions.
*/
@@ -44,6 +45,7 @@ ResultType min( const T1& a, const T2& b )
/***
* \brief This function returns maximum of two numbers.
+ *
* GPU device code uses the functions defined in the CUDA's math_functions.h,
* MIC uses trivial override and host uses the STL functions.
*/
@@ -65,8 +67,8 @@ ResultType max( const T1& a, const T2& b )
#endif
}
-/***
- * \brief This function returns absolute value of given number.
+/**
+ * \brief This function returns absolute value of given number \e n.
*/
template< class T >
__cuda_callable__ inline
@@ -126,6 +128,9 @@ ResultType argAbsMax( const T1& a, const T2& b )
return ( TNL::abs( a ) > TNL::abs( b ) ) ? a : b;
}
+/**
+ * \brief This function returns the result of \e base to the power of \e exp.
+ */
template< typename T1, typename T2, typename ResultType = typename std::common_type< T1, T2 >::type >
__cuda_callable__ inline
ResultType pow( const T1& base, const T2& exp )
@@ -138,7 +143,7 @@ ResultType pow( const T1& base, const T2& exp )
}
/**
- * \brief This function returns square root of a value.
+ * \brief This function returns square root of the given \e value.
*/
template< typename T >
__cuda_callable__ inline
@@ -153,6 +158,8 @@ T sqrt( const T& value )
/**
* \brief This function swaps values of two parameters.
+ *
+ * It assigns the value of \e a to the parameter \e b and vice versa.
*/
template< typename Type >
__cuda_callable__
@@ -166,7 +173,9 @@ void swap( Type& a, Type& b )
/**
* \brief This function represents the signum function.
*
- * It extracts the sign of a real number.
+ * It extracts the sign of the number \e a. In other words, the signum function projects
+ * negative numbers to value -1, positive numbers to value 1 and zero to value 0.
+ * Non-zero complex numbers are projected to the unit circle.
*/
template< class T >
__cuda_callable__
@@ -177,6 +186,14 @@ T sign( const T& a )
return ( T ) 1;
}
+/**
+ * \brief This function tests whether the given real number is small.
+ *
+ * It tests whether the number \e v is in \e tolerance, in other words, whether
+ * \e v in absolute value is less then or equal to \e tolerance.
+ * @param v Real number.
+ * @param tolerance Critical value which is set to 0.00001 by defalt.
+ */
template< typename Real >
__cuda_callable__
bool isSmall( const Real& v,
@@ -185,12 +202,24 @@ bool isSmall( const Real& v,
return ( -tolerance <= v && v <= tolerance );
}
+/**
+ * \brief This function divides \e num by \e div and rounds up the result.
+ *
+ * @param num An integer considered as dividend.
+ * @param div An integer considered as divisor.
+ */
__cuda_callable__
inline int roundUpDivision( const int num, const int div )
{
return num / div + ( num % div != 0 );
}
+/**
+ * \brief This function rounds \e number to the nearest multiple of number \e multiple.
+ *
+ * @param number Integer we want to round.
+ * @param multiple Integer.
+ */
__cuda_callable__
inline int roundToMultiple( int number, int multiple )
{
diff --git a/src/TNL/Object.h b/src/TNL/Object.h
index 4b37d8a77a..b4f2250752 100644
--- a/src/TNL/Object.h
+++ b/src/TNL/Object.h
@@ -17,8 +17,9 @@
namespace TNL {
-//! This is basic class for all 'large' objects like matrices, meshes, grids, solvers etc.
-/*!
+/**
+ * \brief This is the basic class for all 'large' objects like matrices, meshes, grids, solvers, etc..
+ *
* Objects like numerical grids, meshes, matrices large vectors etc.
* are inherited by this class. This class provides name for such objects. Giving
* a name to each bigger object is compulsory. The name can help to locate
--
GitLab