Recommend Against UNIVERSAL:: Methods as Functions, take 2

Message-Id: <1119122141.21521.9.camel@localhost>

p4raw-id: //depot/perl@24909

1 files changed, 13 insertions, 24 deletions

diff --git a/pod/perlobj.pod b/pod/perlobj.pod
index 891ebe37f2..f427de7cde 100644
--- a/pod/perlobj.pod
+++ b/pod/perlobj.pod
@@ -373,18 +373,19 @@ are inherited by all other classes:
 
 C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS>
 
-You can also call C<UNIVERSAL::isa> as a subroutine with two arguments.
-The first does not need to be an object or even a reference.  This
-allows you to check what a reference points to, or whether
-something is a reference of a given type. Example
+You can also call C<UNIVERSAL::isa> as a subroutine with two arguments.  Of
+course, this will do the wrong thing if someone has overridden C<isa> in a
+class, so don't do it.
 
-    if(UNIVERSAL::isa($ref, 'ARRAY')) {
-    	#...
-    }
+If you need to determine whether you've received a valid invocant, use the
+C<blessed> function from L<Scalar::Util>:
 
-To determine if a reference is a blessed object, you can write
+    if (blessed($ref) && $ref->isa( 'Some::Class')) {
+        # ...
+    }
 
-    print "It's an object\n" if UNIVERSAL::isa($val, 'UNIVERSAL');
+C<blessed> returns the name of the package the argument has been
+blessed into, or C<undef>.
 
 =item can(METHOD)
 
@@ -392,21 +393,9 @@ C<can> checks to see if its object has a method called C<METHOD>,
 if it does then a reference to the sub is returned, if it does not then
 I<undef> is returned.
 
-C<UNIVERSAL::can> can also be called as a subroutine with two arguments.
-It'll always return I<undef> if its first argument isn't an object or a
-class name.    So here's another way to check if a reference is a
-blessed object
-
-    print "It's still an object\n" if UNIVERSAL::can($val, 'can');
-
-You can also use the C<blessed> function of Scalar::Util:
-
-    use Scalar::Util 'blessed';
-
-    my $blessing = blessed $suspected_object;
-
-C<blessed> returns the name of the package the argument has been
-blessed into, or C<undef>.
+C<UNIVERSAL::can> can also be called as a subroutine with two arguments.  It'll
+always return I<undef> if its first argument isn't an object or a class name.
+The same caveats for calling C<UNIVERSAL::isa> directly apply here, too.
 
 =item VERSION( [NEED] )