Merge pull request #347 from kykrueger/issue-#346-documentation-improvement

Issue #346 documentation improvement

README.md

@@ -2,56 +2,16 @@ Unity Test API
 ==============
 
 [![Unity Build Status](https://api.travis-ci.org/ThrowTheSwitch/Unity.png?branch=master)](https://travis-ci.org/ThrowTheSwitch/Unity)
-__Copyright (c) 2007 - 2017 Unity Project by Mike Karlesky, Mark VanderVoord, and Greg Williams__
-
-Running Tests
--------------
-
-    RUN_TEST(func, linenum)
-
-Each Test is run within the macro `RUN_TEST`. This macro performs necessary setup before the test is called and handles cleanup and result tabulation afterwards.
-
-Ignoring Tests
---------------
-
-There are times when a test is incomplete or not valid for some reason.  At these times, TEST_IGNORE can be called.  Control will immediately be returned to the caller of the test, and no failures will be returned.
-
-    TEST_IGNORE()
-
-Ignore this test and return immediately
-
-    TEST_IGNORE_MESSAGE (message)
-
-Ignore this test and return immediately.  Output a message stating why the test was ignored.
-
-Aborting Tests
---------------
-
-There are times when a test will contain an infinite loop on error conditions, or there may be reason to escape from the test early without executing the rest of the test.  A pair of macros support this functionality in Unity.  The first `TEST_PROTECT` sets up the feature, and handles emergency abort cases. `TEST_ABORT` can then be used at any time within the tests to return to the last `TEST_PROTECT` call.
-
-    TEST_PROTECT()
-
-Setup and Catch macro
-
-    TEST_ABORT()
-
-Abort Test macro
-
-Example:
-
-    main()
-    {
-        if (TEST_PROTECT())
-        {
-            MyTest();
-        }
-    }
-
-If MyTest calls `TEST_ABORT`, program control will immediately return to `TEST_PROTECT` with a return value of zero.
+__Copyright (c) 2007 - 2019 Unity Project by Mike Karlesky, Mark VanderVoord, and Greg Williams__
 
+Getting Started
+===============
+The [docs](docs/) folder contains a [getting started guide](docs/UnityGettingStartedGuide.md)
+and much more tips about using Unity. 
 
 Unity Assertion Summary
 =======================
+For the full list, see [UnityAssertionsReference.md](docs/UnityAssertionsReference.md).
 
 Basic Validity Tests
 --------------------

docs/UnityGettingStartedGuide.md

@@ -114,10 +114,10 @@ call.
 
 Remembering to add each test to the main function can get to be tedious. If you
 enjoy using helper scripts in your build process, you might consider making use
-of our handy generate_test_runner.rb script. This will create the main function
-and all the calls for you, assuming that you have followed the suggested naming
-conventions. In this case, there is no need for you to include the main function
-in your test file at all.
+of our handy [generate_test_runner.rb](../auto/generate_test_runner.rb) script.
+This will create the main function and all the calls for you, assuming that you
+have followed the suggested naming conventions. In this case, there is no need
+for you to include the main function in your test file at all.
 
 When you're done, your test file will look something like this:
 
@@ -141,6 +141,7 @@ void test_function_should_doAlsoDoBlah(void) {
     //more test stuff
 }
 
+// not needed when using generate_test_runner.rb
 int main(void) {
     UNITY_BEGIN();
     RUN_TEST(test_function_should_doBlahAndBlah);
@@ -153,6 +154,63 @@ It's possible that you will need more customization than this, eventually.
 For that sort of thing, you're going to want to look at the configuration guide.
 This should be enough to get you going, though.
 
+### Running Test Functions
+When writing your own `main()` functions, for a test-runner. There are two ways
+to execute the test. 
+
+The classic variant
+``` c
+RUN_TEST(func, linenum)
+```
+or its simpler replacement that starts at the beginning of the function.
+``` c
+RUN_TEST(func)
+```
+These macros perform the necessary setup before the test is called and
+handles cleanup and result tabulation afterwards.
+
+### Ignoring Test Functions
+There are times when a test is incomplete or not valid for some reason. 
+At these times, TEST_IGNORE can be called. Control will immediately be 
+returned to the caller of the test, and no failures will be returned.
+This is useful when your test runners are automatically generated.
+
+``` c
+TEST_IGNORE()
+```
+
+Ignore this test and return immediately
+
+``` c
+TEST_IGNORE_MESSAGE (message)
+```
+
+Ignore this test and return immediately. Output a message stating why the test was ignored.
+
+### Aborting Tests
+There are times when a test will contain an infinite loop on error conditions, or there may be reason to escape from the test early without executing the rest of the test.  A pair of macros support this functionality in Unity.  The first `TEST_PROTECT` sets up the feature, and handles emergency abort cases. `TEST_ABORT` can then be used at any time within the tests to return to the last `TEST_PROTECT` call.
+
+    TEST_PROTECT()
+
+Setup and Catch macro
+
+    TEST_ABORT()
+
+Abort Test macro
+
+Example:
+
+    main()
+    {
+        if (TEST_PROTECT())
+        {
+            MyTest();
+        }
+    }
+
+If MyTest calls `TEST_ABORT`, program control will immediately return to `TEST_PROTECT` with a return value of zero.
+
+
 
 ## How to Build and Run A Test File