@micro-os-plus/micro-test-plus 3.1.0 → 3.1.2

package/include/micro-os-plus/detail.h

@@ -41,7 +41,7 @@ namespace micro_os_plus::micro_test_plus
   // --------------------------------------------------------------------------
 
   /**
-   * @brief Implementation details, not part of the public API.
+   * @brief Namespace with implementation details, not part of the public API.
    */
   namespace detail
   {
@@ -87,7 +87,7 @@ namespace micro_os_plus::micro_test_plus
     [[nodiscard]] constexpr auto
     get (const T& t)
     {
-      // Call the variadic function, besically to force it return `t`.
+      // Call the variadic function, basically to force it return `t`.
       return get_impl (t, 0);
     }
 
@@ -117,16 +117,15 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wpedantic"
 #endif
 #endif
-              if constexpr (type_traits::has_value_v<
-                                Lhs_T> and type_traits::has_value_v<Rhs_T>)
+              if constexpr (type_traits::has_value_v<Lhs_T>
+                            and type_traits::has_value_v<Rhs_T>)
                 {
                   // If both types have values (like numeric constants),
                   // compare them directly.
                   return Lhs_T::value == Rhs_T::value;
                 }
-              else if constexpr (
-                  type_traits::has_epsilon_v<
-                      Lhs_T> and type_traits::has_epsilon_v<Rhs_T>)
+              else if constexpr (type_traits::has_epsilon_v<Lhs_T>
+                                 and type_traits::has_epsilon_v<Rhs_T>)
                 {
                   // If both values have precision, compare them using
                   // the smalles precision.
@@ -156,7 +155,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -201,14 +201,13 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wpedantic"
 #endif
 #endif
-              if constexpr (type_traits::has_value_v<
-                                Lhs_T> and type_traits::has_value_v<Rhs_T>)
+              if constexpr (type_traits::has_value_v<Lhs_T>
+                            and type_traits::has_value_v<Rhs_T>)
                 {
                   return Lhs_T::value != Rhs_T::value;
                 }
-              else if constexpr (
-                  type_traits::has_epsilon_v<
-                      Lhs_T> and type_traits::has_epsilon_v<Rhs_T>)
+              else if constexpr (type_traits::has_epsilon_v<Lhs_T>
+                                 and type_traits::has_epsilon_v<Rhs_T>)
                 {
                   return math::abs (get (lhs_) - get (rhs_))
                          > math::min_value (Lhs_T::epsilon, Rhs_T::epsilon);
@@ -232,7 +231,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -272,8 +272,8 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wpedantic"
 #endif
 #endif
-              if constexpr (type_traits::has_value_v<
-                                Lhs_T> and type_traits::has_value_v<Rhs_T>)
+              if constexpr (type_traits::has_value_v<Lhs_T>
+                            and type_traits::has_value_v<Rhs_T>)
                 {
                   return Lhs_T::value > Rhs_T::value;
                 }
@@ -288,7 +288,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -328,8 +329,8 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wpedantic"
 #endif
 #endif
-              if constexpr (type_traits::has_value_v<
-                                Lhs_T> and type_traits::has_value_v<Rhs_T>)
+              if constexpr (type_traits::has_value_v<Lhs_T>
+                            and type_traits::has_value_v<Rhs_T>)
                 {
                   return Lhs_T::value >= Rhs_T::value;
                 }
@@ -344,7 +345,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -384,8 +386,8 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wpedantic"
 #endif
 #endif
-              if constexpr (type_traits::has_value_v<
-                                Lhs_T> and type_traits::has_value_v<Rhs_T>)
+              if constexpr (type_traits::has_value_v<Lhs_T>
+                            and type_traits::has_value_v<Rhs_T>)
                 {
                   return Lhs_T::value < Rhs_T::value;
                 }
@@ -400,7 +402,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -441,8 +444,8 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wpedantic"
 #endif
 #endif
-              if constexpr (type_traits::has_value_v<
-                                Lhs_T> and type_traits::has_value_v<Rhs_T>)
+              if constexpr (type_traits::has_value_v<Lhs_T>
+                            and type_traits::has_value_v<Rhs_T>)
                 {
                   return Lhs_T::value <= Rhs_T::value;
                 }
@@ -457,7 +460,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -486,12 +490,13 @@ namespace micro_os_plus::micro_test_plus
     struct and_ : type_traits::op
     {
       constexpr and_ (const Lhs_T& lhs = {}, const Rhs_T& rhs = {})
-          : lhs_{ lhs }, rhs_{ rhs }, value_{ static_cast<bool> (lhs)
-                                              and static_cast<bool> (rhs) }
+          : lhs_{ lhs }, rhs_{ rhs },
+            value_{ static_cast<bool> (lhs) and static_cast<bool> (rhs) }
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -520,12 +525,13 @@ namespace micro_os_plus::micro_test_plus
     struct or_ : type_traits::op
     {
       constexpr or_ (const Lhs_T& lhs = {}, const Rhs_T& rhs = {})
-          : lhs_{ lhs }, rhs_{ rhs }, value_{ static_cast<bool> (lhs)
-                                              or static_cast<bool> (rhs) }
+          : lhs_{ lhs }, rhs_{ rhs },
+            value_{ static_cast<bool> (lhs) or static_cast<bool> (rhs) }
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -558,7 +564,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -599,7 +606,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -628,7 +636,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -657,7 +666,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -668,6 +678,10 @@ namespace micro_os_plus::micro_test_plus
 
     // ------------------------------------------------------------------------
 
+    /**
+     * @brief Base class for a deferred reporter, that collects the
+     * messages into a string.
+     */
     class deferred_reporter_base
     {
     public:
@@ -698,6 +712,10 @@ namespace micro_os_plus::micro_test_plus
       std::string message_{};
     };
 
+    /**
+     * @brief Class template for a deferred reporter specific
+     * to an expression.
+     */
     template <class Expr_T>
     class deferred_reporter : public deferred_reporter_base
     {

package/include/micro-os-plus/inlines.h

@@ -40,8 +40,8 @@ namespace micro_os_plus::micro_test_plus
   template <typename Callable_T, typename... Args_T>
   test_suite::test_suite (const char* name, Callable_T&& callable,
                           Args_T&&... arguments)
-      : test_suite_base{ name }, callable_{ std::bind (callable,
-                                                       arguments...) }
+      : test_suite_base{ name },
+        callable_{ std::bind (callable, arguments...) }
   {
 #if defined(MICRO_TEST_PLUS_TRACE)
     printf ("%s\n", __PRETTY_FUNCTION__);
@@ -52,16 +52,44 @@ namespace micro_os_plus::micro_test_plus
 
   // --------------------------------------------------------------------------
 
+  /**
+   * @details
+   * A test case is a sequence of test conditions (or simply tests,
+   * or checks), which are expectations/assumptions, i.e. conditions
+   * expected to be true.
+   *
+   * Tests are based on logical expressions, which usually compute
+   * a result and compare it to an expected value.
+   * For C++ projects, it is also possible to check if, while
+   * evaluating an expression, exceptions are thrown or not.
+   * Each test either succeeds or fails.
+   * For expectations, the runner keeps counts of successful
+   * and failed tests.
+   *
+   * A test case has a name, a function which performs the checks, and
+   * possibly arguments.
+   *
+   * The `test_case` implementation invokes the function with
+   * the provided arguments, and reports the results.
+   *
+   * @par Example
+   *
+   * ```cpp
+   *   test_case ("Check answer with comparator", [] {
+   *     expect (eq (compute_answer (), 42)) << "answer is 42";
+   *   });
+   * ```
+   */
   template <typename Callable_T, typename... Args_T>
   void
-  test_case (const char* name, Callable_T&& func, Args_T&&... arguments)
+  test_case (const char* name, Callable_T&& callable, Args_T&&... arguments)
   {
 #if 0 // defined(MICRO_TEST_PLUS_TRACE)
     printf ("%s\n", __PRETTY_FUNCTION__);
 #endif // MICRO_TEST_PLUS_TRACE
 
     current_test_suite->begin_test_case (name);
-    std::invoke (std::forward<Callable_T> (func),
+    std::invoke (std::forward<Callable_T> (callable),
                  std::forward<Args_T> (arguments)...);
     current_test_suite->end_test_case ();
   }
@@ -92,9 +120,8 @@ namespace micro_os_plus::micro_test_plus
     constexpr deferred_reporter<Expr_T>::deferred_reporter (
         const Expr_T& expr, bool abort,
         const reflection::source_location& location)
-        : deferred_reporter_base{ static_cast<bool> (expr), location }, expr_{
-            expr
-          }
+        : deferred_reporter_base{ static_cast<bool> (expr), location },
+          expr_{ expr }
     {
 #if 0 // defined(MICRO_TEST_PLUS_TRACE)
       printf ("%s\n", __PRETTY_FUNCTION__);
@@ -121,6 +148,18 @@ namespace micro_os_plus::micro_test_plus
   // --------------------------------------------------------------------------
   namespace utility
   {
+    /**
+     * @details
+     * For tests handling strings, this function template allows
+     * to split a string into a vector of substrings, using a delimiter.
+     *
+     * @par Example
+     * ```cpp
+     * expect (std::vector<std::string_view>{ "a", "b" }
+     *             == utility::split<std::string_view> ("a.b", "."))
+     *         << "a.b splits into [a,b]";
+     * ```
+     */
     template <class T = std::string_view, class Delim_T>
     [[nodiscard]] auto
     split (T input, Delim_T delim) -> std::vector<T>

package/include/micro-os-plus/literals.h

@@ -25,6 +25,7 @@
 
 #include "type-traits.h"
 #include "math.h"
+#include <cstdint>
 
 // ----------------------------------------------------------------------------
 
@@ -47,135 +48,235 @@ namespace micro_os_plus::micro_test_plus
    */
   namespace literals
   {
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `int`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_i ()
+    [[nodiscard]] constexpr auto
+    operator""_i ()
     {
       return type_traits::integral_constant<math::num<int, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `short`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_s ()
+    [[nodiscard]] constexpr auto
+    operator""_s ()
     {
       return type_traits::integral_constant<math::num<short, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `char`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_c ()
+    [[nodiscard]] constexpr auto
+    operator""_c ()
     {
       return type_traits::integral_constant<math::num<char, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `signed char`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_sc ()
+    [[nodiscard]] constexpr auto
+    operator""_sc ()
     {
       return type_traits::integral_constant<
           math::num<signed char, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `long`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_l ()
+    [[nodiscard]] constexpr auto
+    operator""_l ()
     {
       return type_traits::integral_constant<math::num<long, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `long long`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_ll ()
+    [[nodiscard]] constexpr auto
+    operator""_ll ()
     {
       return type_traits::integral_constant<math::num<long long, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `unsigned`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_u ()
+    [[nodiscard]] constexpr auto
+    operator""_u ()
     {
       return type_traits::integral_constant<math::num<unsigned, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `unsigned char`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_uc ()
+    [[nodiscard]] constexpr auto
+    operator""_uc ()
     {
       return type_traits::integral_constant<
           math::num<unsigned char, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `unsigned short`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_us ()
+    [[nodiscard]] constexpr auto
+    operator""_us ()
     {
       return type_traits::integral_constant<
           math::num<unsigned short, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `unsigned long`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_ul ()
+    [[nodiscard]] constexpr auto
+    operator""_ul ()
     {
       return type_traits::integral_constant<
           math::num<unsigned long, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `unsigned long long`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_ull ()
+    [[nodiscard]] constexpr auto
+    operator""_ull ()
     {
       return type_traits::integral_constant<
           math::num<unsigned long long, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `int8_t`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_i8 ()
+    [[nodiscard]] constexpr auto
+    operator""_i8 ()
     {
       return type_traits::integral_constant<
           math::num<std::int8_t, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `int16_t`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_i16 ()
+    [[nodiscard]] constexpr auto
+    operator""_i16 ()
     {
       return type_traits::integral_constant<
           math::num<std::int16_t, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `int32_t`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_i32 ()
+    [[nodiscard]] constexpr auto
+    operator""_i32 ()
     {
       return type_traits::integral_constant<
           math::num<std::int32_t, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `int64_t`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_i64 ()
+    [[nodiscard]] constexpr auto
+    operator""_i64 ()
     {
       return type_traits::integral_constant<
           math::num<std::int64_t, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `uint8_t`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_u8 ()
+    [[nodiscard]] constexpr auto
+    operator""_u8 ()
     {
       return type_traits::integral_constant<
           math::num<std::uint8_t, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `uint16_t`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_u16 ()
+    [[nodiscard]] constexpr auto
+    operator""_u16 ()
     {
       return type_traits::integral_constant<
           math::num<std::uint16_t, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `uint32_t`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_u32 ()
+    [[nodiscard]] constexpr auto
+    operator""_u32 ()
     {
       return type_traits::integral_constant<
           math::num<std::uint32_t, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `uint64_t`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_u64 ()
+    [[nodiscard]] constexpr auto
+    operator""_u64 ()
     {
       return type_traits::integral_constant<
           math::num<std::uint64_t, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `float`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_f ()
+    [[nodiscard]] constexpr auto
+    operator""_f ()
     {
       return type_traits::floating_point_constant<
           float, math::num<unsigned long, Cs...> (),
@@ -183,8 +284,13 @@ namespace micro_os_plus::micro_test_plus
           math::den_size<unsigned long, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `double`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_d ()
+    [[nodiscard]] constexpr auto
+    operator""_d ()
     {
       return type_traits::floating_point_constant<
           double, math::num<unsigned long, Cs...> (),
@@ -192,8 +298,13 @@ namespace micro_os_plus::micro_test_plus
           math::den_size<unsigned long, Cs...> ()>{};
     }
 
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `long double`.
+     */
     template <char... Cs>
-    [[nodiscard]] constexpr auto operator""_ld ()
+    [[nodiscard]] constexpr auto
+    operator""_ld ()
     {
       return type_traits::floating_point_constant<
           long double, math::num<unsigned long long, Cs...> (),
@@ -201,12 +312,18 @@ namespace micro_os_plus::micro_test_plus
           math::den_size<unsigned long long, Cs...> ()>{};
     }
 
-    constexpr auto operator""_b (const char* name, decltype (sizeof ("")) size)
+    /**
+     * @ingroup micro-test-plus-literals
+     * @brief Operator to convert to `bool`.
+     */
+    constexpr auto
+    operator""_b (const char* name, decltype (sizeof ("")) size)
     {
       struct named : std::string_view, type_traits::op
       {
         using value_type = bool;
-        [[nodiscard]] constexpr operator value_type () const
+        [[nodiscard]] constexpr
+        operator value_type () const
         {
           return true;
         }
@@ -230,6 +347,11 @@ namespace micro_os_plus::micro_test_plus
 
   // --------------------------------------------------------------------------
 
+  /**
+   * @addtogroup micro-test-plus-literals
+   * @{
+   */
+
   // Wrappers that can be used to convert dynamic values to specific types
   // that are recognised by the comparators.
   // The syntax is similar to function calls, like `_i(expression)`, but the
@@ -258,7 +380,14 @@ namespace micro_os_plus::micro_test_plus
   using _d = type_traits::value<double>;
   using _ld = type_traits::value<long double>;
 
-  // Template for wrapping any other type.
+  /**
+   * @}
+   */
+
+  /**
+   * @ingroup micro-test-plus-literals
+   * @brief Template for wrapping any other type.
+   */
   template <class T>
   struct _t : type_traits::value<T>
   {