Clarify and complete documentation for in-place reverse

2 files changed, 8 insertions, 2 deletions

diff --git a/pod/perl5112delta.pod b/pod/perl5112delta.pod
index 0fed6261d6..82412b2616 100644
--- a/pod/perl5112delta.pod
+++ b/pod/perl5112delta.pod
@@ -166,8 +166,10 @@ Any changes to F<pod/perldiag.pod> should go in L</New or Changed Diagnostics>.
 
 =item *
 
-Reversing an array in-place in void context is now several orders of magnitude faster than it used to be.
-It will also preserve non-existent elements whenever possible, i.e. for non magical arrays or tied arrays with C<EXISTS> and C<DELETE> methods.
+Reversing an array to itself (as in C<@a = reverse @a>) in void context now
+happens in-place and is several orders of magnitude faster than it used to be.
+It will also preserve non-existent elements whenever possible, i.e. for non
+magical arrays or tied arrays with C<EXISTS> and C<DELETE> methods.
 
 =back
 
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 862e0ba73d..53c318fdb6 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -4782,6 +4782,10 @@ Used without arguments in scalar context, reverse() reverses C<$_>.
     print reverse;                              # No output, list context
     print scalar reverse;                       # Hello, world
 
+Note that reversing an array to itself (as in C<@a = reverse @a>) will
+preserve non-existent elements whenever possible, i.e. for non magical
+arrays or tied arrays with C<EXISTS> and C<DELETE> methods.
+
 This operator is also handy for inverting a hash, although there are some
 caveats.  If a value is duplicated in the original hash, only one of those
 can be represented as a key in the inverted hash.  Also, this has to