document return values of do() better

	Message-Id: <E0z18BI-0003cH-00@taurus.cus.cam.ac.uk>
	Subject: [PATCH] Re: Obscurity of lexicals with do ""

p4raw-id: //depot/maint-5.005/perl@1683

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 35cab3a..69dd5aa 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -915,6 +915,12 @@ scope like 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.
+
 Note that inclusion of library modules is better done with the
 C<use()> and C<require()> operators, which also do automatic error checking
 and raise an exception if there's a problem.