From f6bcb50aae164386fcc44c15294e6f7de9722db4 Mon Sep 17 00:00:00 2001
From: "Paul \"LeoNerd\" Evans" <leonerd@leonerd.org.uk>
Date: Fri, 22 Nov 2024 20:17:47 +0000
Subject: [PATCH] First attempt at writing documentation for the new operators

---
 ext/Pod-Functions/t/Functions.t |  3 +-
 lib/feature.pm                  | 11 +++++-
 pod/perlfunc.pod                | 64 +++++++++++++++++++++++++++++++++
 regen/feature.pl                | 11 +++++-
 4 files changed, 86 insertions(+), 3 deletions(-)

diff --git a/ext/Pod-Functions/t/Functions.t b/ext/Pod-Functions/t/Functions.t
index ee3c3d3eaf2c7..d6b774dac9c8a 100644
--- a/ext/Pod-Functions/t/Functions.t
+++ b/ext/Pod-Functions/t/Functions.t
@@ -91,7 +91,8 @@ Functions for real @ARRAYs:
      each, keys, pop, push, shift, splice, unshift, values
 
 Functions for list data:
-     grep, join, map, qw/STRING/, reverse, sort, unpack
+     all, any, grep, join, map, qw/STRING/, reverse, sort,
+     unpack
 
 Functions for real %HASHes:
      delete, each, exists, keys, values
diff --git a/lib/feature.pm b/lib/feature.pm
index 75af1be899a44..d35e5460277ed 100644
--- a/lib/feature.pm
+++ b/lib/feature.pm
@@ -522,7 +522,16 @@ always enabled.
 
 =head2 The 'any_all' feature
 
-TODO write some docs
+B<WARNING>: This feature is still experimental and the implementation may
+change or be removed in future versions of Perl.  For this reason, Perl will
+warn when you use the feature, unless you have explicitly disabled the warning:
+
+    no warnings "experimental::any_all";
+
+This feature enables the L<C<any>|perlfunc/any BLOCK LIST> and
+L<C<all>|perlfunc/all BLOCK LIST> operator keywords.  These allow testing
+whether values in a list satisfy a given condition, with short-circuiting
+behaviour.
 
 =head1 FEATURE BUNDLES
 
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 6a2e5807fec3f..05d5a5c1e4624 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -173,6 +173,7 @@ X<list>
 
 =for Pod::Functions =LIST
 
+L<C<all>|/all BLOCK LIST>, L<C<any>|/any BLOCK LIST>,
 L<C<grep>|/grep BLOCK LIST>, L<C<join>|/join EXPR,LIST>,
 L<C<map>|/map BLOCK LIST>, L<C<qwE<sol>E<sol>>|/qwE<sol>STRINGE<sol>>,
 L<C<reverse>|/reverse LIST>, L<C<sort>|/sort SUBNAME LIST>,
@@ -805,6 +806,69 @@ For more information see L<perlipc>.
 
 Portability issues: L<perlport/alarm>.
 
+=item all BLOCK LIST
+
+=for Pod::Functions test if every value in a list satisfies the given condition
+
+Evaluates the BLOCK for each element of the LIST (locally setting
+L<C<$_>|perlvar/$_> to each element) and checks the truth of the result of
+that block.  Returns true if every element makes the block yield true, or
+returns false if at least one element makes the block false.
+
+As soon as any element makes the block yield false, then the result of this
+operator is determined.  It will short-circuit in that case and not consider
+any further elements.
+
+When used as a condition, this is similar to using L<C<grep>|/grep BLOCK LIST>
+to count that every value satisfies the condition, except for this
+short-circuit behaviour.
+
+    if( all { length $_ } @strings ) {
+        say "Every string is non-empty";
+    }
+
+is roughly equivalent to
+
+    if( @strings == grep { length $_ } @strings ) ...
+
+This operator is only available if the
+L<C<any_all> feature|feature/"The 'any_all' feature"> is enabled.
+
+It is currently considered B<experimental>, and will issue a compile-time
+warning in the category C<experimental::any_all> unless that category is
+silenced.
+
+=item any BLOCK LIST
+
+=for Pod::Functions test if at least one value in a list satisfies the given condition
+
+Evaluates the BLOCK for each element of the LIST (locally setting
+L<C<$_>|perlvar/$_> to each element) and checks the truth of the result of
+that block.  Returns true if at least one element makes the block yield
+true, or returns false if no element is found to make it true.
+
+As soon as any element makes the block yield true, then the result of this
+operator is determined.  It will short-circuit in that case and not consider
+any further elements.
+
+When used as a condition, this is similar to L<C<grep>|/grep BLOCK LIST>,
+except for this short-circuit behaviour.
+
+    if( any { length $_ } @strings ) {
+        say "At least one string is non-empty";
+    }
+
+is roughly equivalent to
+
+    if( grep { length $_ } @strings ) ...
+
+This operator is only available if the
+L<C<any_all> feature|feature/"The 'any_all' feature"> is enabled.
+
+It is currently considered B<experimental>, and will issue a compile-time
+warning in the category C<experimental::any_all> unless that category is
+silenced.
+
 =item atan2 Y,X
 X<atan2> X<arctangent> X<tan> X<tangent>
 
diff --git a/regen/feature.pl b/regen/feature.pl
index 6727a8374dee7..8af1b5dc8eb3f 100755
--- a/regen/feature.pl
+++ b/regen/feature.pl
@@ -984,7 +984,16 @@ =head2 The 'apostrophe_as_package_separator' feature
 
 =head2 The 'any_all' feature
 
-TODO write some docs
+B<WARNING>: This feature is still experimental and the implementation may
+change or be removed in future versions of Perl.  For this reason, Perl will
+warn when you use the feature, unless you have explicitly disabled the warning:
+
+    no warnings "experimental::any_all";
+
+This feature enables the L<C<any>|perlfunc/any BLOCK LIST> and
+L<C<all>|perlfunc/all BLOCK LIST> operator keywords.  These allow testing
+whether values in a list satisfy a given condition, with short-circuiting
+behaviour.
 
 =head1 FEATURE BUNDLES