Document the %hash{$scalar} warning

2 files changed, 24 insertions, 0 deletions

diff --git a/op.c b/op.c
index 57c20eea40..38ea5b7d86 100644
--- a/op.c
+++ b/op.c
@@ -1235,6 +1235,7 @@ Perl_scalar(pTHX_ OP *o)
 		    assert(SvPOK(name));
 		    sv_chop(name,SvPVX(name)+1);
 		    if (key)
+       /* diag_listed_as: Scalar value %%s[%s] better written as $%s[%s] */
 			Perl_warner(aTHX_ packWARN(WARN_SYNTAX),
 				   "Scalar value %%%"SVf
 				   "%c%s%c better written as $%"SVf
@@ -1242,6 +1243,7 @@ Perl_scalar(pTHX_ OP *o)
 				    SVfARG(name), lbrack, key, rbrack,
 				    SVfARG(name), lbrack, key, rbrack);
 		    else
+       /* diag_listed_as: Scalar value %%s[%s] better written as $%s[%s] */
 			Perl_warner(aTHX_ packWARN(WARN_SYNTAX),
 				   "Scalar value %%%"SVf"%c%"SVf
 				   "%c better written as $%"SVf
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index f25533b59c..1737325771 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -4613,6 +4613,28 @@ as a list, you need to look into how references work, because Perl will
 not magically convert between scalars and lists for you.  See
 L<perlref>.
 
+=item Scalar value %%s[%s] better written as $%s[%s]
+
+(W syntax) In scalar context, you've used an array index/value slice
+(indicated by %) to select a single element of an array.  Generally
+it's better to ask for a scalar value (indicated by $).  The difference
+is that C<$foo[&bar]> always behaves like a scalar, both in the value it
+returns and when evaluating its argument, while C<%foo[&bar]> provides
+a list context to its subscript, which can do weird things if you're
+expecting only one subscript.  When called in list context, it also
+returns the index (what C<&bar> returns) in addition to the value.
+
+=item Scalar value %%s{%s} better written as $%s{%s}
+
+(W syntax) In scalar context, you've used a hash key/value slice
+(indicated by %) to select a single element of a hash.  Generally it's
+better to ask for a scalar value (indicated by $).  The difference
+is that C<$foo{&bar}> always behaves like a scalar, both in the value
+it returns and when evaluating its argument, while C<@foo{&bar}> and
+provides a list context to its subscript, which can do weird things
+if you're expecting only one subscript.  When called in list context,
+it also returns the key in addition to the value.
+
 =item Search pattern not terminated
 
 (F) The lexer couldn't find the final delimiter of a // or m{}