Add doxygen comments

Convert comment blocks into doxygen type comments

opm/simulators/flow/ReservoirCoupling.hpp

@@ -41,32 +41,69 @@ enum class MessageTag : int {
 void custom_error_handler_(MPI_Comm* comm, int* err, const std::string &msg);
 void setErrhandler(MPI_Comm comm, bool is_master);
 
-// Utility class for comparing double values representing epoch dates (seconds since
-// unix epoch) or elapsed time (seconds since the start of the simulation).
-// NOTE: It is important that when comparing against start of a report step or similar, that
-//   that we do not miss these due to numerical issues. This is because communication between
-//   master and slave processes are based on these points in time.
-// NOTE: Epoch values in this century (2000-2100) lies in the range of [1e9,4e9], and a double variable cannot
-//  represent such large values with high precision. For example, the date 01-01-2020 is equal
-//  to 1.5778368e9 seconds and adding 1e-7 seconds to this value will not change the value.
-//  So microseconds (1e-6) is approximately the smallest time unit we can represent for such a number.
-// NOTE: Report steps seems to have a maximum resolution of whole seconds, see stepLength() in
-//   Schedule.cpp in opm-common, which returns the step length in seconds.
+/// \brief Utility class for comparing double values representing epoch dates or elapsed time.
+///
+/// This class is used to compare double values that represent:
+/// - Epoch dates (seconds since the Unix epoch)
+/// - Elapsed time (seconds since the start of the simulation)
+///
+/// \note When comparing against the start of a report step or similar, it is important not to miss
+/// these points due to numerical issues. Communication between master and slave processes is based
+/// on these specific points in time.
+///
+/// \note Epoch values in this century (2000-2100) fall within the range [1e9, 4e9]. A double variable
+/// cannot represent such large values with high precision. For example, the date 01-01-2020 corresponds
+/// to 1.5778368e9 seconds, and adding 1e-7 seconds to this value does not change it. Microseconds (1e-6)
+/// are approximately the smallest time units that can be represented accurately for such numbers.
+///
+/// \note Report steps appear to have a maximum resolution of whole seconds. See the `stepLength()`
+/// function in `Schedule.cpp` in the `opm-common` module, which returns the step length in seconds.
 struct Seconds {
+    /// \brief Absolute tolerance used for comparisons.
     static constexpr double abstol = 1e-15;
+
+    /// \brief Relative tolerance used for comparisons.
     static constexpr double reltol = 1e-15;
-    // We will will use the following expression to determine if two values a and b are equal:
-    //   |a - b| <= tol = abstol + reltol * max(|a|, |b|)
-    // For example, assume abstol = reltol = 1e-15, then the following holds:
-    // - If |a| and |b| are below 1, then the absolute tolerance applies.
-    // - If a and b are above 1, then the relative tolerance applies.
-    // For example, for dates in the range 01-01-2000 to 01-01-2100, epoch values will be in the range
-    //  [1e9, 4e9]. And we have 1e-15 * 1e9 = 1e-6, so numbers differing below one microsecond will
-    // be considered equal.
-    // NOTE: The above is not true for numbers close to zero, but we do not expect to compare such numbers.
+
+    /// \brief Determines if two double values are equal within a specified tolerance.
+    ///
+    /// Two values \a a and \a b are considered equal if:
+    /// \f[ |a - b| \leq \text{tol} = \text{abstol} + \text{reltol} \times \max(|a|, |b|) \f]
+    ///
+    /// For example, if \a abstol = \a reltol = 1e-15:
+    /// - If \a |a| and \a |b| are below 1, the absolute tolerance applies.
+    /// - If \a a and \a b are above 1, the relative tolerance applies.
+    ///
+    /// \note For epoch dates between 01-01-2000 and 01-01-2100, epoch values are in the range [1e9, 4e9].
+    /// Therefore, \f$ 10^{-15} \times 10^9 = 10^{-6} \f$, meaning differences smaller than one microsecond
+    /// will be considered equal.
+    ///
+    /// \note This approach is not accurate for numbers close to zero, but such comparisons are not expected.
+    ///
+    /// \param a First double value.
+    /// \param b Second double value.
+    /// \return True if \a a and \a b are considered equal within the tolerance.
     static bool compare_eq(double a, double b);
+
+   /// \brief Determines if \a a is greater than \a b within the specified tolerance.
+    ///
+    /// \param a First double value.
+    /// \param b Second double value.
+    /// \return True if \a a is greater than \a b.
     static bool compare_gt(double a, double b);
+
+   /// \brief Determines if \a a is greater than \a b within the specified tolerance.
+    ///
+    /// \param a First double value.
+    /// \param b Second double value.
+    /// \return True if \a a is greater than \a b.
     static bool compare_gt_or_eq(double a, double b);
+
+    /// \brief Determines if \a a is less than or equal to \a b within the specified tolerance.
+    ///
+    /// \param a First double value.
+    /// \param b Second double value.
+    /// \return True if \a a is less than or equal to \a b.
     static bool compare_lt_or_eq(double a, double b);
 };