Add some more user documentation

README.rst

@@ -11,15 +11,18 @@ solutions.
 
 Fortuno provides:
 
+- serial unit testing,
+
+- parallel unit testing for MPI- and coarray-parallel projects,
+
 - simple unit tests,
 
 - fixtured tests,
 
 - parametrized tests,
 
-- serial unit testing,
-
-- parallel unit testing for MPI- and coarray-parallel projects, and
+- automatic test registration (in combination with the `Fypp-preprocessor
+  <https://github.com/aradi/fypp>`_), and
 
 - integration with the `fpm <https://fpm.fortran-lang.org/>`_, `CMake
   <https://cmake.org/>`_ and `Meson <https://mesonbuild.com/>`_ build systems.

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/coarray-fpp/test_simple_fpp.F90

@@ -25,6 +25,10 @@ end function tests
 
 
   !> Broadcast test with collective communication
+  !!
+  !! Note: as coarray parallelism might be implemented via threads, coarray tests must be "pure" and
+  !! use the passed context object to signalize test events.
+  !!
   subroutine test_broadcast(ctx)
     class(context), intent(inout) :: ctx
 
@@ -50,6 +54,10 @@ subroutine test_broadcast(ctx)
     end if
 
     ! THEN each rank must contain source rank's value
+    !
+    ! Note: "CHECK()" and "CHECK_MSG()" calls are collective calls, all images must call them with
+    ! their local result synchronously.
+    !
     CHECK_MSG(ctx, is_equal(buffer, sourceval), msg)
 
   end subroutine test_broadcast

example/coarray-fypp/test_simple_fypp.fypp

@@ -15,6 +15,11 @@ contains
 
 
   !> Broadcast test with collective communication
+  !!
+  !! Note: as coarray parallelism might be implemented via threads, coarray tests must be "pure" and
+  !! use the passed context object to signalize test events. The Fypp macros automaticaly handle
+  !! this (using "ctx" as name for the context instance).
+  !!
   $:TEST("broadcast")
     integer, parameter :: sourceimg = 1, sourceval = 100, otherval = -1
     integer :: buffer
@@ -32,6 +37,10 @@ contains
     call broadcast(buffer, sourceimg)
 
     ! THEN each image must contain source image's value
+    !
+    ! Note: CHECK() and ASSERT() calls are collective calls, all images must call them with their
+    ! local result synchronously.
+    !
     @:CHECK(is_equal(buffer, sourceval), msg=msg)
 
   $:END_TEST()

example/coarray/test_simple.f90

@@ -22,7 +22,11 @@ function tests()
   end function tests
 
 
-  !> Broadcast test with collective communication
+  !> Broadcast test with collective communication.
+  !!
+  !! Note: as coarray parallelism might be implemented via threads, coarray tests must be "pure" and
+  !! use the passed context object to signalize test events.
+  !!
   subroutine test_broadcast(ctx)
     class(context), intent(inout) :: ctx
 
@@ -48,6 +52,10 @@ subroutine test_broadcast(ctx)
     end if
 
     ! THEN each rank must contain source rank's value
+    !
+    ! Note: check() calls are collective calls, all images must call it with their local result
+    ! synchronously.
+    !
     call ctx%check(is_equal(buffer, sourceval), msg=msg)
 
   end subroutine test_broadcast

example/mpi-fpp/test_simple_fpp.F90

@@ -48,6 +48,10 @@ subroutine test_broadcast()
     end if
 
     ! THEN each rank must contain source rank's value
+    !
+    ! Note: "CHECK()" and "CHECK_MSG()" calls are collective calls, all processes must call them
+    ! with their local result synchronously.
+    !
     CHECK_MSG(is_equal(buffer, sourceval), msg)
 
   end subroutine test_broadcast

example/mpi-fypp/test_simple_fypp.fypp

@@ -64,6 +64,9 @@ contains
     ! ASSERT() causes the test code to return immediately, while CHECK() only logs the failure and
     ! continues.
     !
+    ! Also note: CHECK() and ASSERT() calls are collective calls, all processes must call them with
+    ! their local result synchronously.
+    !
     @:ASSERT(is_equal(buffer, sourceval), msg=msg)
 
   $:END_TEST()

example/mpi/test_simple.f90

@@ -46,6 +46,10 @@ subroutine test_broadcast()
     end if
 
     ! THEN each rank must contain source rank's value
+    !
+    ! Note: check() calls are collective calls, all processes must call it with their local result
+    ! synchronously.
+    !
     call check(is_equal(buffer, sourceval), msg=msg)
 
   end subroutine test_broadcast

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(),&