improve Testament docs (#15881)

* fix mentions of recursive test discovery

* document that {.fatal.} pragmas cannot be caught

1 files changed, 6 insertions, 4 deletions

diff --git a/doc/testament.rst b/doc/testament.rst
index 18501f4cd..09c248d1f 100644
--- a/doc/testament.rst
+++ b/doc/testament.rst
@@ -58,12 +58,12 @@ Running all tests from a directory
 
   $ testament pattern "tests/*.nim"
 
-To recursively search for all tests in a directory, use
+To search for tests deeper in a directory, use
 
 .. code::
 
-  $ testament pattern "tests/**/*.nim"
-
+  $ testament pattern "tests/**/*.nim"    # one level deeper
+  $ testament pattern "tests/**/**/*.nim" # two levels deeper
 
 HTML Reports
 ============
@@ -89,7 +89,9 @@ Example "template" **to edit** and write a Testament unittest:
     # Options:
     #   "compile": expect successful compilation
     #   "run": expect successful compilation and execution
-    #   "reject": expect failed compilation
+    #   "reject": expect failed compilation. The "reject" action can catch
+    #             {.error.} pragmas but not {.fatal.} pragmas because
+    #             {.fatal.} pragmas guarantee that compilation will be aborted.
     action: "run"
 
     # The exit code that the test is expected to return. Typically, the default