remove misleading info on defined(&func), unclutter deprecation

about defined(@array)

p4raw-id: //depot/perl@3567

3 files changed, 15 insertions, 16 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 3f2214a987..3284cf70da 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -477,13 +477,13 @@ by Perl.
 (W) You used the C<open(FH, "| command")> or C<open(FH, "command |")>
 construction, but the command was missing or blank.
 
-=item defined(@array) is deprecated (and not really meaningful)
+=item defined(@array) is deprecated
 
 (D) defined() is not usually useful on arrays because it checks for an
 undefined I<scalar> value.  If you want to see if the array is empty,
 just use C<if (@array) { # not empty }> for example.  
 
-=item defined(%hash) is deprecated (and not really meaningful)
+=item defined(%hash) is deprecated
 
 (D) defined() is not usually useful on hashes because it checks for an
 undefined I<scalar> value.  If you want to see if the hash is empty,
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 0084f9c6da..d7b9024998 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -1105,13 +1105,13 @@ times more than it has returned.  This probably indicates an infinite
 recursion, unless you're writing strange benchmark programs, in which
 case it indicates something else.
 
-=item defined(@array) is deprecated (and not really meaningful)
+=item defined(@array) is deprecated
 
 (D) defined() is not usually useful on arrays because it checks for an
 undefined I<scalar> value.  If you want to see if the array is empty,
 just use C<if (@array) { # not empty }> for example.  
 
-=item defined(%hash) is deprecated (and not really meaningful)
+=item defined(%hash) is deprecated
 
 (D) defined() is not usually useful on hashes because it checks for an
 undefined I<scalar> value.  If you want to see if the hash is empty,
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 0ac28103d2..6b0fd9d323 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -881,10 +881,17 @@ doesn't I<necessarily> indicate an exceptional condition: C<pop>
 returns C<undef> when its argument is an empty array, I<or> when the
 element to return happens to be C<undef>.
 
-You may also use C<defined> to check whether a subroutine exists, by
-saying C<defined &func> without parentheses.  On the other hand, use
-of C<defined> upon aggregates (hashes and arrays) is not guaranteed to
-produce intuitive results, and should probably be avoided.
+You may also use C<defined(&func)> to check whether subroutine C<&func>
+has ever been defined.  The return value is unaffected by any forward
+declarations of C<&foo>.
+
+Use of C<defined> on aggregates (hashes and arrays) is deprecated.  It
+used to report whether memory for that aggregate has ever been
+allocated.  This behavior may disappear in future versions of Perl.
+You should instead use a simple test for size:
+
+    if (@an_array) { print "has array elements\n" }
+    if (%a_hash)   { print "has hash members\n"   }
 
 When used on a hash element, it tells you whether the value is defined,
 not whether the key exists in the hash.  Use L</exists> for the latter
@@ -914,14 +921,6 @@ should use C<defined> only when you're questioning the integrity of what
 you're trying to do.  At other times, a simple comparison to C<0> or C<""> is
 what you want.
 
-Use of C<defined> on aggregates (hashes and arrays) is deprecated.  It
-used to report whether memory for that aggregate has ever been
-allocated.  This behavior may disappear in future versions of Perl.
-You should instead use a simple test for size:
-
-    if (@an_array) { print "has array elements\n" }
-    if (%a_hash)   { print "has hash members\n"   }
-
 See also L</undef>, L</exists>, L</ref>.
 
 =item delete EXPR