From 26d0d48fb5e49c1aad0f3528032d43f1993dd73c Mon Sep 17 00:00:00 2001
From: Mark Olesen <Mark.Olesen@esi-group.com>
Date: Wed, 9 Jan 2019 09:08:20 +0100
Subject: [PATCH] STYLE: doxygen comments for min/max functions

---
 src/OpenFOAM/primitives/Scalar/doubleFloat.H | 18 ++++++++-------
 src/OpenFOAM/primitives/ints/int/int.H       | 22 ++++++++++---------
 src/OpenFOAM/primitives/ints/uint/uint.H     | 23 ++++++++++----------
 3 files changed, 34 insertions(+), 29 deletions(-)

diff --git a/src/OpenFOAM/primitives/Scalar/doubleFloat.H b/src/OpenFOAM/primitives/Scalar/doubleFloat.H
index 8bd9e0e0dd..f52ce17dad 100644
--- a/src/OpenFOAM/primitives/Scalar/doubleFloat.H
+++ b/src/OpenFOAM/primitives/Scalar/doubleFloat.H
@@ -58,6 +58,7 @@ public:
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
+//- Compare two values for equality
 template<class T>
 inline bool equal(const T& s1, const T& s2)
 {
@@ -65,24 +66,25 @@ inline bool equal(const T& s1, const T& s2)
 }
 
 
-#define MAXMINPOW(retType, type1, type2)          \
-                                                  \
-MAXMIN(retType, type1, type2)                     \
-                                                  \
-inline double pow(const type1 s, const type2 e)   \
-{                                                 \
-    return ::pow(double(s), double(e));           \
+#define MAXMINPOW(retType, type1, type2)                \
+                                                        \
+MAXMIN(retType, type1, type2)                           \
+                                                        \
+/** \brief Raise base to the power expon */             \
+inline double pow(const type1 base, const type2 expon)  \
+{                                                       \
+    return ::pow(double(base), double(expon));          \
 }
 
 
 MAXMINPOW(double, double, double)
 MAXMINPOW(double, double, float)
 MAXMINPOW(double, float, double)
-MAXMINPOW(float, float, float)
 MAXMINPOW(double, double, int)
 MAXMINPOW(double, int, double)
 MAXMINPOW(double, double, long)
 MAXMINPOW(double, long, double)
+MAXMINPOW(float, float, float)
 MAXMINPOW(float, float, int)
 MAXMINPOW(float, int, float)
 MAXMINPOW(float, float, long)
diff --git a/src/OpenFOAM/primitives/ints/int/int.H b/src/OpenFOAM/primitives/ints/int/int.H
index ab122eda99..34c9517b97 100644
--- a/src/OpenFOAM/primitives/ints/int/int.H
+++ b/src/OpenFOAM/primitives/ints/int/int.H
@@ -44,16 +44,18 @@ SourceFiles
 namespace Foam
 {
 
-#define MAXMIN(retType, type1, type2)              \
-                                                   \
-inline retType max(const type1 s1, const type2 s2) \
-{                                                  \
-    return (s1 > s2)? s1: s2;                      \
-}                                                  \
-                                                   \
-inline retType min(const type1 s1, const type2 s2) \
-{                                                  \
-    return (s1 < s2)? s1: s2;                      \
+#define MAXMIN(retType, type1, type2)                                          \
+                                                                               \
+/** \brief Floating/integral min. Use stdFoam::min() to preserve references */ \
+inline retType min(const type1 s1, const type2 s2)                             \
+{                                                                              \
+    return (s1 < s2) ? s1 : s2;                                                \
+}                                                                              \
+                                                                               \
+/** \brief Floating/integral max. Use stdFoam::max() to preserve references */ \
+inline retType max(const type1 s1, const type2 s2)                             \
+{                                                                              \
+    return (s2 < s1) ? s1 : s2;                                                \
 }
 
 
diff --git a/src/OpenFOAM/primitives/ints/uint/uint.H b/src/OpenFOAM/primitives/ints/uint/uint.H
index 67eeb08b20..87d4a0a987 100644
--- a/src/OpenFOAM/primitives/ints/uint/uint.H
+++ b/src/OpenFOAM/primitives/ints/uint/uint.H
@@ -44,19 +44,20 @@ SourceFiles
 namespace Foam
 {
 
-#define MAXMIN(retType, type1, type2)              \
-                                                   \
-inline retType max(const type1 s1, const type2 s2) \
-{                                                  \
-    return (s1 > s2)? s1: s2;                      \
-}                                                  \
-                                                   \
-inline retType min(const type1 s1, const type2 s2) \
-{                                                  \
-    return (s1 < s2)? s1: s2;                      \
+#define MAXMIN(retType, type1, type2)                                          \
+                                                                               \
+/** \brief Floating/integral min. Use stdFoam::min() to preserve references */ \
+inline retType min(const type1 s1, const type2 s2)                             \
+{                                                                              \
+    return (s1 < s2) ? s1 : s2;                                                \
+}                                                                              \
+                                                                               \
+/** \brief Floating/integral max. Use stdFoam::max() to preserve references */ \
+inline retType max(const type1 s1, const type2 s2)                             \
+{                                                                              \
+    return (s2 < s1) ? s1 : s2;                                                \
 }
 
-
 MAXMIN(uint8_t, uint8_t, uint8_t)
 MAXMIN(uint16_t, uint16_t, uint16_t)