Cleanup PerlIO::scalar documentation a bit.

p4raw-id: //depot/perl@21067

diff --git a/ext/PerlIO/scalar/scalar.pm b/ext/PerlIO/scalar/scalar.pm
index b5ea957..1c4fa45 100644 (file)
--- a/ext/PerlIO/scalar/scalar.pm
+++ b/ext/PerlIO/scalar/scalar.pm
@@ -7,26 +7,35 @@ __END__
 
 =head1 NAME
 
-PerlIO::scalar - support module for in-memory IO.
+PerlIO::scalar - in-memory IO, scalar IO
 
 =head1 SYNOPSIS
 
-   open($fh,"<",\$scalar);
-   open($fh,">",\$scalar);
+   my $scalar = '';
+   ...
+   open my $fh, "<",  \$scalar or die;
+   open my $fh, ">",  \$scalar or die;
+   open my $fh, ">>", \$scalar or die;
 
 or
 
-   open($fh,"<:scalar",\$scalar);
-   open($fh,">:scalar",\$scalar);
+   my $scalar = '';
+   ...
+   open my $fh, "<:scalar",  \$scalar or die;
+   open my $fh, ">:scalar",  \$scalar or die;
+   open my $fh, ">>:scalar", \$scalar or die;
 
 =head1 DESCRIPTION
 
-C<PerlIO::scalar> only exists to use XSLoader to load C code that provides
-support for treating a scalar as an "in memory" file.
+A filehandle is opened but the file operations are performed "in-memory"
+on a scalar variable.  All the normal file operations can be performed
+on the handle. The scalar is considered a stream of bytes.  Currently
+fileno($fh) returns C<undef>.
 
-All normal file operations can be performed on the handle. The scalar
-is considered a stream of bytes. Currently fileno($fh) returns C<undef>.
-
-=cut
+=head1 IMPLEMENTATION NOTE
 
+C<PerlIO::scalar> only exists to use XSLoader to load C code that
+provides support for treating a scalar as an "in memory" file.
+One does not need to explicitly C<use PerlIO::scalar>.
 
+=cut