Update documentation.

Add UNITY_PRINT_TEST_CONTEXT (thanks @jlindgren90 !)
Replaces PR #473

docs/UnityAssertionsReference.md

@@ -67,18 +67,20 @@ to be well designed code.
 
 The convention of assertion parameters generally follows this order:
 
-    TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} )
+```
+TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} )
+```
 
-The very simplest assertion possible uses only a single "actual" parameter (e.g.
+The very simplest assertion possible uses only a single `actual` parameter (e.g.
 a simple null check).
 
-"Actual" is the value being tested and unlike the other parameters in an
-assertion construction is the only parameter present in all assertion variants.
-"Modifiers" are masks, ranges, bit flag specifiers, floating point deltas.
-"Expected" is your expected value (duh) to compare to an "actual" value; it's
-marked as an optional parameter because some assertions only need a single
-"actual" parameter (e.g. null check).
-"Size/count" refers to string lengths, number of array elements, etc.
+ - `Actual` is the value being tested and unlike the other parameters in an
+    assertion construction is the only parameter present in all assertion variants.
+ - `Modifiers` are masks, ranges, bit flag specifiers, floating point deltas.
+ - `Expected` is your expected value (duh) to compare to an `actual` value; it's
+    marked as an optional parameter because some assertions only need a single
+    `actual` parameter (e.g. null check).
+ - `Size/count` refers to string lengths, number of array elements, etc.
 
 Many of Unity's assertions are clear duplications in that the same data type
 is handled by several assertions. The differences among these are in how failure
@@ -98,11 +100,15 @@ the reference list below and add a string as the final parameter.
 
 _Example:_
 
-    TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} )
+```
+TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} )
+```
 
 becomes messageified like thus...
 
-    TEST_ASSERT_X_MESSAGE( {modifiers}, {expected}, actual, {size/count}, message )
+```
+TEST_ASSERT_X_MESSAGE( {modifiers}, {expected}, actual, {size/count}, message )
+```
 
 Notes:
 - The `_MESSAGE` variants intentionally do not support `printf` style formatting
@@ -122,18 +128,21 @@ with the `_MESSAGE`variants of Unity's Asserts in that for pretty much any Unity
 type assertion you can tack on `_ARRAY` and run assertions on an entire block of
 memory.
 
+```
     TEST_ASSERT_EQUAL_TYPEX_ARRAY( expected, actual, {size/count} )
+```
 
-"Expected" is an array itself.
-"Size/count" is one or two parameters necessary to establish the number of array
-elements and perhaps the length of elements within the array.
+ - `Expected` is an array itself.
+ - `Size/count` is one or two parameters necessary to establish the number of array
+    elements and perhaps the length of elements within the array.
 
 Notes:
-- The `_MESSAGE` variant convention still applies here to array assertions. The
-`_MESSAGE` variants of the `_ARRAY` assertions have names ending with
-`_ARRAY_MESSAGE`.
-- Assertions for handling arrays of floating point values are grouped with float
-and double assertions (see immediately following section).
+
+ - The `_MESSAGE` variant convention still applies here to array assertions. The
+   `_MESSAGE` variants of the `_ARRAY` assertions have names ending with
+   `_ARRAY_MESSAGE`.
+ - Assertions for handling arrays of floating point values are grouped with float
+   and double assertions (see immediately following section).
 
 
 ### TEST_ASSERT_EACH_EQUAL_X Variants
@@ -142,19 +151,22 @@ Unity provides a collection of assertions for arrays containing a variety of
 types which can be compared to a single value as well. These are documented in
 the Each Equal section below. these are almost on par with the `_MESSAGE`
 variants of Unity's Asserts in that for pretty much any Unity type assertion you
-can inject _EACH_EQUAL and run assertions on an entire block of memory.
+can inject `_EACH_EQUAL` and run assertions on an entire block of memory.
 
-    TEST_ASSERT_EACH_EQUAL_TYPEX( expected, actual, {size/count} )
+```
+TEST_ASSERT_EACH_EQUAL_TYPEX( expected, actual, {size/count} )
+```
 
-"Expected" is a single value to compare to.
-"Actual" is an array where each element will be compared to the expected value.
-"Size/count" is one of two parameters necessary to establish the number of array
-elements and perhaps the length of elements within the array.
+ - `Expected` is a single value to compare to.
+ - `Actual` is an array where each element will be compared to the expected value.
+ - `Size/count` is one of two parameters necessary to establish the number of array
+    elements and perhaps the length of elements within the array.
 
 Notes:
-- The `_MESSAGE` variant convention still applies here to Each Equal assertions.
-- Assertions for handling Each Equal of floating point values are grouped with
-float and double assertions (see immediately following section).
+
+ - The `_MESSAGE` variant convention still applies here to Each Equal assertions.
+ - Assertions for handling Each Equal of floating point values are grouped with
+   float and double assertions (see immediately following section).
 
 
 ### Configuration
@@ -189,6 +201,7 @@ performing logic beyond a simple assertion. That is, in practice, `TEST_FAIL()`
 will always be found inside a conditional code block.
 
 _Examples:_
+
 - Executing a state machine multiple times that increments a counter your test
 code then verifies as a final step.
 - Triggering an exception and verifying it (as in Try / Catch / Throw - see the

docs/UnityConfigurationGuide.md

@@ -392,6 +392,24 @@ _Example:_
 #define UNITY_EXCLUDE_DETAILS
 ```
 
+##### `UNITY_PRINT_TEST_CONTEXT`
+
+This option allows you to specify your own function to print additional context
+as part of the error message when a test has failed. It can be useful if you
+want to output some specific information about the state of the test at the point
+of failure, and `UNITY_SET_DETAILS` isn't flexible enough for your needs.
+
+_Example:_
+```C
+#define UNITY_PRINT_TEST_CONTEXT PrintIterationCount
+
+extern int iteration_count;
+
+void PrintIterationCount(void)
+{
+  UnityPrintFormatted("At iteration #%d: ", iteration_count);
+}
+```
 
 ##### `UNITY_EXCLUDE_SETJMP`
 

docs/UnityHelperScriptsGuide.md

@@ -48,7 +48,7 @@ ruby generate_test_runner.rb TestFile.c NameOfRunner.c
 ```
 
 Alternatively, if you include only the test file parameter, the script will copy
-the name of the test file and automatically append "_Runner" to the name of the
+the name of the test file and automatically append `_Runner` to the name of the
 generated file. The example immediately below will create TestFile_Runner.c.
 
 ```Shell
@@ -194,6 +194,18 @@ If you are using CMock, it is very likely that you are already passing an array
 of plugins to CMock. You can just use the same array here. This script will just
 ignore the plugins that don't require additional support.
 
+##### `:include_extensions`
+
+This option specifies the pattern for matching acceptable header file extensions.
+By default it will accept hpp, hh, H, and h files. If you need a different combination
+of files to search, update this from the default `'(?:hpp|hh|H|h)'`.
+
+##### `:source_extensions`
+
+This option specifies the pattern for matching acceptable source file extensions.
+By default it will accept cpp, cc, C, c, and ino files. If you need a different combination
+of files to search, update this from the default `'(?:cpp|cc|ino|C|c)'`.
+
 
 ### `unity_test_summary.rb`
 

src/unity.c

@@ -566,6 +566,10 @@ static void UnityAddMsgIfSpecified(const char* msg)
     if (msg)
     {
         UnityPrint(UnityStrSpacer);
+
+#ifdef UNITY_PRINT_TEST_CONTEXT
+        UNITY_PRINT_TEST_CONTEXT();
+#endif
 #ifndef UNITY_EXCLUDE_DETAILS
         if (Unity.CurrentDetail1)
         {
@@ -1760,6 +1764,9 @@ void UnityFail(const char* msg, const UNITY_LINE_TYPE line)
     {
         UNITY_OUTPUT_CHAR(':');
 
+#ifdef UNITY_PRINT_TEST_CONTEXT
+        UNITY_PRINT_TEST_CONTEXT();
+#endif
 #ifndef UNITY_EXCLUDE_DETAILS
         if (Unity.CurrentDetail1)
         {

src/unity_internals.h

@@ -509,6 +509,10 @@ void UnityDefaultTestRun(UnityTestFunction Func, const char* FuncName, const int
 #endif
 #endif
 
+#ifdef UNITY_PRINT_TEST_CONTEXT
+void UNITY_PRINT_TEST_CONTEXT(void);
+#endif
+
 /*-------------------------------------------------------
  * Test Output
  *-------------------------------------------------------*/