This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
clarify "bless" doc
authorZefram <zefram@fysh.org>
Wed, 6 Dec 2017 17:15:29 +0000 (17:15 +0000)
committerZefram <zefram@fysh.org>
Wed, 6 Dec 2017 17:24:47 +0000 (17:24 +0000)
A couple of points came out of discussion on [perl #124428] that are
worthy of explication.

pod/perlfunc.pod

index 58bfbd4..98cba47 100644 (file)
@@ -893,7 +893,9 @@ X<bless>
 =for Pod::Functions create an object
 
 This function tells the thingy referenced by REF that it is now an object
-in the CLASSNAME package.  If CLASSNAME is omitted, the current package
+in the CLASSNAME package.  If CLASSNAME is an empty string, it is
+interpreted as referring to the C<main> package.
+If CLASSNAME is omitted, the current package
 is used.  Because a L<C<bless>|/bless REF,CLASSNAME> is often the last
 thing in a constructor, it returns the reference for convenience.
 Always use the two-argument version if a derived class might inherit the
@@ -903,8 +905,9 @@ method doing the blessing.  See L<perlobj> for more about the blessing
 Consider always blessing objects in CLASSNAMEs that are mixed case.
 Namespaces with all lowercase names are considered reserved for
 Perl pragmas.  Builtin types have all uppercase names.  To prevent
-confusion, you may wish to avoid such package names as well.  Make sure
-that CLASSNAME is a true value.
+confusion, you may wish to avoid such package names as well.
+It is advised to avoid the class name C<0>, because much code erroneously
+uses the result of L<C<ref>|/ref EXPR> as a truth value.
 
 See L<perlmod/"Perl Modules">.