Add some more user documentation

example/README.rst

@@ -0,0 +1,46 @@
+****************
+Fortuno examples
+****************
+
+Documented examples demonstrating the usage of the Fortuno unit testing
+framework for various test scenarios.
+
+**Serial unit tests**
+
+- `serial <serial>`_: Unit tests in pure Fortran.
+
+- `serial-fpp <serial-fpp>`_: Unit tests utilizing fpp-style macros (which are
+  natively understood by basically all Fortran compilers). Allows for
+  automatically added file and line information when reporting failure.
+
+- `serial-fypp <serial-fypp>`_: Unit tests utilizing Fypp macros (helpful if
+  your project uses the Fypp-preprocessor). Allows for automatic test
+  registration as well as for automatic file and line information when reporting
+  failure.
+
+
+**MPI-parallel unit tests**
+
+- `mpi <mpi>`_: Unit tests in pure Fortran.
+
+- `mpi-fpp <mpi-fpp>`_: Unit tests utilizing fpp-style macros (which are
+  natively understood by basically all Fortran compilers). Allows for
+  automatically added file and line information when reporting failure.
+
+- `mpi-fypp <mpi-fypp>`_: Unit tests utilizing Fypp macros (helpful if your
+  project uses the Fypp-preprocessor). Allows for automatic test registration as
+  well as for automatic file and line information when reporting failure.
+
+
+**Coarray-parallel unit tests**
+
+- `coarray <coarray>`_: Unit tests in pure Fortran.
+
+- `coarray-fpp <coarray-fpp>`_: Unit tests utilizing fpp-style macros (which are
+  natively understood by basically all Fortran compilers). Allows for
+  automatically added file and line information when reporting failure.
+
+- `coarray-fypp <coarray-fypp>`_: Unit tests utilizing Fypp macros (helpful if
+  your project uses the Fypp-preprocessor). Allows for automatic test
+  registration as well as for automatic file and line information when reporting
+  failure.

example/serial/test_fixtured.f90

@@ -5,9 +5,9 @@
 !> Demo for realizing fixtured tests by overriding the run() method of the test_case object.
 module test_fixtured
   use mylib, only : factorial
-  use fortuno_serial, only : check => serial_check, is_equal, state_dict,&
-      & dict_item, suite => serial_suite_item, store_state => serial_store_state,&
-      & serial_case_base, test_item, test_list
+  use fortuno_serial, only : check => serial_check, is_equal, state_dict, dict_item,&
+      & suite => serial_suite_item, store_state => serial_store_state, serial_case_base,&
+      & test_item, test_list
   implicit none
 
   private
@@ -17,7 +17,7 @@ module test_fixtured
   ! Fixtured test case creating a random number before running a test procedure.
   type, extends(serial_case_base) :: random_test_case
 
-  ! Test procedure to be called after fixture setup had finished.
+    ! Test procedure to be called after fixture setup had finished.
     procedure(test_recursion_down), pointer, nopass :: proc
 
   contains

example/serial/test_simple.f90

@@ -21,7 +21,8 @@ function tests()
 
     tests = test_list([&
         ! Best practice is to create at least one suite with the name of the module and put the
-        ! tests in it, like below. You might further structure your test sets by nesting suites...
+        ! tests in it, like below. You might further structure your test sets by nesting further
+        ! suites into the top level one.
         suite("simple", test_list([&
             test("factorial_0", test_factorial_0),&
             test("factorial_1", test_factorial_1),&
@@ -47,11 +48,13 @@ end subroutine test_factorial_1
 
   ! Test: 2! = 2 (will fail due to the bug in the implementation of the factorial function)
   subroutine test_factorial_2()
-    ! Two failing checks, you should see info about both in the output
+    ! Both check will fail, you should see info about both in the output
+    ! The file and line information are provided manually. Check the examples in the fpp example
+    ! folders for automatic file name and line number generation.
     call check(is_equal(factorial(2), 2),&
         & msg="Test failed for demonstration purposes",&
         & file="test_simple.f90",&
-        & line=43)
+        & line=51)
     call check(factorial(2) == 2)
   end subroutine test_factorial_2
 

example/serial/testapp.f90

@@ -11,6 +11,9 @@ program testapp
   use test_fixtured_suite, only : fixtured_suite_tests => tests
   implicit none
 
+  ! Creating and executing a command line app with the tests to be included.
+  ! Note: this function does not return but stops the code with the right exit code.
+  ! (0 on success, non-zero otherwise)
   call execute_serial_cmd_app(test_list([&
       simple_tests(),&
       parametrized_tests(),&