From: Ricardo SIGNES <rjbs@cpan.org>
Date: Mon, 26 Jan 2009 14:53:51 +0000 (-0500)
Subject: pare down docs of UNIVERSAL in perlobj
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=003db2bd2e42353866adbc9b4f1ad5f829a2b43b;p=p5sagit%2Fp5-mst-13.2.git

pare down docs of UNIVERSAL in perlobj
---

diff --git a/lib/UNIVERSAL.pm b/lib/UNIVERSAL.pm
index 6c75665..1adef7a 100644
--- a/lib/UNIVERSAL.pm
+++ b/lib/UNIVERSAL.pm
@@ -68,7 +68,7 @@ is a package name
 
 =item C<$obj>
 
-is a blessed reference or a string containing a package name
+is a blessed reference or a package name
 
 =item C<CLASS>
 
@@ -154,6 +154,14 @@ You may call C<can> as a class (static) method or an object method.
 Again, the same rule about having a valid invocant applies -- use an C<eval>
 block or C<blessed> if you need to be extra paranoid.
 
+B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and
+C<isa> uses a very similar method and cache-ing strategy. This may cause
+strange effects if the Perl code dynamically changes @ISA in any package.
+
+You may add other methods to the UNIVERSAL class via Perl or XS code.
+You do not need to C<use UNIVERSAL> to make these methods
+available to your program (and you should not do so).
+
 =item C<VERSION ( [ REQUIRE ] )>
 
 C<VERSION> will return the value of the variable C<$VERSION> in the
diff --git a/pod/perlobj.pod b/pod/perlobj.pod
index 5b6adba..44ae453 100644
--- a/pod/perlobj.pod
+++ b/pod/perlobj.pod
@@ -158,8 +158,8 @@ through @ISA are known as base classes of the current class.
 
 All classes implicitly inherit from class C<UNIVERSAL> as their
 last base class.  Several commonly used methods are automatically
-supplied in the UNIVERSAL class; see L<"Default UNIVERSAL methods"> for
-more details.
+supplied in the UNIVERSAL class; see L<"Default UNIVERSAL methods"> or
+L<UNIVERSAL|UNIVERSAL> for more details.
 X<UNIVERSAL> X<base class> X<class, base>
 
 If a missing method is found in a base class, it is cached
@@ -405,38 +405,18 @@ X<isa>
 
 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.  Of
-course, this will do the wrong thing if someone has overridden C<isa> in a
-class, so don't do it.
-
-If you need to determine whether you've received a valid invocant, use the
-C<blessed> function from L<Scalar::Util>:
-X<invocant> X<blessed>
-
-    if (blessed($ref) && $ref->isa( 'Some::Class')) {
-        # ...
-    }
-
-C<blessed> returns the name of the package the argument has been
-blessed into, or C<undef>.
-
 =item DOES(ROLE)
+X<DOES>
 
-C<DOES> returns I<true> if its object claims to perform the role C<ROLE>.
-
-By default, the response to C<DOES> is the same as the response to ISA.  For
-more information on C<DOES> and other universal methods, see L<UNIVERSAL>.
+C<DOES> returns I<true> if its object claims to perform the role C<ROLE>.  By
+default, this is equivalent to C<isa>.
 
 =item can(METHOD)
 X<can>
 
 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.
-The same caveats for calling C<UNIVERSAL::isa> directly apply here, too.
+C<undef> is returned.
 
 =item VERSION( [NEED] )
 X<VERSION>
@@ -444,24 +424,15 @@ X<VERSION>
 C<VERSION> returns the version number of the class (package).  If the
 NEED argument is given then it will check that the current version (as
 defined by the $VERSION variable in the given package) not less than
-NEED; it will die if this is not the case.  This method is normally
-called as a class method.  This method is called automatically by the
-C<VERSION> form of C<use>.
+NEED; it will die if this is not the case.  This method is called automatically
+by the C<VERSION> form of C<use>.
 
-    use A 1.2 qw(some imported subs);
+    use Package 1.2 qw(some imported subs);
     # implies:
-    A->VERSION(1.2);
+    Package->VERSION(1.2);
 
 =back
 
-B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and
-C<isa> uses a very similar method and cache-ing strategy. This may cause
-strange effects if the Perl code dynamically changes @ISA in any package.
-
-You may add other methods to the UNIVERSAL class via Perl or XS code.
-You do not need to C<use UNIVERSAL> to make these methods
-available to your program (and you should not do so).
-
 =head2 Destructors
 X<destructor> X<DESTROY>