Better docs on capturing success with catch block

While there is a note that calls it out below, I believe the behavior and usage of capturing success when also using a catch{} block is sufficiently different to the example that it merits its own example in the same code block. My rationale is twofold:

1) Because it is sufficiently different in behavior, giving an example goes a long way towards understanding.
2) Because this is a critical feature to have fail and it might be easy for someone reading the docs to digest the example and move on before reading the note below (which is unemphasized), it is best to have the second code example alongside the first with a meaningful name so that they are both digested at the same time.

diff --git a/lib/Try/Tiny.pm b/lib/Try/Tiny.pm
index f97e9f7..588451c 100644 (file)
--- a/lib/Try/Tiny.pm
+++ b/lib/Try/Tiny.pm
@@ -500,6 +500,19 @@ Instead, you should capture the return value:
 
     say "This text WILL NEVER appear!";
   }
+  
+  # or
+  
+  sub parent_sub_with_catch {
+    my $success = try {
+      die;
+      1;
+    }
+    catch {
+      # do something with $_
+      return undef; #see note
+    };
+  }
 
 Note that if you have a C<catch> block, it must return C<undef> for this to work,
 since if a C<catch> block exists, its return value is returned in place of C<undef>