Document that smartmatch is deprecated and will be removed in 5.42

Author: book

lib/feature.pm

@@ -2643,11 +2643,10 @@ C<getpwnam> operator returned an invalid UIC.
 forget to check the return value of your socket() call?  See
 L<perlfunc/getsockopt>.
 
-=item given is experimental
+=item given is deprecated
 
-(S experimental::smartmatch) C<given> depends on smartmatch, which
-is experimental, so its behavior may change or even be removed
-in any future release of perl.  See the explanation under
+(D deprecated) C<given> depends on smartmatch, which is deprecated. It
+will be removed in Perl 5.42.  See the explanation under
 L<perlsyn/Experimental Details on given and when>.
 
 =item Global symbol "%s" requires explicit package name (did you forget to
@@ -6038,14 +6037,13 @@ so there can't be any left to fill later parameters.
 overload it: Perl refuses to use the object's underlying structure
 for the smart match.
 
-=item Smartmatch is experimental
+=item Smartmatch is deprecated
 
-(S experimental::smartmatch) This warning is emitted if you
-use the smartmatch (C<~~>) operator.  This is currently an experimental
-feature, and its details are subject to change in future releases of
-Perl.  Particularly, its current behavior is noticed for being
-unnecessarily complex and unintuitive, and is very likely to be
-overhauled.
+(D deprecated) This warning is emitted if you
+use the smartmatch (C<~~>) operator.  This is a deprecated
+feature.  Particularly, its behavior is noticed for being
+unnecessarily complex and unintuitive, and it will be removed
+in Perl 5.42.
 
 =item Sorry, hash keys must be smaller than 2**31 bytes
 
@@ -8025,12 +8023,12 @@ but in actual fact, you got
 
 So put in parentheses to say what you really mean.
 
-=item when is experimental
+=item when is deprecated
 
-(S experimental::smartmatch) C<when> depends on smartmatch, which is
-experimental.  Additionally, it has several special cases that may
-not be immediately obvious, and their behavior may change or
-even be removed in any future release of perl.  See the explanation
+(D deprecated) C<when> depends on smartmatch, which is
+deprecated.  Additionally, it has several special cases that may
+not be immediately obvious, and it will be removed in Perl 5.42.
+See the explanation
 under L<perlsyn/Experimental Details on given and when>.
 
 =item Wide character in %s

pod/perldiag.pod

@@ -605,6 +605,9 @@ =head2 The 'switch' feature
 See L<perlsyn/"Switch Statements"> for details.
 
 This feature is available starting with Perl 5.10.
+It is deprecated starting with Perl 5.38, and using
+C<given>, C<when> or smartmatch will throw a warning.
+It will be removed in Perl 5.42.
 
 =head2 The 'unicode_strings' feature