doc: Integrated doxygen docs for parameterized tests in sphinx

doc/parameterized.rst

@@ -14,6 +14,8 @@ Adding parameterized tests
 Adding parameterized tests is done by defining the parameterized test function,
 and the parameter generator function:
 
+.. doxygengroup:: ParameterizedBase
+
 .. code-block:: c
 
     #include <criterion/parameterized.h>

include/criterion/internal/parameterized.h

@@ -112,4 +112,13 @@ struct criterion_test_params {
     (struct criterion_test_params) { .size = sizeof (Type), (void*)(Array), __VA_ARGS__ }
 # endif
 
+# undef ParameterizedTest
+# define ParameterizedTest(...) CR_EXPAND(CR_PARAM_TEST_BASE(__VA_ARGS__, .sentinel_ = 0))
+
+# undef ParameterizedTestParameters
+# define ParameterizedTestParameters(Suite, Name) CR_PARAM_TEST_PARAMS(Suite, Name)
+
+# undef cr_make_param_array
+# define cr_make_param_array(...) CR_EXPAND(cr_make_param_array_(__VA_ARGS__))
+
 #endif /* !CRITERION_INTERNAL_PARAMETERIZED_H_ */

include/criterion/parameterized.h

@@ -30,7 +30,11 @@
 
 # include "alloc.h"
 # include "assert.h"
-# include "internal/parameterized.h"
+
+/**
+ * @defgroup ParameterizedBase Parameterized test & generator macros
+ * @{
+ */
 
 /**
  *  ParameterizedTest(Type *param, Suite, Name, [Options...]) { Function Body }
@@ -43,45 +47,59 @@
  *  @param Type    The type of the parameter.
  *  @param Suite   The name of the test suite containing this test.
  *  @param Name    The name of the test.
- *  @param Options An optional sequence of designated initializer key/value
+ *  @param ...     An optional sequence of designated initializer key/value
  *    pairs as described in the `criterion_test_extra_data` structure
  *    (see criterion/types.h).
- *    Example: .exit_code = 1
+ *    Example: `.exit_code = 1`
  */
-# define ParameterizedTest(...) CR_EXPAND(CR_PARAM_TEST_BASE(__VA_ARGS__, .sentinel_ = 0))
+# define ParameterizedTest(Type, Suite, Name, ...) <internal>
 
 /**
- *  ParameterizedTestParameters(Suite, Test) { Function Body }
- *
- *  Defines the parameter generator for the associated parameterized test.
+ *  Defines the parameter generator prototype for the associated parameterized
+ *  test.
  *
  *  @param Suite   The name of the test suite containing the test.
  *  @param Test    The name of the test.
  *  @returns A constructed instance of criterion::parameters, or the result of
  *    the cr_make_param_array macro.
  */
-# define ParameterizedTestParameters(Suite, Name) CR_PARAM_TEST_PARAMS(Suite, Name)
+# define ParameterizedTestParameters(Suite, Name) <internal>
 
 /**
- *  cr_make_param_array(Type, Array, Len, [Cleanup]);
- *
  *  Constructs a parameter list used as a return value for a parameter generator.
  *
+ *  This is only recommended for C sources. For C++, use `criterion::parameters`
+ *  or `criterion_test_params`.
+ *
  *  @param Type     The type of the array subscript.
  *  @param Array    The array of parameters.
  *  @param Len      The length of the array.
  *  @param Cleanup  The optional cleanup function for the array.
  *  @returns The parameter list.
  */
-# define cr_make_param_array(...) CR_EXPAND(cr_make_param_array_(__VA_ARGS__))
+# define cr_make_param_array(Type, Array, Len, Cleanup) <internal>
 
 # ifdef __cplusplus
 #  include <vector>
 
 namespace criterion {
+
+    /**
+     *  Represents a C++ dynamic parameter list for a parameter generator.
+     *
+     *  @param Type     The type of the array subscript.
+     *  @param Array    The array of parameters.
+     *  @param Len      The length of the array.
+     *  @param Cleanup  The optional cleanup function for the array.
+     *  @returns The parameter list.
+     */
     template <typename T>
     using parameters = std::vector<T, criterion::allocator<T>>;
 }
 # endif
 
+/** @} */
+
+# include "internal/parameterized.h"
+
 #endif /* !CRITERION_PARAMETERIZED_H_ */