X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlobj.pod;h=f427de7cdea5fd48b7c89a389e9c14b84e60bed6;hb=cf2649810f00335bd657355d81bcc9384a620135;hp=7d7beaf477d6e04189109043f7bdaf89bea1f672;hpb=2359510ddb135dcc6e80153f51cff0a97b20b597;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlobj.pod b/pod/perlobj.pod
index 7d7beaf..f427de7 100644
--- a/pod/perlobj.pod
+++ b/pod/perlobj.pod
@@ -97,9 +97,11 @@ so that your constructors may be inherited:
     }
 
 Or if you expect people to call not just C<< CLASS->new() >> but also
-C<< $obj->new() >>, then use something like this.  The initialize()
-method used will be of whatever $class we blessed the
-object into:
+C<< $obj->new() >>, then use something like the following.  (Note that using
+this to call new() on an instance does not automatically perform any
+copying.  If you want a shallow or deep copy of an object, you'll have to
+specifically allow for that.)  The initialize() method used will be of
+whatever $class we blessed the object into:
 
     sub new {
 	my $this = shift;
@@ -371,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)
 
@@ -390,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] )
 
@@ -485,9 +476,8 @@ if you don't care to leak.  For example, here's a self-referential
 node such as one might use in a sophisticated tree structure:
 
     sub new_node {
-	my $self = shift;
-	my $class = ref($self) || $self;
-	my $node = {};
+	my $class = shift;
+	my $node  = {};
 	$node->{LEFT} = $node->{RIGHT} = $node;
 	$node->{DATA} = [ @_ ];
 	return bless $node => $class;