Document that caller() does not see try{} blocks

2 files changed, 12 insertions, 0 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 674866671a..6ce02b081e 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -989,6 +989,11 @@ L<C<undef>|/undef EXPR> if L<C<%^H>|perlvar/%^H> was empty.  Do not
 modify the values of this hash, as they are the actual values stored in
 the optree.
 
+Note that the only types of call frames that are visible are subroutine
+calls and C<eval>. Other forms of context, such as C<while> or C<foreach>
+loops or C<try> blocks are not considered interesting to C<caller>, as they
+do not alter the behaviour of the C<return> expression.
+
 Furthermore, when called from within the DB package in
 list context, and with an argument, caller returns more
 detailed information: it sets the list variable C<@DB::args> to be the
diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index f6067037dc..fe511f052e 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -666,6 +666,13 @@ containing function to return.
         }
     };
 
+As with other control-flow syntax, C<try> blocks are not visible to
+C<caller()> (just as for example, C<while> or C<foreach> loops are not).
+Successive levels of the C<caller> result can see subroutine calls and
+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>.
+
 This syntax is currently experimental and must be enabled with
 C<use feature 'try'>. It emits a warning in the C<experimental::try> category.