perldelta - Updates, tidy-ups and remove boilerplate

[perl5.git] / pod / perlfunc.pod

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 011bd9c..b55068f 100644 (file)
--- 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
@@ -3680,7 +3683,8 @@ may behave differently to Perl's hashes with respect to changes in order on
 insertion and deletion of items.
 
 As a side effect, calling L<C<keys>|/keys HASH> resets the internal
-iterator of the HASH or ARRAY (see L<C<each>|/each HASH>).  In
+iterator of the HASH or ARRAY (see L<C<each>|/each HASH>) before
+yielding the keys.  In
 particular, calling L<C<keys>|/keys HASH> in void context resets the
 iterator with no other overhead.
 
@@ -9600,9 +9604,12 @@ may behave differently to Perl's hashes with respect to changes in order on
 insertion and deletion of items.
 
 As a side effect, calling L<C<values>|/values HASH> resets the HASH or
-ARRAY's internal iterator, see L<C<each>|/each HASH>.  (In particular,
+ARRAY's internal iterator (see L<C<each>|/each HASH>) before yielding the
+values.  In particular,
 calling L<C<values>|/values HASH> in void context resets the iterator
-with no other overhead.  Apart from resetting the iterator,
+with no other overhead.
+
+Apart from resetting the iterator,
 C<values @array> in list context is the same as plain C<@array>.
 (We recommend that you use void context C<keys @array> for this, but
 reasoned that taking C<values @array> out would require more