Provide rules definitions

src/AbstractFixer.php

@@ -17,7 +17,6 @@ use PhpCsFixer\Fixer\ConfigurableFixerInterface;
 use PhpCsFixer\Fixer\DefinedFixerInterface;
 use PhpCsFixer\Fixer\FixerInterface;
 use PhpCsFixer\Fixer\WhitespacesAwareFixerInterface;
-use PhpCsFixer\FixerDefinition\ShortFixerDefinition;
 
 /**
  * @author Dariusz Rumiński <dariusz.ruminski@gmail.com>
@@ -90,13 +89,6 @@ abstract class AbstractFixer implements FixerInterface, DefinedFixerInterface
         $this->whitespacesConfig = $config;
     }
 
-    public function getDefinition()
-    {
-        return new ShortFixerDefinition(
-            $this->getDescription()
-        );
-    }
-
     private function getDefaultWhitespacesFixerConfig()
     {
         static $defaultWhitespacesFixerConfig = null;

src/Console/Command/DescribeCommand.php

@@ -18,8 +18,9 @@ use PhpCsFixer\Fixer\ConfigurableFixerInterface;
 use PhpCsFixer\Fixer\DefinedFixerInterface;
 use PhpCsFixer\Fixer\FixerInterface;
 use PhpCsFixer\FixerDefinition\CodeSampleInterface;
+use PhpCsFixer\FixerDefinition\FileSpecificCodeSampleInterface;
+use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
-use PhpCsFixer\FixerDefinition\ShortFixerDefinition;
 use PhpCsFixer\FixerDefinition\VersionSpecificCodeSampleInterface;
 use PhpCsFixer\FixerFactory;
 use PhpCsFixer\RuleSet;
@@ -106,7 +107,7 @@ final class DescribeCommand extends Command
         if ($fixer instanceof DefinedFixerInterface) {
             $definition = $fixer->getDefinition();
         } else {
-            $definition = new ShortFixerDefinition('Description is not available.');
+            $definition = new FixerDefinition('Description is not available.', array());
         }
 
         $output->writeln(sprintf('<info>Description of</info> %s <info>rule</info>.', $name));
@@ -170,7 +171,10 @@ final class DescribeCommand extends Command
                     $fixer->configure($codeSample->getConfiguration());
                 }
 
-                $fixer->fix(new StdinFileInfo(), $tokens);
+                $file = $codeSample instanceof FileSpecificCodeSampleInterface
+                    ? $codeSample->getSplFileInfo()
+                    : new StdinFileInfo();
+                $fixer->fix($file, $tokens);
                 $new = $tokens->generateCode();
                 $diff = $differ->diff($old, $new);
 
@@ -184,7 +188,7 @@ final class DescribeCommand extends Command
             }
         }
 
-        if ($definition instanceof ShortFixerDefinition) {
+        if (!($fixer instanceof DefinedFixerInterface)) {
             $output->writeln(sprintf('<question>This rule is not yet described, do you want to help us and describe it?</question>'));
             $output->writeln('Contribute at <comment>https://github.com/FriendsOfPHP/PHP-CS-Fixer</comment> !');
             $output->writeln('');

src/Fixer/ArrayNotation/ArraySyntaxFixer.php

@@ -107,7 +107,7 @@ final class ArraySyntaxFixer extends AbstractFixer implements ConfigurableFixerI
                 ),
             ),
             null,
-            'The following can be configured: `only_untyped => "long"|"short"`',
+            'The following can be configured: `syntax => "long"|"short"`',
             self::$defaultConfiguration
         );
     }

src/Fixer/Basic/Psr0Fixer.php

@@ -14,6 +14,8 @@ namespace PhpCsFixer\Fixer\Basic;
 
 use PhpCsFixer\AbstractPsrAutoloadingFixer;
 use PhpCsFixer\Fixer\ConfigurableFixerInterface;
+use PhpCsFixer\FixerDefinition\FileSpecificCodeSample;
+use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\Tokenizer\Tokens;
 
 /**
@@ -143,8 +145,31 @@ final class Psr0Fixer extends AbstractPsrAutoloadingFixer implements Configurabl
     /**
      * {@inheritdoc}
      */
-    protected function getDescription()
+    public function getDefinition()
     {
-        return 'Classes must be in a path that matches their namespace, be at least one namespace deep and the class name should match the file name.';
+        return new FixerDefinition(
+            'Classes must be in a path that matches their namespace, be at least one namespace deep and the class name should match the file name.',
+            array(
+                new FileSpecificCodeSample(
+                    '<?php
+namespace PhpCsFixer\FIXER\Basic;
+class InvalidName {}
+',
+                    new \SplFileInfo(__FILE__)
+                ),
+                new FileSpecificCodeSample(
+                    '<?php
+namespace PhpCsFixer\FIXER\Basic;
+class InvalidName {}
+',
+                    new \SplFileInfo(__FILE__),
+                    array('dir' => realpath(__DIR__.'/../..'))
+                ),
+            ),
+            null,
+            'One could set up `dir` where the code is placed under project location.',
+            self::$defaultConfiguration,
+            'This fixer may change you class name, which will break the code that is depended on old name.'
+        );
     }
 }

src/Fixer/Basic/Psr4Fixer.php

@@ -13,6 +13,8 @@
 namespace PhpCsFixer\Fixer\Basic;
 
 use PhpCsFixer\AbstractPsrAutoloadingFixer;
+use PhpCsFixer\FixerDefinition\FileSpecificCodeSample;
+use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\Tokenizer\Tokens;
 
 /**
@@ -72,8 +74,23 @@ final class Psr4Fixer extends AbstractPsrAutoloadingFixer
     /**
      * {@inheritdoc}
      */
-    protected function getDescription()
+    public function getDefinition()
     {
-        return 'Class names should match the file name.';
+        return new FixerDefinition(
+            'Class names should match the file name.',
+            array(
+                new FileSpecificCodeSample(
+                    '<?php
+namespace PhpCsFixer\FIXER\Basic;
+class InvalidName {}
+',
+                    new \SplFileInfo(__FILE__)
+                ),
+            ),
+            null,
+            null,
+            null,
+            'This fixer may change you class name, which will break the code that is depended on old name.'
+        );
     }
 }

src/Fixer/ClassNotation/MethodSeparationFixer.php

@@ -14,6 +14,8 @@ namespace PhpCsFixer\Fixer\ClassNotation;
 
 use PhpCsFixer\AbstractFixer;
 use PhpCsFixer\Fixer\WhitespacesAwareFixerInterface;
+use PhpCsFixer\FixerDefinition\CodeSample;
+use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\Tokenizer\Token;
 use PhpCsFixer\Tokenizer\Tokens;
 use PhpCsFixer\Tokenizer\TokensAnalyzer;
@@ -66,19 +68,36 @@ final class MethodSeparationFixer extends AbstractFixer implements WhitespacesAw
     /**
      * {@inheritdoc}
      */
-    public function getPriority()
+    public function getDefinition()
     {
-        // Must run before BracesFixer and IndentationTypeFixer fixers because this fixer
-        // might add line breaks to the code without indenting.
-        return 55;
+        return new FixerDefinition(
+            'Methods must be separated with one blank line.',
+            array(
+                new CodeSample(
+                    '<?php
+final class Sample
+{
+    protected function foo()
+    {
+    }
+    protected function bar()
+    {
+    }
+}
+'
+                ),
+            )
+        );
     }
 
     /**
      * {@inheritdoc}
      */
-    protected function getDescription()
+    public function getPriority()
     {
-        return 'Methods must be separated with one blank line.';
+        // Must run before BracesFixer and IndentationTypeFixer fixers because this fixer
+        // might add line breaks to the code without indenting.
+        return 55;
     }
 
     /**

src/Fixer/ClassNotation/NoBlankLinesAfterClassOpeningFixer.php

@@ -14,6 +14,8 @@ namespace PhpCsFixer\Fixer\ClassNotation;
 
 use PhpCsFixer\AbstractFixer;
 use PhpCsFixer\Fixer\WhitespacesAwareFixerInterface;
+use PhpCsFixer\FixerDefinition\CodeSample;
+use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\Tokenizer\Token;
 use PhpCsFixer\Tokenizer\Tokens;
 use PhpCsFixer\Utils;
@@ -53,9 +55,24 @@ final class NoBlankLinesAfterClassOpeningFixer extends AbstractFixer implements
     /**
      * {@inheritdoc}
      */
-    protected function getDescription()
+    public function getDefinition()
     {
-        return 'There should be no empty lines after class opening brace.';
+        return new FixerDefinition(
+            'There should be no empty lines after class opening brace.',
+            array(
+                new CodeSample(
+                    '<?php
+final class Sample
+{
+
+    protected function foo()
+    {
+    }
+}
+'
+                ),
+            )
+        );
     }
 
     /**

src/Fixer/ClassNotation/OrderedClassElementsFixer.php

@@ -15,6 +15,8 @@ namespace PhpCsFixer\Fixer\ClassNotation;
 use PhpCsFixer\AbstractFixer;
 use PhpCsFixer\ConfigurationException\InvalidFixerConfigurationException;
 use PhpCsFixer\Fixer\ConfigurableFixerInterface;
+use PhpCsFixer\FixerDefinition\CodeSample;
+use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\Tokenizer\CT;
 use PhpCsFixer\Tokenizer\Token;
 use PhpCsFixer\Tokenizer\Tokens;
@@ -177,19 +179,62 @@ final class OrderedClassElementsFixer extends AbstractFixer implements Configura
     /**
      * {@inheritdoc}
      */
-    public function getPriority()
+    public function getDefinition()
     {
-        // must run before MethodSeparationFixer, NoBlankLinesAfterClassOpeningFixer and SpaceAfterSemicolonFixer.
-        // must run after ProtectedToPrivateFixer.
-        return 65;
+        $types = array_merge(array_keys(self::$typeHierarchy), array_keys(self::$specialTypes));
+        sort($types);
+
+        return new FixerDefinition(
+            'Orders the elements of classes/interfaces/traits.',
+            array(
+                new CodeSample(
+                    '<?php
+final class Example
+{
+    use BarTrait;
+    use BazTrait;
+    const C1 = 1;
+    const C2 = 2;
+    protected static $protStatProp;
+    public static $pubStatProp1;
+    public $pubProp1;
+    protected $protProp;
+    var $pubProp2;
+    private static $privStatProp;
+    private $privProp;
+    public static $pubStatProp2;
+    public $pubProp3;
+    protected function __construct() {}
+    private static function privStatFunc() {}
+    public function pubFunc1() {}
+    public function __toString() {}
+    protected function protFunc() {}
+    function pubFunc2() {}
+    public static function pubStatFunc1() {}
+    public function pubFunc3() {}
+    static function pubStatFunc2() {}
+    private function privFunc() {}
+    public static function pubStatFunc3() {}
+    protected static function protStatFunc() {}
+    public function __destruct() {}
+}
+'
+                ),
+            ),
+            null,
+            sprintf('List of strings defining order of elements. Possible values: %s.', implode(', ', $types)),
+            self::$defaultConfiguration
+        );
     }
 
     /**
      * {@inheritdoc}
      */
-    protected function getDescription()
+    public function getPriority()
     {
-        return 'Orders the elements of classes/interfaces/traits.';
+        // must run before MethodSeparationFixer, NoBlankLinesAfterClassOpeningFixer and SpaceAfterSemicolonFixer.
+        // must run after ProtectedToPrivateFixer.
+        return 65;
     }
 
     /**

src/Fixer/ClassNotation/SingleClassElementPerStatementFixer.php

@@ -16,6 +16,8 @@ use PhpCsFixer\AbstractFixer;
 use PhpCsFixer\ConfigurationException\InvalidFixerConfigurationException;
 use PhpCsFixer\Fixer\ConfigurableFixerInterface;
 use PhpCsFixer\Fixer\WhitespacesAwareFixerInterface;
+use PhpCsFixer\FixerDefinition\CodeSample;
+use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\Tokenizer\CT;
 use PhpCsFixer\Tokenizer\Token;
 use PhpCsFixer\Tokenizer\Tokens;
@@ -30,21 +32,21 @@ use PhpCsFixer\Tokenizer\TokensAnalyzer;
  */
 final class SingleClassElementPerStatementFixer extends AbstractFixer implements ConfigurableFixerInterface, WhitespacesAwareFixerInterface
 {
-    /**
-     * @var string[]
-     */
-    private $configuration;
-
     /**
      * Default target/configuration.
      *
      * @var string[]
      */
     private static $defaultConfiguration = array(
-        'property',
         'const',
+        'property',
     );
 
+    /**
+     * @var string[]
+     */
+    private $configuration;
+
     /**
      * {@inheritdoc}
      */
@@ -93,9 +95,35 @@ final class SingleClassElementPerStatementFixer extends AbstractFixer implements
     /**
      * {@inheritdoc}
      */
-    protected function getDescription()
+    public function getDefinition()
     {
-        return 'There MUST NOT be more than one property or constant declared per statement.';
+        return new FixerDefinition(
+            'There MUST NOT be more than one property or constant declared per statement.',
+            array(
+                new CodeSample(
+                    '<?php
+final class Example
+{
+    const FOO_1 = 1, FOO_2 = 2;
+    private static $bar1 = array(1,2,3), $bar2 = [1,2,3];
+}
+'
+                ),
+                new CodeSample(
+                    '<?php
+final class Example
+{
+    const FOO_1 = 1, FOO_2 = 2;
+    private static $bar1 = array(1,2,3), $bar2 = [1,2,3];
+}
+',
+                    array('property')
+                ),
+            ),
+            null,
+            'List of strings which element should be modified, possible values: `const`, `property`.',
+            self::$defaultConfiguration
+        );
     }
 
     /**

src/Fixer/Comment/HeaderCommentFixer.php

@@ -17,6 +17,8 @@ use PhpCsFixer\ConfigurationException\InvalidFixerConfigurationException;
 use PhpCsFixer\ConfigurationException\RequiredFixerConfigurationException;
 use PhpCsFixer\Fixer\ConfigurableFixerInterface;
 use PhpCsFixer\Fixer\WhitespacesAwareFixerInterface;
+use PhpCsFixer\FixerDefinition\CodeSample;
+use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\Tokenizer\Token;
 use PhpCsFixer\Tokenizer\Tokens;
 
@@ -51,13 +53,6 @@ final class HeaderCommentFixer extends AbstractFixer implements ConfigurableFixe
 
     /**
      * {@inheritdoc}
-     *
-     * The following configuration options are allowed:
-     * - commentType  PHPDoc|comment*
-     * - location     after_open|after_declare_strict*
-     * - separate     top|bottom|none|both*
-     *
-     * (* is the default when the item is omitted)
      */
     public function configure(array $configuration = null)
     {
@@ -107,17 +102,75 @@ final class HeaderCommentFixer extends AbstractFixer implements ConfigurableFixe
     /**
      * {@inheritdoc}
      */
-    public function isCandidate(Tokens $tokens)
+    public function getDefinition()
     {
-        return $tokens[0]->isGivenKind(T_OPEN_TAG) && $tokens->isMonolithicPhp();
+        return new FixerDefinition(
+            'Add, replace or remove header comment.',
+            array(
+                new CodeSample(
+                    '<?php
+declare(strict_types=1);
+
+namespace A\B;
+
+echo 1;
+',
+                    array(
+                        'header' => 'Made with love.',
+                    )
+                ),
+                new CodeSample(
+                    '<?php
+declare(strict_types=1);
+
+namespace A\B;
+
+echo 1;
+',
+                    array(
+                        'header' => 'Made with love.',
+                        'commentType' => 'PHPDoc',
+                        'location' => 'after_open',
+                        'separate' => 'bottom',
+                    )
+                ),
+                new CodeSample(
+                    '<?php
+declare(strict_types=1);
+
+namespace A\B;
+
+echo 1;
+',
+                    array(
+                        'header' => 'Made with love.',
+                        'commentType' => 'comment',
+                        'location' => 'after_declare_strict',
+                    )
+                ),
+            ),
+            null,
+            'The following configuration options are allowed:
+- header       proper header content here, this option is required
+- commentType  PHPDoc|comment*
+- location     after_open|after_declare_strict*
+- separate     top|bottom|none|both*
+
+* is the default when the item is omitted',
+            array(
+                'commentType' => 'comment',
+                'location' => 'after_declare_strict',
+                'separate' => 'both',
+            )
+        );
     }
 
     /**
      * {@inheritdoc}
      */
-    protected function getDescription()
+    public function isCandidate(Tokens $tokens)
     {
-        return 'Add, replace or remove header comment.';
+        return $tokens[0]->isGivenKind(T_OPEN_TAG) && $tokens->isMonolithicPhp();
     }
 
     /**