Document X::Control

X::Control got the ability to turn exceptions into control exceptions
in 2019.03. Part of #2673 and also refs #2551.

doc/Language/exceptions.pod6

@@ -385,13 +385,14 @@ printing a backtrace along with the message:
 
 =head1 Control exceptions
 
-Control exceptions are thrown by certain L<keywords|/language/phasers#CONTROL>
-and are handled either automatically or by the appropriate
-L<phaser|/language/phasers#Loop_phasers>. Any unhandled control exception is
-converted to a normal exception.
+Control exceptions are raised when throwing an Exception which does the
+L<X::Control|/type/X::Control> role (since Rakudo 2019.03). They are
+usually thrown by certain L<keywords|/language/phasers#CONTROL> and are
+handled either automatically or by the appropriate L<phaser|/language/phasers#Loop_phasers>.
+Any unhandled control exception is converted to a normal exception.
 
 =begin code
-{ return; CATCH { default { $*ERR.say: .^name, ': ',.Str } } }
+{ return; CATCH { default { $*ERR.say: .^name, ': ', .Str } } }
 # OUTPUT: «X::ControlFlow::Return: Attempt to return outside of any Routine␤»
 # was CX::Return
 =end code

doc/Type/X/Control.pod6

@@ -0,0 +1,38 @@
+=begin pod
+
+=TITLE role X::Control
+
+=SUBTITLE Role for control exceptions
+
+    role X::Control is Exception { }
+
+This role turns an exception into a L<control exception|/language/exceptions#Control_exceptions>,
+like C<CX::Next>, C<CX::Take>, etc.
+
+Since Rakudo 2019.03, C<throw>ing an C<X::Control> object raises a control
+exception which is caught by the L<CONTROL phaser|/language/phasers#CONTROL>
+instead of L<CATCH|/language/phasers#CATCH>. This allows to define custom
+control exceptions.
+
+For example
+
+=begin code
+class CX::Oops does X::Control {
+    has $.message
+}
+
+sub oops ($message = 'oops') {
+    CX::Oops.new(:$message).throw
+}
+
+oops "I messed up!";
+
+CONTROL {
+    default {
+        say "Controlled { .^name }: { .message }"
+    }
+}
+# OUTPUT: «Controlled CX::Oops: I messed up!␤»
+=end code
+
+=end pod