document Failure

lib/Failure.pod

@@ -0,0 +1,50 @@
+=begin pod
+
+=TITLE class Failure
+
+    class Failure { }
+
+A C<Failure> is a I<soft> or I<unthrown> exception, usually generated by
+calling C<&fail>. It acts as a wrapper around an L<Exception> object.
+
+Sink (void) context causes a Failure to throw, i.e. turn into a normal
+exception.
+
+Checking a Failure for truth (with the C<Bool> method) or definedness (with
+the C<defined> method) marks the failure as handled, and causes it not to
+throw in sink context anymore.
+
+You can call the C<handled> method to check if a failure has been handled.
+
+Calling methods on unhandled failures propagates the failure. The
+specification says the result is another C<Failure>, in Rakudo it causes the
+failure to throw.
+
+=head1 Methods
+
+=head2 handled
+
+    method handled(Failure:D:) returns Bool:D
+
+Returns C<True> for handled failures, C<False> otherwise.
+
+=head2 exception
+
+    method handled(Failure:D:) returns Exception
+
+Returns the L<Exception> object that the failure wraps.
+
+=head2 Bool
+
+    multi method Bool(Failure:D:) returns Bool:D
+
+Returns C<False>, and marks the failure as handled.
+
+=head2 defined
+
+    multi method defined(Failure:D:) returns Bool:D
+
+Returns C<False> (failures are officially undefined), and marks
+the failure as handled.
+
+=end pod