chore: better identify EXPERIMENTAL rules (#7729)

Co-authored-by: Greg Korba <wirone@gmail.com>

doc/rules/function_notation/phpdoc_to_param_type.rst

@@ -2,20 +2,27 @@
 Rule ``phpdoc_to_param_type``
 =============================
 
-EXPERIMENTAL: Takes ``@param`` annotations of non-mixed types and adjusts
-accordingly the function signature. Requires PHP >= 7.0.
+Takes ``@param`` annotations of non-mixed types and adjusts accordingly the
+function signature. Requires PHP >= 7.0.
 
 Warning
 -------
 
+This rule is experimental
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Rule is not covered with backward compatibility promise, use it at your own
+risk. Rule's behaviour may be changed at any point, including rule's name; its
+options' names, availability and allowed values; its default configuration. Rule
+may be even removed without prior notice. Feel free to provide feedback and help
+with determining final state of the rule.
+
 Using this rule is risky
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-This rule is EXPERIMENTAL and [1] is not covered with backward compatibility
-promise. [2] ``@param`` annotation is mandatory for the fixer to make changes,
-signatures of methods without it (no docblock, inheritdocs) will not be fixed.
-[3] Manual actions are required if inherited signatures are not properly
-documented.
+The ``@param`` annotation is mandatory for the fixer to make changes, signatures
+of methods without it (no docblock, inheritdocs) will not be fixed. Manual
+actions are required if inherited signatures are not properly documented.
 
 Configuration
 -------------

doc/rules/function_notation/phpdoc_to_property_type.rst

@@ -2,20 +2,27 @@
 Rule ``phpdoc_to_property_type``
 ================================
 
-EXPERIMENTAL: Takes ``@var`` annotation of non-mixed types and adjusts
-accordingly the property signature. Requires PHP >= 7.4.
+Takes ``@var`` annotation of non-mixed types and adjusts accordingly the
+property signature. Requires PHP >= 7.4.
 
 Warning
 -------
 
+This rule is experimental
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Rule is not covered with backward compatibility promise, use it at your own
+risk. Rule's behaviour may be changed at any point, including rule's name; its
+options' names, availability and allowed values; its default configuration. Rule
+may be even removed without prior notice. Feel free to provide feedback and help
+with determining final state of the rule.
+
 Using this rule is risky
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-This rule is EXPERIMENTAL and [1] is not covered with backward compatibility
-promise. [2] ``@var`` annotation is mandatory for the fixer to make changes,
-signatures of properties without it (no docblock) will not be fixed. [3] Manual
-actions might be required for newly typed properties that are read before
-initialization.
+The ``@var`` annotation is mandatory for the fixer to make changes, signatures
+of properties without it (no docblock) will not be fixed. Manual actions might
+be required for newly typed properties that are read before initialization.
 
 Configuration
 -------------

doc/rules/function_notation/phpdoc_to_return_type.rst

@@ -2,20 +2,27 @@
 Rule ``phpdoc_to_return_type``
 ==============================
 
-EXPERIMENTAL: Takes ``@return`` annotation of non-mixed types and adjusts
-accordingly the function signature.
+Takes ``@return`` annotation of non-mixed types and adjusts accordingly the
+function signature.
 
 Warning
 -------
 
+This rule is experimental
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Rule is not covered with backward compatibility promise, use it at your own
+risk. Rule's behaviour may be changed at any point, including rule's name; its
+options' names, availability and allowed values; its default configuration. Rule
+may be even removed without prior notice. Feel free to provide feedback and help
+with determining final state of the rule.
+
 Using this rule is risky
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-This rule is EXPERIMENTAL and [1] is not covered with backward compatibility
-promise. [2] ``@return`` annotation is mandatory for the fixer to make changes,
+The ``@return`` annotation is mandatory for the fixer to make changes,
 signatures of methods without it (no docblock, inheritdocs) will not be fixed.
-[3] Manual actions are required if inherited signatures are not properly
-documented.
+Manual actions are required if inherited signatures are not properly documented.
 
 Configuration
 -------------

doc/rules/index.rst

@@ -401,15 +401,15 @@ Function Notation
 - `nullable_type_declaration_for_default_null_value <./function_notation/nullable_type_declaration_for_default_null_value.rst>`_
 
   Adds or removes ``?`` before single type declarations or ``|null`` at the end of union types when parameters have a default ``null`` value.
-- `phpdoc_to_param_type <./function_notation/phpdoc_to_param_type.rst>`_ *(risky)*
+- `phpdoc_to_param_type <./function_notation/phpdoc_to_param_type.rst>`_ *(experimental, risky)*
 
-  EXPERIMENTAL: Takes ``@param`` annotations of non-mixed types and adjusts accordingly the function signature. Requires PHP >= 7.0.
-- `phpdoc_to_property_type <./function_notation/phpdoc_to_property_type.rst>`_ *(risky)*
+  Takes ``@param`` annotations of non-mixed types and adjusts accordingly the function signature. Requires PHP >= 7.0.
+- `phpdoc_to_property_type <./function_notation/phpdoc_to_property_type.rst>`_ *(experimental, risky)*
 
-  EXPERIMENTAL: Takes ``@var`` annotation of non-mixed types and adjusts accordingly the property signature. Requires PHP >= 7.4.
-- `phpdoc_to_return_type <./function_notation/phpdoc_to_return_type.rst>`_ *(risky)*
+  Takes ``@var`` annotation of non-mixed types and adjusts accordingly the property signature. Requires PHP >= 7.4.
+- `phpdoc_to_return_type <./function_notation/phpdoc_to_return_type.rst>`_ *(experimental, risky)*
 
-  EXPERIMENTAL: Takes ``@return`` annotation of non-mixed types and adjusts accordingly the function signature.
+  Takes ``@return`` annotation of non-mixed types and adjusts accordingly the function signature.
 - `regular_callable_call <./function_notation/regular_callable_call.rst>`_ *(risky)*
 
   Callables must be called without using ``call_user_func*`` when possible.
@@ -463,9 +463,9 @@ Import
 Language Construct
 ------------------
 
-- `class_keyword <./language_construct/class_keyword.rst>`_ *(risky)*
+- `class_keyword <./language_construct/class_keyword.rst>`_ *(experimental, risky)*
 
-  EXPERIMENTAL: Converts FQCN strings to ``*::class`` keywords. Do not use it, unless you know what you are doing.
+  Converts FQCN strings to ``*::class`` keywords.
 - `class_keyword_remove <./language_construct/class_keyword_remove.rst>`_ *(deprecated)*
 
   Converts ``::class`` keywords to FQCN strings.

doc/rules/language_construct/class_keyword.rst

@@ -2,8 +2,7 @@
 Rule ``class_keyword``
 ======================
 
-EXPERIMENTAL: Converts FQCN strings to ``*::class`` keywords. Do not use it,
-unless you know what you are doing.
+Converts FQCN strings to ``*::class`` keywords.
 
 Description
 -----------
@@ -16,10 +15,19 @@ context.
 Warning
 -------
 
+This rule is experimental
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Rule is not covered with backward compatibility promise, use it at your own
+risk. Rule's behaviour may be changed at any point, including rule's name; its
+options' names, availability and allowed values; its default configuration. Rule
+may be even removed without prior notice. Feel free to provide feedback and help
+with determining final state of the rule.
+
 Using this rule is risky
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Risky as EXPERIMENTAL.
+Do not use it, unless you know what you are doing.
 
 Examples
 --------

src/Console/Command/DescribeCommand.php

@@ -21,6 +21,7 @@ use PhpCsFixer\Differ\FullDiffer;
 use PhpCsFixer\Documentation\FixerDocumentGenerator;
 use PhpCsFixer\Fixer\ConfigurableFixerInterface;
 use PhpCsFixer\Fixer\DeprecatedFixerInterface;
+use PhpCsFixer\Fixer\ExperimentalFixerInterface;
 use PhpCsFixer\Fixer\FixerInterface;
 use PhpCsFixer\FixerConfiguration\AliasedFixerOption;
 use PhpCsFixer\FixerConfiguration\AllowedValueSubset;
@@ -179,8 +180,15 @@ final class DescribeCommand extends Command
 
         $output->writeln('');
 
+        if ($fixer instanceof ExperimentalFixerInterface) {
+            $output->writeln('<error>Fixer applying this rule is EXPERIMENTAL.</error>.');
+            $output->writeln('It is not covered with backward compatibility promise and may produce unstable or unexpected results.');
+
+            $output->writeln('');
+        }
+
         if ($fixer->isRisky()) {
-            $output->writeln('<error>Fixer applying this rule is risky.</error>');
+            $output->writeln('<error>Fixer applying this rule is RISKY.</error>');
 
             $riskyDescription = $definition->getRiskyDescription();
 

src/Documentation/FixerDocumentGenerator.php

@@ -18,6 +18,7 @@ use PhpCsFixer\Console\Command\HelpCommand;
 use PhpCsFixer\Differ\FullDiffer;
 use PhpCsFixer\Fixer\ConfigurableFixerInterface;
 use PhpCsFixer\Fixer\DeprecatedFixerInterface;
+use PhpCsFixer\Fixer\ExperimentalFixerInterface;
 use PhpCsFixer\Fixer\FixerInterface;
 use PhpCsFixer\FixerConfiguration\AliasedFixerOption;
 use PhpCsFixer\FixerConfiguration\AllowedValueSubset;
@@ -89,6 +90,19 @@ final class FixerDocumentGenerator
             }
         }
 
+        $experimentalDescription = '';
+
+        if ($fixer instanceof ExperimentalFixerInterface) {
+            $experimentalDescriptionRaw = RstUtils::toRst('Rule is not covered with backward compatibility promise, use it at your own risk. Rule\'s behaviour may be changed at any point, including rule\'s name; its options\' names, availability and allowed values; its default configuration. Rule may be even removed without prior notice. Feel free to provide feedback and help with determining final state of the rule.', 0);
+            $experimentalDescription = <<<RST
+
+                This rule is experimental
+                ~~~~~~~~~~~~~~~~~~~~~~~~~
+
+                {$experimentalDescriptionRaw}
+                RST;
+        }
+
         $riskyDescription = '';
         $riskyDescriptionRaw = $definition->getRiskyDescription();
 
@@ -115,6 +129,7 @@ final class FixerDocumentGenerator
                 $warningsHeader,
                 $warningsHeaderLine,
                 $deprecationDescription,
+                $experimentalDescription,
                 $riskyDescription,
             ]));
         }
@@ -317,6 +332,10 @@ final class FixerDocumentGenerator
                 $attributes[] = 'deprecated';
             }
 
+            if ($fixer instanceof ExperimentalFixerInterface) {
+                $attributes[] = 'experimental';
+            }
+
             if ($fixer->isRisky()) {
                 $attributes[] = 'risky';
             }

src/Fixer/ExperimentalFixerInterface.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of PHP CS Fixer.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *     Dariusz Rumiński <dariusz.ruminski@gmail.com>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace PhpCsFixer\Fixer;
+
+/**
+ * @internal
+ */
+interface ExperimentalFixerInterface extends FixerInterface {}

src/Fixer/FunctionNotation/PhpdocToParamTypeFixer.php

@@ -16,6 +16,7 @@ namespace PhpCsFixer\Fixer\FunctionNotation;
 
 use PhpCsFixer\AbstractPhpdocToTypeDeclarationFixer;
 use PhpCsFixer\DocBlock\Annotation;
+use PhpCsFixer\Fixer\ExperimentalFixerInterface;
 use PhpCsFixer\FixerDefinition\CodeSample;
 use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
@@ -25,7 +26,7 @@ use PhpCsFixer\Tokenizer\Tokens;
 /**
  * @author Jan Gantzert <jan@familie-gantzert.de>
  */
-final class PhpdocToParamTypeFixer extends AbstractPhpdocToTypeDeclarationFixer
+final class PhpdocToParamTypeFixer extends AbstractPhpdocToTypeDeclarationFixer implements ExperimentalFixerInterface
 {
     private const TYPE_CHECK_TEMPLATE = '<?php function f(%s $x) {}';
 
@@ -49,7 +50,7 @@ final class PhpdocToParamTypeFixer extends AbstractPhpdocToTypeDeclarationFixer
     public function getDefinition(): FixerDefinitionInterface
     {
         return new FixerDefinition(
-            'EXPERIMENTAL: Takes `@param` annotations of non-mixed types and adjusts accordingly the function signature. Requires PHP >= 7.0.',
+            'Takes `@param` annotations of non-mixed types and adjusts accordingly the function signature. Requires PHP >= 7.0.',
             [
                 new CodeSample(
                     '<?php
@@ -84,7 +85,7 @@ function bar($foo) {}
                 ),
             ],
             null,
-            'This rule is EXPERIMENTAL and [1] is not covered with backward compatibility promise. [2] `@param` annotation is mandatory for the fixer to make changes, signatures of methods without it (no docblock, inheritdocs) will not be fixed. [3] Manual actions are required if inherited signatures are not properly documented.'
+            'The `@param` annotation is mandatory for the fixer to make changes, signatures of methods without it (no docblock, inheritdocs) will not be fixed. Manual actions are required if inherited signatures are not properly documented.'
         );
     }
 

src/Fixer/FunctionNotation/PhpdocToPropertyTypeFixer.php

@@ -16,6 +16,7 @@ namespace PhpCsFixer\Fixer\FunctionNotation;
 
 use PhpCsFixer\AbstractPhpdocToTypeDeclarationFixer;
 use PhpCsFixer\DocBlock\Annotation;
+use PhpCsFixer\Fixer\ExperimentalFixerInterface;
 use PhpCsFixer\FixerDefinition\CodeSample;
 use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
@@ -25,7 +26,7 @@ use PhpCsFixer\Tokenizer\Tokens;
 /**
  * @phpstan-import-type _CommonTypeInfo from AbstractPhpdocToTypeDeclarationFixer
  */
-final class PhpdocToPropertyTypeFixer extends AbstractPhpdocToTypeDeclarationFixer
+final class PhpdocToPropertyTypeFixer extends AbstractPhpdocToTypeDeclarationFixer implements ExperimentalFixerInterface
 {
     private const TYPE_CHECK_TEMPLATE = '<?php class A { private %s $b; }';
 
@@ -40,7 +41,7 @@ final class PhpdocToPropertyTypeFixer extends AbstractPhpdocToTypeDeclarationFix
     public function getDefinition(): FixerDefinitionInterface
     {
         return new FixerDefinition(
-            'EXPERIMENTAL: Takes `@var` annotation of non-mixed types and adjusts accordingly the property signature. Requires PHP >= 7.4.',
+            'Takes `@var` annotation of non-mixed types and adjusts accordingly the property signature. Requires PHP >= 7.4.',
             [
                 new CodeSample(
                     '<?php
@@ -76,7 +77,7 @@ class Foo {
                 ),
             ],
             null,
-            'This rule is EXPERIMENTAL and [1] is not covered with backward compatibility promise. [2] `@var` annotation is mandatory for the fixer to make changes, signatures of properties without it (no docblock) will not be fixed. [3] Manual actions might be required for newly typed properties that are read before initialization.'
+            'The `@var` annotation is mandatory for the fixer to make changes, signatures of properties without it (no docblock) will not be fixed. Manual actions might be required for newly typed properties that are read before initialization.'
         );
     }