Completed documentation with parameter reference, test-suite configuration, custom output provider, and various fixes

doc/env.rst

@@ -14,7 +14,7 @@ Command line arguments
 * ``-f or --fail-fast``: Exit after the first test failure.
 * ``--ascii``: Don't use fancy unicode symbols or colors in the output.
 * ``--pattern [PATTERN]``: Run tests whose string identifier matches
-  the given shell wildcard pattern (see dedicated section below).
+  the given shell wildcard pattern (see dedicated section below). (\*nix only)
 * ``--no-early-exit``: The test workers shall not prematurely exit when done and
   will properly return from the main, cleaning up their process space.
   This is useful when tracking memory leaks with ``valgrind --tool=memcheck``.
@@ -27,7 +27,8 @@ Shell Wildcard Pattern
 ----------------------
 
 Patterns in criterion are matched against a test's string identifier with
-``fnmatch``.
+``fnmatch``. This feature is only available on \*nix systems where ``fnmatch``
+is provided.
 
 Special characters used in shell-style wildcard patterns are:
 
@@ -61,4 +62,4 @@ Environment variables are alternatives to command line switches when set to 1.
 * ``CRITERION_VERBOSITY_LEVEL``: Same as ``--verbose``. Sets the verbosity level
   to its value.
 * ``CRITERION_TEST_PATTERN``:    Same as ``--pattern``. Sets the test pattern
-  to its value.
+  to its value. (\*nix only)

doc/faq.rst

@@ -14,4 +14,5 @@ There are plenty of ways to fix that behaviour:
 **Q. I'm having an issue with the library, what can I do ?**
 
 A. Open a new issue on the `github issue tracker <https://github.com/Snaipe/Criterion/issues>`_,
-and describe the problem you are experiencing.
+and describe the problem you are experiencing, along with the platform you are
+running criterion on.

doc/hooks.rst

@@ -17,6 +17,10 @@ A report hook can be declared using the ``ReportHook`` macro:
 The macro takes a Phase parameter that indicates the phase at which the function
 shall be run. Valid phases are described below.
 
+**Note**: there are no guarantees regarding the order of execution of report hooks
+on the same phase. In other words, all report hooks of a specific phase could
+be executed in any order.
+
 Testing Phases
 --------------
 
@@ -49,3 +53,18 @@ Valid types for each phases are:
 * ``struct criterion_test_stats *`` for ``POST_TEST``, ``POST_FINI``, and ``TEST_CRASH``.
 * ``struct criterion_suite_stats *`` for ``POST_SUITE``.
 * ``struct criterion_global_stats *`` for ``POST_ALL``.
+
+For instance, these are valid report hook declarations for the ``PRE_TEST`` phase:
+
+.. code-block:: c
+
+    #include <criterion/criterion.h>
+    #include <criterion/hooks.h>
+
+    ReportHook(PRE_TEST)() {
+        // not using the parameter
+    }
+
+    ReportHook(PRE_TEST)(struct criterion_test *test) {
+        // using the parameter
+    }

doc/internal.rst

@@ -39,3 +39,16 @@ Starting the test runner
 
 The test runner can be called with ``criterion_run_all_tests``. The function
 returns 0 if one test or more failed, 1 otherwise.
+
+Implementing your own output provider
+-------------------------------------
+
+In case you are not satisfied by the default output provider, you can implement
+yours. To do so, simply set the ``output_provider`` option to your custom
+output provider.
+
+Each function contained in the structure is called during one of the standard
+phase of the criterion runner.
+
+For more insight on how to implement this, see other existing output providers
+in ``src/log/``.

doc/starter.rst

@@ -68,8 +68,16 @@ On top of those, more assertions are available for common operations:
 * ``{assert,expect}_arrays_eq(Actual, Expected, Size, [Message])``
 * ``{assert,expect}_arrays_neq(Actual, Unexpected, Size, [Message])``
 
+Please note that ``arrays_(n)eq`` assertions should not be used for padded structures.
+
+Configuring tests
+-----------------
+
+Tests may receive optional configuration parameters to alter their behaviour
+or provide additional metadata.
+
 Fixtures
---------
+~~~~~~~~
 
 Tests that need some setup and teardown can register functions that will
 run before and after the test function:
@@ -91,8 +99,13 @@ run before and after the test function:
         // test contents
     }
 
+If a setup crashes, you will get a warning message, and the test will be aborted
+and marked as a failure.
+Is a teardown crashes, you will get a warning message, and the test will keep
+its result.
+
 Testing signals
----------------
+~~~~~~~~~~~~~~~
 
 If a test receives a signal, it will by default be marked as a failure.
 You can, however, expect a test to only pass if a special kind of signal
@@ -115,3 +128,47 @@ is received:
         int *ptr = NULL;
         *ptr = 42;
     }
+
+This feature will of course not work on Windows.
+
+Configuration reference
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Here is an exhaustive list of all possible configuration parameters you can
+pass:
+
+============= =============== ==============================================================
+Parameter     Type            Description
+============= =============== ==============================================================
+.description  const char *    Adds a description. Cannot be ``NULL``.
+------------- --------------- --------------------------------------------------------------
+.init         void (*)(void)  Adds a setup function the be executed before the test.
+------------- --------------- --------------------------------------------------------------
+.fini         void (*)(void)  Adds a teardown function the be executed after the test.
+------------- --------------- --------------------------------------------------------------
+.disabled     bool            Disables the test.
+------------- --------------- --------------------------------------------------------------
+.signal       int             Expect the test to raise the specified signal.
+============= =============== ==============================================================
+
+Setting up suite-wise configuration
+-----------------------------------
+
+Tests under the same suite can have a suite-wise configuration -- this is done
+using the ``TestSuite`` macro:
+
+.. code-block:: c
+
+    #include <criterion/criterion.h>
+
+    TestSuite(suite_name, [params...]);
+
+    Test(suite_name, test_1) {
+    }
+
+    Test(suite_name, test_2) {
+    }
+
+Configuration parameters are the same as above, but applied to the suite itself.
+
+Suite fixtures are run *along with* test fixtures.