[inseparable changes from patch from perl5.003_22 to perl5.003_23]

[perl5.git] / pod / perldiag.pod

diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index d08d2dc..0f204a8 100644 (file)
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -799,6 +799,12 @@ Perhaps you need to copy the value to a temporary, and repeat that.
 (F) The create routine failed for some reason while trying to process
 a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
 
+=item Cannot resolve method `%s' overloading `%s' in package `%s'
+
+(F|P) Error resolving overloading specified by a method name (as
+opposed to a subroutine reference): no such method callable via the
+package. If method name is C<???>, this is an internal error.
+
 =item chmod: mode argument is missing initial 0
 
 (W) A novice will sometimes say
@@ -823,6 +829,10 @@ the return value of your socket() call?  See L<perlfunc/connect>.
 inlining.  See L<perlsub/"Constant Functions"> for commentary and
 workarounds.
 
+=item Copy method did not return a reference
+
+(F) The method which overloads "=" is buggy. See L<overload/Copy Constructor>.
+
 =item Corrupt malloc ptr 0x%lx at 0x%lx
 
 (P) The malloc package that comes with Perl had an internal failure.
@@ -1177,7 +1187,7 @@ assume that an unbackslashed @ interpolates an array.)
 =item Method for operation %s not found in package %s during blessing
 
 (F) An attempt was made to specify an entry in an overloading table that
-doesn't somehow point to a valid method.  See L<overload>.
+doesn't resolve to a valid subroutine.  See L<overload>.
 
 =item Might be a runaway multi-line %s string starting on line %d
 
@@ -1420,7 +1430,7 @@ subroutine), but found a reference to something else instead.  You can
 use the ref() function to find out what kind of ref it really was.
 See also L<perlref>.
 
-=item Not a subroutine reference in %OVERLOAD
+=item Not a subroutine reference in overload table
 
 (F) An attempt was made to specify an entry in an overloading table that
 doesn't somehow point to a valid subroutine.  See L<overload>.
@@ -1487,21 +1497,13 @@ will extend the buffer and zero pad the new area.
 
 (S) An internal warning that the grammar is screwed up.
 
-=item Operation `%s' %s: no method found,
-
-(F) An attempt was made to use an entry in an overloading table that
-somehow no longer points to a valid method.  See L<overload>.
-
-=item Stub found while resolving method `%s' overloading `%s' in package `%s'
-
-(P) Overloading resolution over @ISA tree may be broken by importing stubs.
-Stubs should never be implicitely created, but explicit calls to C<can>
-may break this.
-
-=item Cannot resolve method `%s' overloading `%s' in package `s'
+=item Operation `%s': no method found,%s
 
-(P) Internal error trying to resolve overloading specified by a method
-name (as opposed to a subroutine reference).
+(F) An attempt was made to perform an overloaded operation for which
+no handler was defined.  While some handlers can be autogenerated in
+terms of other handlers, there is no default handler for any
+operation, unless C<fallback> overloading key is specified to be
+true.  See L<overload>.
 
 =item Operator or semicolon missing before %s
 
@@ -1714,27 +1716,49 @@ the BSD version, which takes a pid.
 
 =item Possible attempt to put comments in qw() list
 
-(W) You probably wrote something like this:
+(W) qw() lists contain items separated by whitespace; as with literal
+strings, comment characters are not ignored, but are instead treated
+as literal data.  (You may have used different delimiters than the
+exclamation marks parentheses shown here; braces are also frequently
+used.)
 
-    qw( a # a comment
+You probably wrote something like this:
+
+    @list = qw( 
+       a # a comment
         b # another comment
-      ) ;
+    );
 
 when you should have written this:
 
-    qw( a 
+    @list = qw(
+       a 
         b 
-      ) ;
+    );
+
+If you really want comments, build your list the
+old-fashioned way, with quotes and commas:
+
+    @list = (
+        'a',    # a comment
+        'b',    # another comment
+    );
 
 =item Possible attempt to separate words with commas
 
-(W) You probably wrote something like this:
+(W) qw() lists contain items separated by whitespace; therefore commas
+aren't needed to separate the items. (You may have used different
+delimiters than the parentheses shown here; braces are also frequently
+used.)
 
-    qw( a, b, c );
+You probably wrote something like this: 
 
-when you should have written this:
+    qw! a, b, c !;
+
+which puts literal commas into some of the list items.  Write it without
+commas if you don't want them to appear in your data:
 
-    qw( a b c );
+    qw! a b c !;
 
 =item Possible memory corruption: %s overflowed 3rd argument
 
@@ -2002,6 +2026,12 @@ there was a failure.  You probably wanted to use system() instead,
 which does return.  To suppress this warning, put the exec() in a block
 by itself.
 
+=item Stub found while resolving method `%s' overloading `%s' in package `%s'
+
+(P) Overloading resolution over @ISA tree may be broken by importation stubs.
+Stubs should never be implicitely created, but explicit calls to C<can>
+may break this.
+
 =item Subroutine %s redefined
 
 (W) You redefined a subroutine.  To suppress this warning, say
@@ -2558,10 +2588,10 @@ streams, such as
     }
     close OUT;
 
-=item Got an error from DosAllocMem:
+=item Got an error from DosAllocMem
 
-(P) An error peculiar to OS/2. Most probably you use an obsolete version
-of perl, and this should not happen anyway.
+(P) An error peculiar to OS/2.  Most probably you're using an obsolete
+version of Perl, and this should not happen anyway.
 
 =item Malformed PERLLIB_PREFIX