Revamp fields documentation

• Actually give an example of a typed lexical.
• Also show the syntax parenthetically in the pod, since the phrase
 ‘typed lexical’ is not exactly well known.
• Don’t use dev version numbers.
• Don’t talk about pseudo-hashes so pervasively, as the fact that they
  are used is more an implementation detail now than a feature (except
  for phash).
• If we talk about restricted hashes, we should link to Hash::Util.
• -w is not the only way to turn warnings on.

Also mention in perlfunc that ‘my __PACKAGE__’ and ‘my CONSTANT’ work,
so that the only mentions are not in perl561delta and Lexical::Types.

diff --git a/dist/base/lib/fields.pm b/dist/base/lib/fields.pm
index fd59b6a..ca7a35e 100644 (file)
--- a/dist/base/lib/fields.pm
+++ b/dist/base/lib/fields.pm
@@ -200,9 +200,13 @@ fields - compile-time class fields
     my $var = Foo->new;
     $var->{foo} = 42;
 
-    # this will generate an error
+    # this will generate a run-time error
     $var->{zap} = 42;
 
+    # this will generate a compile-time error
+    my Foo $foo = Foo->new;
+    $foo->{zap} = 24;
+
     # subclassing
     {
         package Bar;
@@ -220,38 +224,34 @@ fields - compile-time class fields
 
 =head1 DESCRIPTION
 
-The C<fields> pragma enables compile-time verified class fields.
+The C<fields> pragma enables compile-time and run-time verified class
+fields.
 
 NOTE: The current implementation keeps the declared fields in the %FIELDS
 hash of the calling package, but this may change in future versions.
 Do B<not> update the %FIELDS hash directly, because it must be created
 at compile-time for it to be fully useful, as is done by this pragma.
 
-B<Only valid for perl before 5.9.0:>
-
-If a typed lexical variable holding a reference is used to access a
+If a typed lexical variable (C<my Class
+$var>) holding a reference is used to access a
 hash element and a package with the same name as the type has
-declared class fields using this pragma, then the operation is
-turned into an array access at compile time.
-
+declared class fields using this pragma, then the hash key is
+verified at compile time.  If the variables are not typed, access is
+only checked at run time.
 
 The related C<base> pragma will combine fields from base classes and any
 fields declared using the C<fields> pragma.  This enables field
-inheritance to work properly.
-
-Field names that start with an underscore character are made private to
-the class and are not visible to subclasses.  Inherited fields can be
-overridden but will generate a warning if used together with the C<-w>
-switch.
-
-B<Only valid for perls before 5.9.0:>
+inheritance to work properly.  Inherited fields can be overridden but
+will generate a warning if warnings are enabled.
 
-The effect of all this is that you can have objects with named
-fields which are as compact and as fast arrays to access. This only
-works as long as the objects are accessed through properly typed
-variables. If the objects are not typed, access is only checked at
-run time.
+B<Only valid for Perl 5.8.x and earlier:> Field names that start with an
+underscore character are made private to the class and are not visible
+to subclasses.
 
+Also, B<in Perl 5.8.x and earlier>, this pragma uses pseudo-hashes, the
+effect being that you can have objects with named fields which are as
+compact and as fast arrays to access, as long as the objects are
+accessed through properly typed variables.
 
 The following functions are supported:
 
@@ -259,15 +259,8 @@ The following functions are supported:
 
 =item new
 
-B< perl before 5.9.0: > fields::new() creates and blesses a
-pseudo-hash comprised of the fields declared using the C<fields>
-pragma into the specified class.
-
-B< perl 5.9.0 and higher: > fields::new() creates and blesses a
-restricted-hash comprised of the fields declared using the C<fields>
-pragma into the specified class.
-
-This function is usable with or without pseudo-hashes.  It is the
+fields::new() creates and blesses a hash comprised of the fields declared
+using the C<fields> pragma into the specified class.  It is the
 recommended way to construct a fields-based object.
 
 This makes it possible to write a constructor like this:
@@ -285,7 +278,11 @@ This makes it possible to write a constructor like this:
 
 =item phash
 
-B< before perl 5.9.0: > 
+B<This function only works in Perl 5.8.x and earlier.>  Pseudo-hashes
+were removed from Perl as of 5.10.  Consider using restricted hashes or
+fields::new() instead (which itself uses restricted hashes under 5.10+).
+See L<Hash::Util>.  Using fields::phash() under 5.10 or higher will
+cause an error.
 
 fields::phash() can be used to create and initialize a plain (unblessed)
 pseudo-hash.  This function should always be used instead of creating
@@ -312,16 +309,10 @@ be used to construct the pseudo hash.  Examples:
 
     my $pseudohash = fields::phash(%args);
 
-B< perl 5.9.0 and higher: >
-
-Pseudo-hashes have been removed from Perl as of 5.10.  Consider using
-restricted hashes or fields::new() instead.  Using fields::phash()
-will cause an error.
-
 =back
 
 =head1 SEE ALSO
 
-L<base>
+L<base>, L<Hash::Util>
 
 =cut

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 38a5555..c8124f1 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3778,7 +3778,9 @@ enclosing block, file, or C<eval>.  If more than one variable is listed,
 the list must be placed in parentheses.
 
 The exact semantics and interface of TYPE and ATTRS are still
-evolving.  TYPE is currently bound to the use of the C<fields> pragma,
+evolving.  TYPE may be a bareword, a constant declared
+with C<use constant>, or C<__PACKAGE__>.  It is
+currently bound to the use of the 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>,