bug#75041: [PATCH] doc/srfi-64: Fix typos and add examples.

bug#75041: [PATCH] doc/srfi-64: Fix typos and add examples.

[Maxim Cournoyer]

* doc/ref/srfi-modules.texi (SRFI-64 Writing Basic Test Suites): Fix
typo.  Add default test runner example.  Add test-approximate and
test-error examples.  Document valid error types in Guile for test-error.
(SRFI-64 Conditonal Test Suites and Other Advanced Features): Fix typo.

Suggested-by: Arne Babenhauserheide <arne_bab@web.de>
---
 doc/ref/srfi-modules.texi | 83 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 80 insertions(+), 3 deletions(-)

diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
index d77bc1c90..537ec9059 100644
--- a/doc/ref/srfi-modules.texi
+++ b/doc/ref/srfi-modules.texi
@@ -5387,13 +5387,31 @@ is also easy to add new tests, without having to name individual tests
 (though that is optional).
 
 Test cases are executed in the context of a @dfn{test runner}, which is
-a object that accumulates and reports test results.  This specification
+an object that accumulates and reports test results.  This specification
 defines how to create and use custom test runners, but implementations
 should also provide a default test runner.  It is suggested (but not
 required) that loading the above file in a top-level environment will
 cause the tests to be executed using an implementation-specified default
 test runner, and @code{test-end} will cause a summary to be displayed in
-an implementation-specified manner.
+an implementation-specified manner.  The SRFI 64 implementation used in
+Guile provides such a default test runner; running the above snippet at
+the REPL prints:
+
+@example
+*** Entering test group: vec-test ***
+$1 = #t
+* PASS:
+$2 = ((pass . 1))
+* PASS:
+$3 = ((pass . 2))
+* PASS:
+$4 = ((pass . 3))
+*** Leaving test group: vec-test ***
+*** Test suite finished. ***
+*** # of expected passes    : 3
+@end example
+
+It also returns the @code{<test-runner>} object.
 
 @subsubheading Simple test-cases
 
@@ -5455,6 +5473,14 @@ once):
   (and (>= test-expr (- expected error))
        (<= test-expr (+ expected error))))
 @end lisp
+
+Here's an example:
+@lisp
+(test-approximate "is 22/7 within 1% of π?"
+ 3.1415926535
+ 22/7
+ 1/100)
+@end lisp
 @end deffn
 
 @subsubheading Tests for catching errors
@@ -5492,8 +5518,59 @@ classes:
 
 An implementation that cannot catch exceptions should skip
 @code{test-error} forms.
+
+@cindex test-error error types
+@cindex error types, test-error, srfi-64
+The SRFI-64 implementation in Guile supports specifying @var{error-type}
+as either:
+@iterate
+@item
+@code{#f}, meaning the test is @emph{not} expected to produce an error
+@item
+@code{#t}, meaning the test is expected to produce an error, of any type
+@item
+A native exception type, as created via @code{make-exception-type} or
+@code{make-condition-type} from SRFI-35
+@item
+A predicate, which will be applied to the exception caught
+to determine whether is it of the right type
+@item
+A symbol, for the exception kind of legacy
+@code{make-exception-from-throw} style exceptions.
 @end deffn
 
+Below are some examples valid in Guile:
+
+@lisp
+(test-error "expect old-style exception kind"
+ 'numerical-overflow
+ (/ 1 0))
+@end lisp
+
+@lisp
+(use-modules (ice-9 exceptions)) ;for standard exception types
+
+(test-error "expect a native exception type"
+ &warning
+ (raise-exception (make-warning)))
+
+(test-error "expect a native exception, using predicate"
+ warning?
+ (raise-exception (make-warning)))
+@end lisp
+
+@lisp
+(use-modules (srfi srfi-35))
+
+(test-error "expect a serious SRFI 35 condition type"
+ &serious
+ (raise-exception (condition (&serious))))
+
+(test-error "expect a serious SRFI 35 condition type, using predicate"
+ serious-condition?
+ (raise-exception (condition (&serious))))
+@end lisp
+
 @subsubheading Testing syntax
 
 Testing syntax is tricky, especially if we want to check that invalid
@@ -5617,7 +5694,7 @@ or specifying that some tests are @emph{expected} to fail.
 @subsubheading Test specifiers
 
 Sometimes we want to only run certain tests, or we know that certain
-tests are expected to fail.  A @dfn{test specifier} is one-argument
+tests are expected to fail.  A @dfn{test specifier} is a one-argument
 function that takes a test-runner and returns a boolean.  The specifier
 may be run before a test is performed, and the result may control
 whether the test is executed.  For convenience, a specifier may also be

base-commit: f6359a4715d023761454f1bf945633ce4cca98fc
-- 
2.46.0