perlfunc: clarified 'do FILE' error checking

Partial fix for RT #80626

2 files changed, 16 insertions, 5 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 5151965773..2ac1a3ed36 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -388,6 +388,17 @@ XXX Changes which significantly change existing files in F<pod/> go here.
 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
 section.
 
+=head3 L<perlfunc>
+
+=over 4
+
+=item *
+
+Clarified the order in which to check C<$@> and C<$!> after C<do FILE>.
+(RT #80626)
+
+=back
+
 =head3 L<XXX>
 
 =over 4
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 0185762d79..0d9a65cbec 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1419,11 +1419,11 @@ cannot see lexicals in the enclosing scope; C<eval STRING> does.  It's the
 same, however, in that it does reparse the file every time you call it,
 so you probably don't want to do this inside a loop.
 
-If C<do> cannot read the file, it returns undef and sets C<$!> to the
-error.  If C<do> can read the file but cannot compile it, it
-returns undef and sets an error message in C<$@>.   If the file is
-successfully compiled, C<do> returns the value of the last expression
-evaluated.
+If C<do> can read the file but cannot compile it, it returns undef and sets
+an error message in C<$@>.  If C<do> cannot read the file, it returns undef
+and sets C<$!> to the error.  Always check C<$@> first, as compilation
+could fail in a way that also sets C<$!>.  If the file is successfully
+compiled, C<do> returns the value of the last expression evaluated.
 
 Inclusion of library modules is better done with the
 C<use> and C<require> operators, which also do automatic error checking