Document delete %hash{key} return value

cc0776d64 introduced delete on key-value hash slices. That intuitively
returns a list of key- value pairs, which is two elements per specified
hash key. Update the docs to reflect this.

1 files changed, 6 insertions, 3 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index fa08d4c3e9..b55068f1f9 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1595,10 +1595,13 @@ so that L<C<exists>|/exists EXPR> on that element no longer returns
 true.  Setting a hash element to the undefined value does not remove its
 key, but deleting it does; see L<C<exists>|/exists EXPR>.
 
-In list context, returns the value or values deleted, or the last such
-element in scalar context.  The return list's length always matches that of
+In list context, usually returns the value or values deleted, or the last such
+element in scalar context.  The return list's length corresponds to that of
 the argument list: deleting non-existent elements returns the undefined value
-in their corresponding positions.
+in their corresponding positions. When a
+L<keyE<sol>value hash slice|perldata/KeyE<sol>Value Hash Slices> is passed to
+C<delete>, the return value is a list of key/value pairs (two elements for each
+item deleted from the hash).
 
 L<C<delete>|/delete EXPR> may also be used on arrays and array slices,
 but its behavior is less straightforward.  Although