From b3e0c1d99f494408fe18ee051078ca76b5c5afb8 Mon Sep 17 00:00:00 2001
From: Elizabeth Mattijsen <liz@raku.rocks>
Date: Tue, 7 Mar 2023 14:07:09 +0100
Subject: [PATCH] Document Exception|Cool.Failure coercer

---
 doc/Type/Cool.rakudoc      | 11 +++++++++++
 doc/Type/Exception.rakudoc |  8 ++++++++
 2 files changed, 19 insertions(+)

diff --git a/doc/Type/Cool.rakudoc b/doc/Type/Cool.rakudoc
index 032add958..edacdf663 100644
--- a/doc/Type/Cool.rakudoc
+++ b/doc/Type/Cool.rakudoc
@@ -1448,4 +1448,15 @@ had been coerced to is negative.
     say (-4/3).UInt.^name;    # OUTPUT: «Failure␤»
     say "foo".UInt.^name;     # OUTPUT: «Failure␤»
 
+=head2 method Failure
+
+    method Failure(Exception:D --> Failure:D)
+
+Available as of the 2022.06 release of the Rakudo compiler.
+
+Creates an C<X::AdHoc> exception with the stringification of the
+invocant, and coerces that into a L<Failure|/type/Failure> object.
+Mainly intended to reduce the bytecode for error branches in code,
+to increase the chances of hot code getting inlined.
+
 =end pod
diff --git a/doc/Type/Exception.rakudoc b/doc/Type/Exception.rakudoc
index 33a4fddfd..a6ac47ab3 100644
--- a/doc/Type/Exception.rakudoc
+++ b/doc/Type/Exception.rakudoc
@@ -121,6 +121,14 @@ a newline.
     # OUTPUT: «This exception is pretty bad
     #   in block <unit> at <unknown file> line 1␤»
 
+=head2 method Failure
+
+    method Failure(Exception:D --> Failure:D)
+
+Available as of the 2022.06 release of the Rakudo compiler.
+
+Coerces the C<Exception> into a L<Failure|/type/Failure> object.
+
 =head2 routine die
 
     multi sub die()