Document the new try/catch/finally syntax

1 files changed, 26 insertions, 1 deletions

diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index 627c9647f4..463ababa2d 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -294,6 +294,7 @@ a list of lexicals within parentheses:
 If enabled by the experimental C<try> feature, the following may also be used
 
     try BLOCK catch (VAR) BLOCK
+    try BLOCK catch (VAR) BLOCK finally BLOCK
 
 The experimental C<given> statement is I<not automatically enabled>; see
 L</"Switch Statements"> below for how to do so, and the attendant caveats.
@@ -649,7 +650,7 @@ return value of a C<for> loop is unspecified and may change without notice.
 Do not rely on it.
 
 =head2 Try Catch Exception Handling
-X<try> X<catch>
+X<try> X<catch> X<finally>
 
 The C<try>/C<catch> syntax provides control flow relating to exception
 handling. The C<try> keyword introduces a block which will be executed when it
@@ -711,6 +712,30 @@ C<eval> blocks, because those affect the way that C<return> would work. Since
 C<try> blocks do not intercept C<return>, they are not of interest to
 C<caller>.
 
+The C<try> and C<catch> blocks may optionally be followed by a third block
+introduced by the C<finally> keyword. This third block is executed after the
+rest of the construct has finished.
+
+    try {
+        call_a_function();
+    }
+    catch ($e) {
+        warn "Unable to call; $e";
+    }
+    finally {
+        print "Finished\n";
+    }
+
+The C<finally> block is equivalent to using a C<defer> block and will be
+invoked in the same situations; whether the C<try> block completes
+successfully, throws an exception, or transfers control elsewhere by using
+C<return>, a loop control, or C<goto>.
+
+Unlike the C<try> and C<catch> blocks, a C<finally> block is not permitted to
+C<return>, C<goto> or use any loop controls. The final expression value is
+ignored, and does not affect the return value of the containing function even
+if it is placed last in the function.
+
 This syntax is currently experimental and must be enabled with
 C<use feature 'try'>. It emits a warning in the C<experimental::try> category.