@micro-os-plus/micro-test-plus 3.1.1 → 3.2.0

package/include/micro-os-plus/test-reporter.h

@@ -23,7 +23,7 @@
 
 // ----------------------------------------------------------------------------
 
-//#include <functional>
+// #include <functional>
 #include <string_view>
 #include <string>
 
@@ -47,6 +47,10 @@ namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
 
+  /**
+   * @brief Colours used to highlight pass vs. fail.
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+   */
   struct colors
   {
     const char* none = "\033[0m";
@@ -54,6 +58,10 @@ namespace micro_os_plus::micro_test_plus
     const char* fail = "\033[31m";
   };
 
+  /**
+   * @brief The verbosity levels.
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+   */
   enum class verbosity
   {
     silent = 0, // Nothing, only return the exit code
@@ -74,6 +82,7 @@ namespace micro_os_plus::micro_test_plus
   /**
    * @brief Reporter to display the test results. For failed
    * tests it prints the actual values of the operands, with their types.
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
   class test_reporter
   {
@@ -176,9 +185,10 @@ namespace micro_os_plus::micro_test_plus
     /**
      * @brief Output operator to display containers. Iterate all members.
      */
-    template <class T, type_traits::requires_t<
-                           type_traits::is_container_v<
-                               T> and not type_traits::has_npos_v<T>> = 0>
+    template <class T,
+              type_traits::requires_t<type_traits::is_container_v<T>
+                                      and not type_traits::has_npos_v<T>>
+              = 0>
     test_reporter&
     operator<< (T&& t);
 

package/include/micro-os-plus/test-runner.h

@@ -44,8 +44,9 @@ namespace micro_os_plus::micro_test_plus
   // --------------------------------------------------------------------------
 
   /**
-   * @brief The test runner. It maintaines a list of test suites which
+   * @brief The test runner. It maintains a list of test suites which
    * automatically register themselves in their constructors.
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
   class test_runner
   {
@@ -66,7 +67,7 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Pass the main arguments explicitly, if the default
-     * contructor was used.
+     * constructor was used.
      */
     void
     initialize (int argc, char* argv[], const char* name);

package/include/micro-os-plus/test-suite.h

@@ -44,14 +44,15 @@ namespace micro_os_plus::micro_test_plus
   // --------------------------------------------------------------------------
 
   /**
-   * @brief Test suites are classes that represent a named group of
-   * test cases which self registers to the runner.
+   * @brief Base class for all test suites.
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
   class test_suite_base
   {
   public:
     /**
-     * @brief Construct the default suite used in main().
+     * @brief Construct a test suite.
+     * @param [in] name The test suite name.
      */
     test_suite_base (const char* name);
 
@@ -69,24 +70,38 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Run the sequence of test cases in the suite.
+     * @par Parameters
+     *	None.
+     * @par Returns
+     *  Nothing.
      */
     virtual void
     run (void);
 
     /**
-     * @brief Mark the begining of a named test case.
+     * @brief Mark the beginning of a named test case.
+     * @param [in] name The test case name.
+     * @par Returns
+     *  Nothing.
      */
     void
     begin_test_case (const char* name);
 
     /**
      * @brief Mark the end of a test case.
+     * @par Parameters
+     *	None.
+     * @par Returns
+     *  Nothing.
      */
     void
     end_test_case (void);
 
     /**
      * @brief Get the suite name.
+     * @par Parameters
+     *	None.
+     * @return A pointer to the null terminated test suite name.
      */
     [[nodiscard]] constexpr const char*
     name ()
@@ -95,19 +110,30 @@ namespace micro_os_plus::micro_test_plus
     }
 
     /**
-     * @brief Count one more passed test condition.
+     * @brief Count one more passed test conditions.
+     * @par Parameters
+     *	None.
+     * @par Returns
+     *  Nothing.
      */
     void
     increment_successful (void);
 
     /**
-     * @brief Count one more failed test condition.
+     * @brief Count one more failed test conditions.
+     * @par Parameters
+     *	None.
+     * @par Returns
+     *  Nothing.
      */
     void
     increment_failed (void);
 
     /**
      * @brief Get the number of conditions that passed.
+     * @par Parameters
+     *	None.
+     * @return An integer with the number checks that passed.
      */
     [[nodiscard]] constexpr int
     successful_checks (void)
@@ -117,6 +143,9 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Get the number of conditions that failed.
+     * @par Parameters
+     *	None.
+     * @return An integer with the number checks that failed.
      */
     [[nodiscard]] constexpr int
     failed_checks (void)
@@ -126,6 +155,9 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Get the number of test cases.
+     * @par Parameters
+     *	None.
+     * @return An integer with the number of test cases.
      */
     [[nodiscard]] constexpr int
     test_cases (void)
@@ -135,18 +167,29 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Begin the execution of the test suite.
+     * @par Parameters
+     *	None.
+     * @par Returns
+     *  Nothing.
      */
     void
     begin_test_suite (void);
 
     /**
      * @brief Mark the end of the test suite.
+     * @par Parameters
+     *	None.
+     * @par Returns
+     *  Nothing.
      */
     void
     end_test_suite (void);
 
     /**
      * @brief Get the test suite result.
+     * @par Parameters
+     *	None.
+     * @return True if the test suite was successful.
      */
     [[nodiscard]] constexpr bool
     was_successful (void)
@@ -155,6 +198,12 @@ namespace micro_os_plus::micro_test_plus
       return (failed_checks_ == 0 && successful_checks_ != 0);
     }
 
+    /**
+     * @brief If all counter are null, it is unused.
+     * @par Parameters
+     *	None.
+     * @return True if the test suite is not used.
+     */
     [[nodiscard]] constexpr bool
     unused (void)
     {
@@ -197,9 +246,26 @@ namespace micro_os_plus::micro_test_plus
     } current_test_case{};
   };
 
+  /**
+   * @ingroup micro-test-plus-test-suites
+   * @brief Test suites are classes that represent a named group of
+   * test cases which self register to the runner.
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+   */
   class test_suite : public test_suite_base
   {
   public:
+    /**
+     * @brief Construct a test suite.
+     * @tparam Callable_T The type of an object that can be called.
+     * @tparam Args_T The type of the callable arguments.
+     * @param [in] name The test case name or description.
+     * A short string used in the report.
+     * @param [in] callable A generic callable object,
+     * invoked to perform the test. Usually a lambda.
+     * @param [in] arguments A possibly empty list of arguments to be
+     * passed to the callable.
+     */
     template <typename Callable_T, typename... Args_T>
     test_suite (const char* name, Callable_T&& callable,
                 Args_T&&... arguments);

package/include/micro-os-plus/type-traits.h

@@ -45,22 +45,39 @@ namespace micro_os_plus::micro_test_plus
    */
   namespace type_traits
   {
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class...>
     struct list
     {
     };
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class T, class...>
     struct identity
     {
       using type = T;
     };
 
+#if defined(__DOXYGEN__)
+    // error: Detected potential recursive class relation between class
+    // micro_os_plus::micro_test_plus::type_traits::function_traits and base
+    // class micro_os_plus::micro_test_plus::type_traits::function_traits<
+    // decltype(&T::operator())>!
+    // https://github.com/doxygen/doxygen/issues/9915
+#else
     template <class T>
     struct function_traits : function_traits<decltype (&T::operator())>
     {
     };
+#endif
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class R, class... Args_T>
     struct function_traits<R (*) (Args_T...)>
     {
@@ -68,6 +85,9 @@ namespace micro_os_plus::micro_test_plus
       using args = list<Args_T...>;
     };
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class R, class... Args_T>
     struct function_traits<R (Args_T...)>
     {
@@ -75,6 +95,9 @@ namespace micro_os_plus::micro_test_plus
       using args = list<Args_T...>;
     };
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class R, class T, class... Args_T>
     struct function_traits<R (T::*) (Args_T...)>
     {
@@ -82,6 +105,9 @@ namespace micro_os_plus::micro_test_plus
       using args = list<Args_T...>;
     };
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class R, class T, class... Args_T>
     struct function_traits<R (T::*) (Args_T...) const>
     {
@@ -107,9 +133,8 @@ namespace micro_os_plus::micro_test_plus
     }
 
     template <class T>
-    static constexpr auto is_container_v
-        = is_valid<T> ([] (auto t) -> decltype (t.begin (), t.end (),
-                                                void ()) {});
+    static constexpr auto is_container_v = is_valid<T> (
+        [] (auto t) -> decltype (t.begin (), t.end (), void ()) {});
 
     template <class T>
     static constexpr auto has_npos_v
@@ -134,7 +159,7 @@ namespace micro_os_plus::micro_test_plus
 
 #if defined(__clang__) or defined(_MSC_VER)
     template <class From, class To>
-    static constexpr auto is_convertible_v = __is_convertible_to(From, To);
+    static constexpr auto is_convertible_v = __is_convertible_to (From, To);
 #else
     template <class From, class To>
     constexpr auto
@@ -152,11 +177,17 @@ namespace micro_os_plus::micro_test_plus
     constexpr auto is_convertible_v = is_convertible<From, To> (0);
 #endif
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <bool>
     struct requires_
     {
     };
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <>
     struct requires_<true>
     {
@@ -168,6 +199,7 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Empty base class of all operators.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     struct op
     {
@@ -176,6 +208,7 @@ namespace micro_os_plus::micro_test_plus
     /**
      * @brief A generic integral constant.
      * It has a getter and a '-' operator to return the negative value.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <auto N>
     struct integral_constant : op
@@ -189,7 +222,8 @@ namespace micro_os_plus::micro_test_plus
         return integral_constant<-N>{};
       }
 
-      [[nodiscard]] constexpr explicit operator value_type () const
+      [[nodiscard]] constexpr explicit
+      operator value_type () const
       {
         return N;
       }
@@ -205,6 +239,7 @@ namespace micro_os_plus::micro_test_plus
      * @brief A generic floating point constant, with custom size
      * and precision.
      * It has a getter and a '-' operator to return the negative value.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class T, auto N, auto D, auto Size, auto P = 1>
     struct floating_point_constant : op
@@ -221,7 +256,8 @@ namespace micro_os_plus::micro_test_plus
         return floating_point_constant<T, N, D, Size, -1>{};
       }
 
-      [[nodiscard]] constexpr explicit operator value_type () const
+      [[nodiscard]] constexpr explicit
+      operator value_type () const
       {
         return value;
       }
@@ -233,6 +269,9 @@ namespace micro_os_plus::micro_test_plus
       }
     };
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class T>
     struct genuine_integral_value : op
     {
@@ -242,7 +281,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr explicit operator T () const
+      [[nodiscard]] constexpr explicit
+      operator T () const
       {
         return value_;
       }
@@ -257,10 +297,11 @@ namespace micro_os_plus::micro_test_plus
     };
 
     template <class T>
-    inline constexpr auto is_op_v = __is_base_of(type_traits::op, T);
+    inline constexpr auto is_op_v = __is_base_of (type_traits::op, T);
 
     /**
      * @brief Class defining a generic value, accessible via a getter.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class T, class = int>
     struct value : type_traits::op
@@ -271,7 +312,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr explicit operator T () const
+      [[nodiscard]] constexpr explicit
+      operator T () const
       {
         return value_;
       }
@@ -290,6 +332,7 @@ namespace micro_os_plus::micro_test_plus
      * in addition to the actual value, has an epsilon, to use the
      * desired precision during comparisons.
      * If missing, the default is 1 / (10^decimals).
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class T>
     struct value<T,
@@ -312,7 +355,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr explicit operator T () const
+      [[nodiscard]] constexpr explicit
+      operator T () const
       {
         return value_;
       }

package/meson.build

@@ -14,7 +14,7 @@
 
 # This file is intended to be consumed by applications with:
 #
-# `subdir('xpacks/micro-os-plus-micro-test-plus')`
+# `subdir('xpacks/@micro-os-plus/micro-test-plus')`
 #
 # The result is a library and a dependency that can be referred as:
 #
@@ -29,18 +29,21 @@ message('Processing xPack @micro-os-plus/micro-test-plus...')
 
 # -----------------------------------------------------------------------------
 
-xpack_common_args = []
-xpack_c_args = []
-xpack_cpp_args = []
-xpack_include_directories = []
-xpack_sources = []
-xpack_compile_definitions = []
+_local_compile_args = [] # Common C/C++ args.
+_local_compile_c_args = []
+_local_compile_cpp_args = []
+_local_include_directories = []
+_local_sources = []
+_local_compile_definitions = []
+_local_dependencies = []
+_local_link_args = []
+_local_link_with = []
 
-xpack_include_directories += [
+_local_include_directories += [
   'include',
 ]
 
-xpack_sources += [
+_local_sources += [
   'src/micro-test-plus.cpp',
   'src/test-runner.cpp',
   'src/test-reporter.cpp',
@@ -49,18 +52,21 @@ xpack_sources += [
 
 # https://mesonbuild.com/Reference-manual_functions.html#declare_dependency
 micro_os_plus_micro_test_plus_dependency = declare_dependency(
-  include_directories: include_directories(xpack_include_directories),
-  compile_args: xpack_common_args,
-  sources: files(xpack_sources),
+  include_directories: include_directories(_local_include_directories),
+  compile_args: _local_compile_args,
+  sources: files(_local_sources),
+  dependencies: _local_dependencies,
+  link_args: _local_link_args,
+  link_with: _local_link_with,
 )
+# meson dependencies cannot differentiate c/cpp args; pass them separately.
+micro_os_plus_micro_test_plus_dependency_compile_c_args = _local_compile_c_args
+micro_os_plus_micro_test_plus_dependency_compile_cpp_args = _local_compile_cpp_args
 
-# micro_os_plus_micro_test_plus_dependency_c_args = xpack_c_args
-# micro_os_plus_micro_test_plus_dependency_cpp_args = xpack_cpp_args
-
-foreach name : xpack_include_directories
+foreach name : _local_include_directories
   message('+ -I ' + name)
 endforeach
-foreach name : xpack_sources + xpack_common_args
+foreach name : _local_sources + _local_compile_definitions + _local_compile_args + _local_compile_c_args + _local_compile_cpp_args
   message('+ ' + name)
 endforeach
 message('> micro_os_plus_micro_test_plus_dependency')