Re: AW: [PATCH pod/*] Use Direct Object Constructor Calls

Message-Id: <200609010912.46314.chromatic@wgz.org>

p4raw-id: //depot/perl@28778

1 files changed, 12 insertions, 11 deletions

diff --git a/pod/perlref.pod b/pod/perlref.pod
index 21f15d41eb..afc1671fdf 100644
--- a/pod/perlref.pod
+++ b/pod/perlref.pod
@@ -210,17 +210,18 @@ that most Perl programmers need trouble themselves about to begin with.
 =item 5.
 X<constructor> X<new>
 
-References are often returned by special subroutines called constructors.
-Perl objects are just references to a special type of object that happens to know
-which package it's associated with.  Constructors are just special
-subroutines that know how to create that association.  They do so by
-starting with an ordinary reference, and it remains an ordinary reference
-even while it's also being an object.  Constructors are often
-named new() and called indirectly:
-
-    $objref = new Doggie (Tail => 'short', Ears => 'long');
-
-But don't have to be:
+References are often returned by special subroutines called constructors.  Perl
+objects are just references to a special type of object that happens to know
+which package it's associated with.  Constructors are just special subroutines
+that know how to create that association.  They do so by starting with an
+ordinary reference, and it remains an ordinary reference even while it's also
+being an object.  Constructors are often named C<new()>.  You I<can> call them
+indirectly:
+
+    $objref = new Doggie( Tail => 'short', Ears => 'long' );
+
+But that can produce ambiguous syntax in certain cases, so it's often
+better to use the direct method invocation approach:
 
     $objref   = Doggie->new(Tail => 'short', Ears => 'long');