From 4185058a896594ca78786fd739db9748cd0fb76a Mon Sep 17 00:00:00 2001
From: Snaipe <franklinmathieu@gmail.com>
Date: Fri, 27 Nov 2015 13:45:23 +0100
Subject: [PATCH] Added doxygen-style doc in criterion.h

---
 include/criterion/criterion.h | 70 +++++++++++++++++++++++++++++++++++
 include/criterion/types.h     | 17 +++++++--
 2 files changed, 83 insertions(+), 4 deletions(-)

diff --git a/include/criterion/criterion.h b/include/criterion/criterion.h
index c90114e..e1ce158 100644
--- a/include/criterion/criterion.h
+++ b/include/criterion/criterion.h
@@ -30,16 +30,86 @@
 
 # include "internal/test.h"
 
+/**
+ *  Test(Suite, Name, [Options...]) { Function body }
+ *
+ *  Defines a new test.
+ *
+ *  @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
+ *    pairs as described in the `criterion_test_extra_data` structure
+ *    (see criterion/types.h).
+ *    Example: .exit_code = 1
+ */
 # define Test(...) CR_EXPAND(CR_TEST_BASE(__VA_ARGS__, .sentinel_ = 0))
 
+/**
+ *  TestSuite(Name, [Options...]);
+ *
+ *  Explicitely defines a test suite and its options.
+ *
+ *  @param Name    The name of the test suite.
+ *  @param Options An optional sequence of designated initializer key/value
+ *    pairs as described in the `criterion_test_extra_data` structure
+ *    (see criterion/types.h).
+ *    These options will provide the defaults for each test.
+ */
 # define TestSuite(...) CR_EXPAND(CR_SUITE_BASE(__VA_ARGS__, .sentinel_ = 0))
 
 CR_BEGIN_C_API
 
+/**
+ *  Initializes criterion and builds a set of all discovered tests.
+ *
+ *  Using any of the functions and macros provided by criterion before calling
+ *  this results in undefined behaviour.
+ *
+ *  @returns the set of tests
+ */
 CR_API struct criterion_test_set *criterion_initialize(void);
+
+/**
+ *  Release all resources allocated by criterion.
+ *
+ *  Using any of the functions and macros provided by criterion except
+ *  criterion_initialize after this function is called results in undefined
+ *  behaviour.
+ */
 CR_API void criterion_finalize(struct criterion_test_set *tests);
+
+/**
+ *  Run all the tests in the test set.
+ *
+ *  @param[in] tests The set of tests that are to be executed.
+ *
+ *  @returns 1 if all tests succeeded or criterion_options.always_succeed
+ *    is true, 0 otherwise.
+ */
 CR_API int criterion_run_all_tests(struct criterion_test_set *tests);
+
+/**
+ *  Handles all default command-line parameters, as documented in:
+ *  <http://criterion.readthedocs.org/en/latest/env.html>, and appropriately
+ *  sets criterion_options.
+ *
+ *  @param[in] argc The number of arguments in argv.
+ *  @param[in] argv A null-terminated array of strings representing the arguments.
+ *  @param[in] handle_unknown_arg Whether the function should print a message
+ *    and exit when an unknown parameter is encountered. Use false if you want
+ *    to handle additional parameters yourself.
+ *
+ *  @returns 0 if the process should exit immediately after, for instance after
+ *    printing the help message.
+ */
 CR_API int criterion_handle_args(int argc, char *argv[], bool handle_unknown_arg);
+
+/**
+ *  Manually registers a new test within the specified test set.
+ *
+ *  @param[in] tests The set of tests you want to insert the test in.
+ *  @param[in] test  The newly created test.
+ */
 CR_API void criterion_register_test(struct criterion_test_set *tests,
                                     struct criterion_test *test);
 
diff --git a/include/criterion/types.h b/include/criterion/types.h
index 5c9cc33..2bb4a91 100644
--- a/include/criterion/types.h
+++ b/include/criterion/types.h
@@ -36,10 +36,10 @@ using std::size_t;
 # include "internal/common.h"
 
 enum criterion_language {
-    CR_LANG_C,
-    CR_LANG_CXX,
-    CR_LANG_OBJC,
-    CR_LANG_OBJCXX,
+    CR_LANG_C,              /// C
+    CR_LANG_CXX,            /// C++
+    CR_LANG_OBJC,           /// Objective-C
+    CR_LANG_OBJCXX,         /// Objective-C++
 
     CR_LANG_SIZE_ // leave this at the end
 };
@@ -54,6 +54,13 @@ enum criterion_test_kind {
 struct criterion_test_params;
 
 struct criterion_test_extra_data {
+    // Start of private API
+    /*
+     * Warning: the fields below are not meant to be set manually.
+     *  Setting them improperly *will* wreck havock in your tests.
+     *
+     * You've been warned.
+     */
     int sentinel_;
     enum criterion_language lang_;
     enum criterion_test_kind kind_;
@@ -61,6 +68,8 @@ struct criterion_test_extra_data {
     const char *identifier_;
     const char *file_;
     unsigned line_;
+    // Enf of private API
+
     void (*init)(void);
     void (*fini)(void);
     int signal;