--- a/doc/interpreter/testfun.txi
+++ b/doc/interpreter/testfun.txi
@@ -267,6 +267,45 @@
 @end group
 @end example
 
+@noindent
+The following trivial code snippet provides examples for the use of
+fail, assert, error and xtest:
+
+@example
+@group
+function output = must_be_zero (@var{input})
+  if (@var{input} != 0)
+    error ("Non-zero input!")
+  endif
+  output = input;
+endfunction
+
+%!fail ("must_be_zero (1)");
+%!assert (must_be_zero (0), 0);
+%!error <Non-zero> must_be_zero (1);
+%!xtest error ("This code generates an error");
+@end group
+@end example
+
+@noindent
+When putting this a file @file{must_be_zero.m}, and running the test, we see
+
+@example
+@group
+test must_be_zero verbose
+
+@result{}
+>>>>> /path/to/must_be_zero.m
+  ***** fail ("must_be_zero (1)");
+  ***** assert (must_be_zero (0), 0);
+  ***** error <Non-zero> must_be_zero (1);
+  ***** xtest error ("This code generates an error");
+!!!!! known failure
+This code generates an error
+PASSES 4 out of 4 tests (1 expected failures)
+@end group
+@end example
+
 @subsubheading Block type summary:
 
 @table @code

--- a/scripts/testfun/fail.m
+++ b/scripts/testfun/fail.m
@@ -29,10 +29,19 @@
 ## is a string and if @var{code} runs successfully, the error produced is:
 ##
 ## @example
-##           expected error but got none
+##           expected error <.> but got none
 ## @end example
 ##
-## If the code fails with a different error, the message produced is:
+##
+## Code must be in the form of a string that may be passed by
+## @code{fail} to the Octave interpreter via the @code{evalin} function,
+## that is, a (quoted) string constant or a string variable.
+##
+## If called with two arguments, the behavior is similar to
+## @code{fail (@var{code})}, except the return value will only be true if
+## code fails with an error message containing pattern (case sensitive).
+## If the code fails with a different error to that given in pattern,
+## the message produced is:
 ##
 ## @example
 ## @group