Update docs wrt bitwise ops

5 files changed, 35 insertions, 49 deletions

diff --git a/lib/feature.pm b/lib/feature.pm
index 1ea74eb8a0..97f789ad64 100644
--- a/lib/feature.pm
+++ b/lib/feature.pm
@@ -316,13 +316,6 @@ This feature is available from Perl 5.22 onwards.
 
 =head2 The 'bitwise' feature
 
-B<WARNING>: This feature is still experimental and the implementation may
-change 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::bitwise";
-
 This makes the four standard bitwise operators (C<& | ^ ~>) treat their
 operands consistently as numbers, and introduces four new dotted operators
 (C<&. |. ^. ~.>) that treat their operands consistently as strings.  The
@@ -330,7 +323,10 @@ same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>).
 
 See L<perlop/Bitwise String Operators> for details.
 
-This feature is available from Perl 5.22 onwards.
+This feature is available from Perl 5.22 onwards.  Starting in Perl 5.28,
+C<use v5.28> will enable the feature.  Before 5.28, it was still
+experimental and would emit a warning in the "experimental::bitwise"
+category.
 
 =head2 The 'declared_refs' feature
 
diff --git a/lib/overload.pm b/lib/overload.pm
index b19c5a53cb..f7d5d0f7cf 100644
--- a/lib/overload.pm
+++ b/lib/overload.pm
@@ -310,7 +310,7 @@ An appropriate implementation of C<--> might look like
         # ...
     sub decr { --${$_[0]}; }
 
-If the experimental "bitwise" feature is enabled (see L<feature>), a fifth
+If the "bitwise" feature is enabled (see L<feature>), a fifth
 TRUE argument is passed to subroutines handling C<&>, C<|>, C<^> and C<~>.
 This indicates that the caller is expecting numeric behaviour.  The fourth
 argument will be C<undef>, as that position (C<$_[3]>) is reserved for use
@@ -693,7 +693,7 @@ The specified function will be passed four parameters.
 The first three arguments coincide with those that would have been
 passed to the corresponding method if it had been defined.
 The fourth argument is the C<use overload> key for that missing
-method.  If the experimental "bitwise" feature is enabled (see L<feature>),
+method.  If the "bitwise" feature is enabled (see L<feature>),
 a fifth TRUE argument is passed to subroutines handling C<&>, C<|>, C<^> and C<~> to indicate that the caller is expecting numeric behaviour.
 
 For example, if C<$a> is an object blessed into a package declaring
diff --git a/pod/perlexperiment.pod b/pod/perlexperiment.pod
index 3918080820..8c2c8f0ffb 100644
--- a/pod/perlexperiment.pod
+++ b/pod/perlexperiment.pod
@@ -92,18 +92,6 @@ C<experimental::re_strict>.
 
 See L<re/'strict' mode>
 
-=item String- and number-specific bitwise operators
-
-Introduced in Perl 5.22.0
-
-See also: L<perlop/Bitwise String Operators>
-
-Using this feature triggers warnings in the category
-C<experimental::bitwise>.
-
-The ticket for this feature is
-L<[perl #123707]|https://rt.perl.org/rt3/Ticket/Display.html?id=123707>.
-
 =item The <:win32> IO pseudolayer
 
 The ticket for this feature is
@@ -256,6 +244,12 @@ Introduced in Perl 5.18.0
 
 Accepted in Perl 5.26.0
 
+=item String- and number-specific bitwise operators
+
+Introduced in Perl 5.22.0
+
+Accepted in Perl 5.28.0
+
 =back
 
 =head2 Removed features
diff --git a/pod/perlop.pod b/pod/perlop.pod
index 023353c12c..ceeb97fc47 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -266,12 +266,13 @@ X<~> X<negation, binary>
 Starting in Perl 5.28, it is a fatal error to try to complement a string
 containing a character with an ordinal value above 255.
 
-If the experimental "bitwise" feature is enabled via S<C<use feature
-'bitwise'>>, then unary C<"~"> always treats its argument as a number, and an
+If the "bitwise" feature is enabled via S<C<use
+feature 'bitwise'>> or C<use v5.28>, then unary
+C<"~"> always treats its argument as a number, and an
 alternate form of the operator, C<"~.">, always treats its argument as a
 string.  So C<~0> and C<~"0"> will both give 2**32-1 on 32-bit platforms,
-whereas C<~.0> and C<~."0"> will both yield C<"\xff">.  This feature
-produces a warning unless you use S<C<no warnings 'experimental::bitwise'>>.
+whereas C<~.0> and C<~."0"> will both yield C<"\xff">.  Until Perl 5.28,
+this feature produced a warning in the C<"experimental::bitwise"> category.
 
 Unary C<"+"> has no effect whatsoever, even on strings.  It is useful
 syntactically for separating a function name from a parenthesized expression
@@ -872,10 +873,10 @@ the parentheses are essential in a test like
 
     print "Even\n" if ($x & 1) == 0;
 
-If the experimental "bitwise" feature is enabled via S<C<use feature
-'bitwise'>>, then this operator always treats its operand as numbers.  This
-feature produces a warning unless you also use C<S<no warnings
-'experimental::bitwise'>>.
+If the "bitwise" feature is enabled via S<C<use feature 'bitwise'>> or
+C<use v5.28>, then this operator always treats its operands as numbers.
+Before Perl 5.28 this feature produced a warning in the
+C<"experimental::bitwise"> category.
 
 =head2 Bitwise Or and Exclusive Or
 X<operator, bitwise, or> X<bitwise or> X<|> X<operator, bitwise, xor>
@@ -895,10 +896,10 @@ for example the parentheses are essential in a test like
 
     print "false\n" if (8 | 2) != 10;
 
-If the experimental "bitwise" feature is enabled via S<C<use feature
-'bitwise'>>, then this operator always treats its operand as numbers.  This
-feature produces a warning unless you also use S<C<no warnings
-'experimental::bitwise'>>.
+If the "bitwise" feature is enabled via S<C<use feature 'bitwise'>> or
+C<use v5.28>, then this operator always treats its operands as numbers.
+Before Perl 5.28. this feature produced a warning in the
+C<"experimental::bitwise"> category.
 
 =head2 C-style Logical And
 X<&&> X<logical and> X<operator, logical, and>
@@ -1233,7 +1234,7 @@ the number of elements produced by the expression on the right hand
 side of the assignment.
 
 The three dotted bitwise assignment operators (C<&.=> C<|.=> C<^.=>) are new in
-Perl 5.22 and experimental.  See L</Bitwise String Operators>.
+Perl 5.22.  See L</Bitwise String Operators>.
 
 =head2 Comma Operator
 X<comma> X<operator, comma> X<,>
@@ -3376,16 +3377,15 @@ operation you intend by using C<""> or C<0+>, as in the examples below.
     $baz = 0+$foo & 0+$bar;	# both ops explicitly numeric
     $biz = "$foo" ^ "$bar";	# both ops explicitly stringy
 
-This somewhat unpredictable behavior can be avoided with the experimental
-"bitwise" feature, new in Perl 5.22.  You can enable it via S<C<use feature
-'bitwise'>>.  By default, it will warn unless the C<"experimental::bitwise">
-warnings category has been disabled.  (S<C<use experimental 'bitwise'>> will
-enable the feature and disable the warning.)  Under this feature, the four
+This somewhat unpredictable behavior can be avoided with the "bitwise"
+feature, new in Perl 5.22.  You can enable it via S<C<use feature
+'bitwise'>> or C<use v5.28>.  Before Perl 5.28, it used to emit a warning
+in the C<"experimental::bitwise"> category.  Under this feature, the four
 standard bitwise operators (C<~ | & ^>) are always numeric.  Adding a dot
 after each operator (C<~. |. &. ^.>) forces it to treat its operands as
 strings:
 
-    use experimental "bitwise";
+    use feature "bitwise";
     $foo =  150  |  105;	# yields 255  (0x96 | 0x69 is 0xFF)
     $foo = '150' |  105;	# yields 255
     $foo =  150  | '105';	# yields 255
diff --git a/regen/feature.pl b/regen/feature.pl
index 4005144f48..ca7a9b3e88 100755
--- a/regen/feature.pl
+++ b/regen/feature.pl
@@ -626,13 +626,6 @@ This feature is available from Perl 5.22 onwards.
 
 =head2 The 'bitwise' feature
 
-B<WARNING>: This feature is still experimental and the implementation may
-change 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::bitwise";
-
 This makes the four standard bitwise operators (C<& | ^ ~>) treat their
 operands consistently as numbers, and introduces four new dotted operators
 (C<&. |. ^. ~.>) that treat their operands consistently as strings.  The
@@ -640,7 +633,10 @@ same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>).
 
 See L<perlop/Bitwise String Operators> for details.
 
-This feature is available from Perl 5.22 onwards.
+This feature is available from Perl 5.22 onwards.  Starting in Perl 5.28,
+C<use v5.28> will enable the feature.  Before 5.28, it was still
+experimental and would emit a warning in the "experimental::bitwise"
+category.
 
 =head2 The 'declared_refs' feature