Document all the return values that code references in @INC can return.

p4raw-id: //depot/perl@27879

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index da46ec9..e32bc96 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -4534,12 +4534,42 @@ Subroutine references are the simplest case.  When the inclusion system
 walks through @INC and encounters a subroutine, this subroutine gets
 called with two parameters, the first being a reference to itself, and the
 second the name of the file to be included (e.g. "F<Foo/Bar.pm>").  The
-subroutine should return C<undef> or a filehandle, from which the file to
-include will be read.  If C<undef> is returned, C<require> will look at
-the remaining elements of @INC.  Note that a tied file handle must be a
-real file handle (strictly a typeglob, or reference to a typeglob, blessed or
-unblessed) - tied file handles will be ignored and treated as a return of
-C<undef>.
+subroutine should return nothing, or a list of up to 4 values in the
+following order:
+
+=over
+
+=item 1
+
+A reference to a scalar, containing any initial source code to prepend to
+the file or generator output.
+
+
+=item 2
+
+A filehandle, from which the file will be read.  
+
+=item 3
+
+A reference to a subroutine. If there is no file handle, then this subroutine
+is expected to generate one line of source code per call, writing the line
+into C<$_> and returning 1, then returning 0 at "end of FILE" If there is a
+file handle then the subroutine will be called to act a simple source filter,
+with the line as read in C<$_>. Again, return 1 for each valid line, and 0
+after all lines have been returned.
+
+=item 4
+
+Optional state for the subroutine. The state is passed in as C<$_[1]>. A
+reference to the subroutine itself is passed in as C<$_[0]>.
+
+=back
+
+If an empty list, C<undef>, or nothing that matches the first 3 values above
+is returned then C<require> will look at the remaining elements of @INC.
+Note that a tied file handle must be a real file handle (strictly a typeglob,
+or reference to a typeglob, blessed or unblessed) - tied file handles will be
+ignored and return value processing will stop there.
 
 If the hook is an array reference, its first element must be a subroutine
 reference.  This subroutine is called as above, but the first parameter is