One more pass on the TYPE/ATTRS issues.

p4raw-id: //depot/perl@17219

diff --git a/lib/attributes.pm b/lib/attributes.pm
index 8b18b06..2dacd02 100644 (file)
--- a/lib/attributes.pm
+++ b/lib/attributes.pm
@@ -129,9 +129,9 @@ The second example in the synopsis does something equivalent to this:
 
 Yes, that's a lot of expansion.
 
-B<WARNING>: attribute declarations for variables are an I<experimental>
-feature.  The semantics of such declarations could change or be removed
-in future versions.  They are present for purposes of experimentation
+B<WARNING>: attribute declarations for variables are still evolving.
+The semantics and interfaces of such declarations could change in
+future versions.  They are present for purposes of experimentation
 with what the semantics ought to be.  Do not rely on the current
 implementation of this feature.
 
@@ -151,12 +151,11 @@ before those attributes will get applied.  For example:
 will neither assign 42 to $x I<nor> will it apply the C<Bent> attribute
 to the variable.
 
-An attempt to set
-an unrecognized attribute is a fatal error.  (The error is trappable, but
-it still stops the compilation within that C<eval>.)  Setting an attribute
-with a name that's all lowercase letters that's not a built-in attribute
-(such as "foo")
-will result in a warning with B<-w> or C<use warnings 'reserved'>.
+An attempt to set an unrecognized attribute is a fatal error.  (The
+error is trappable, but it still stops the compilation within that
+C<eval>.)  Setting an attribute with a name that's all lowercase
+letters that's not a built-in attribute (such as "foo") will result in
+a warning with B<-w> or C<use warnings 'reserved'>.
 
 =head2 Built-in Attributes
 

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 10120ed..e858b26 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2628,16 +2628,16 @@ and C<IPC::SysV::Msg> documentation.
 
 =item my TYPE EXPR
 
-=item my EXPR : ATTRIBUTES
+=item my EXPR : ATTRS
 
-=item my TYPE EXPR : ATTRIBUTES
+=item my TYPE EXPR : ATTRS
 
 A C<my> declares the listed variables to be local (lexically) to the
-enclosing block, file, or C<eval>.  If
-more than one value is listed, the list must be placed in parentheses.
+enclosing block, file, or C<eval>.  If more than one value is listed,
+the list must be placed in parentheses.
 
-The use of TYPE and ATTRIBUTES is considered experimental and subject
-to change.  TYPE is currently bound to the use of C<fields> pragma,
+The exact semantics and interface of TYPE and ATTRS are still
+evolving.  TYPE is currently bound to the use of C<fields> pragma,
 and attributes are handled using the C<attributes> pragma, or starting
 from Perl 5.8.0 also via the C<Attribute::Handlers> module.  See
 L<perlsub/"Private Variables via my()"> for details, and L<fields>,
@@ -3070,9 +3070,9 @@ See L<perlunicode> and L<encoding> for more about Unicode.
 
 =item our EXPR TYPE
 
-=item our EXPR : ATTRIBUTES
+=item our EXPR : ATTRS
 
-=item our TYPE EXPR : ATTRIBUTES
+=item our TYPE EXPR : ATTRS
 
 An C<our> declares the listed variables to be valid globals within
 the enclosing block, file, or C<eval>.  That is, it has the same
@@ -3115,8 +3115,8 @@ package, Perl will emit warnings if you have asked for them.
 An C<our> declaration may also have a list of attributes associated
 with it.
 
-The use of TYPE and ATTRIBUTES is considered experimental and subject
-to change.  TYPE is currently bound to the use of C<fields> pragma,
+The exact semantics and interface of TYPE and ATTRS are still
+evolving.  TYPE is currently bound to the use of C<fields> pragma,
 and attributes are handled using the C<attributes> pragma, or starting
 from Perl 5.8.0 also via the C<Attribute::Handlers> module.  See
 L<perlsub/"Private Variables via my()"> for details, and L<fields>,
@@ -5218,17 +5218,22 @@ out the names of those files that contain a match:
        print $file, "\n";
     }
 
-=item sub BLOCK
+=item sub NAME BLOCK
 
-=item sub NAME
+=item sub NAME (PROTO) BLOCK
 
-=item sub NAME BLOCK
+=item sub NAME : ATTRS BLOCK
+
+=item sub NAME (PROTO) : ATTRS BLOCK
+
+This is subroutine definition, not a real function I<per se>.
+Without a BLOCK it's just a forward declaration.  Without a NAME,
+it's an anonymous function declaration, and does actually return
+a value: the CODE ref of the closure you just created.
 
-This is subroutine definition, not a real function I<per se>.  With just a
-NAME (and possibly prototypes or attributes), it's just a forward declaration.
-Without a NAME, it's an anonymous function declaration, and does actually
-return a value: the CODE ref of the closure you just created.  See L<perlsub>
-and L<perlref> for details.
+See L<perlsub> and L<perlref> for details about subroutines and
+references, and L<attributes> and L<Attributed::Handlers> for more
+information about attributes.
 
 =item substr EXPR,OFFSET,LENGTH,REPLACEMENT