Documents Exception.fail closes #3383

Author: JJ

doc/Type/Exception.pod6

@@ -94,43 +94,30 @@ backtrace.
 
 Defined as:
 
-    multi sub    fail(*@text)
     multi sub    fail(Exception $e)
-    method fail(Exception:D:)
+    method       fail(Exception:D:)
 
 Exits the calling C<Routine> and returns a L<Failure|/type/Failure> object wrapping the
-exception C<$e> - or, for the C<*@text> form, an L<X::AdHoc|/type/X::AdHoc> exception
-constructed from the concatenation of C<@text>. If the caller
-activated fatal exceptions via the pragma C<use fatal;>, the exception is
-thrown instead of being returned as a C<Failure>.
+exception.
 
+=begin code
+# A custom exception defined
+class ForbiddenWord is Exception {
+    has Str $.word;
+    method message { "This word is forbidden: «$!word»" }
+}
+
+sub say-word ( $word ) {
+    ForbiddenWord.new(:word($word)).fail if $word eq 'foo';
+    $word.say;
+}
+
+my $result = say-word("foo");
+say $result.exception;
+=end code
 
-    # A custom exception defined
-    class ForbiddenDirectory is Exception {
-        has Str $.name;
-
-        method message { "This directory is forbidden: '$!name'" }
-    }
-
-    sub copy-directory-tree ($dir) {
-        # We don't allow for non-directories to be copied
-        fail "$dir is not a directory" if !$dir.IO.d;
-        # We don't allow 'foo' directory to be copied too
-        fail ForbiddenDirectory.new(:name($dir)) if $dir eq 'foo';
-        # or above can be written in method form as:
-        # ForbiddenDirectory.new(:name($dir)).fail if $dir eq 'foo';
-        # Do some actual copying here
-        ...
-    }
-
-    # A Failure with X::AdHoc exception object is returned and
-    # assigned, so no throwing Would be thrown without an assignment
-    my $result = copy-directory-tree("cat.jpg");
-    say $result.exception; # OUTPUT: «cat.jpg is not a directory␤»
-
-    # A Failure with a custom Exception object is returned
-    $result = copy-directory-tree('foo');
-    say $result.exception; # OUTPUT: «This directory is forbidden: 'foo'␤»
+The routine form works in the same way, with an alternative syntax:
+C<fail ForbiddenWord.new(:word($word))>.
 
 =head2 method gist