[perl #95538] perldiag.pod on defined %hash

I found the perldiag.pod description of item "defined(%hash) is
deprecated" unclear.

At first I thought it was threatening another incompatible change, but
if I'm not mistaken it's merely that defined %hash has only ever been a
check for non-empty, which may not be what you intended.  If so then
perhaps a wording like the following could make it clearer,

diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 483d164f496f42a4caa4d21d8c03117d93b4ac63..5bf28c8bcc5b2eebc7ff9aa7f7dc9cb079f42ea8 100644 (file)
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -1517,9 +1517,20 @@ array is empty, just use C<if (@array) { # not empty }> for example.
 
 =item defined(%hash) is deprecated
 
-(D deprecated) 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, just use C<if (%hash) { # not empty }> for example.
+(D deprecated) C<defined()> is not usually useful on hashes; it merely
+checks for non-empty, similar to a hash in boolean context (see
+L<perldata>).  If a non-empty check is what you want then just use:
+
+    if (%hash) {
+       # not empty
+    }
+
+If you had C<defined(%Foo::Bar::QUUX)> to check whether such a
+package variable exists, then it has never actually done that,
+but instead creates the hash if necessary (autovivification)
+then tests for non-empty.  If you really want to check
+existence of a package variable then look at the glob slot
+with C<defined *Foo::Bar::QUUX{HASH}> (see L<perlref>).
 
 =item (?(DEFINE)....) does not allow branches in regex; marked by <-- HERE in m/%s/