[docs] add auto imports docs (#6240)

README.md

@@ -70,6 +70,7 @@ It supports all versions of PHP from 5.3 and major open-source projects:
 
 ### Advanced
 
+- [Auto Import Names](/docs/auto_import_names.md)
 - [How to Ignore Rule or Paths](/docs/how_to_ignore_rule_or_paths.md)
 - [Static Reflection and Autoload](/docs/static_reflection_and_autoload.md)
 - [How to Configure Rule](/docs/how_to_configure_rules.md)
@@ -161,15 +162,6 @@ return static function (ContainerConfigurator $containerConfigurator): void {
     // is your PHP version different from the one your refactor to? [default: your PHP version], uses PHP_VERSION_ID format
     $parameters->set(Option::PHP_VERSION_FEATURES, PhpVersion::PHP_72);
 
-    // auto import fully qualified class names? [default: false]
-    $parameters->set(Option::AUTO_IMPORT_NAMES, true);
-
-    // skip root namespace classes, like \DateTime or \Exception [default: true]
-    $parameters->set(Option::IMPORT_SHORT_CLASSES, false);
-
-    // skip classes used in PHP DocBlocks, like in /** @var \Some\Class */ [default: true]
-    $parameters->set(Option::IMPORT_DOC_BLOCKS, false);
-
     // Run Rector only on changed files
     $parameters->set(Option::ENABLE_CACHE, true);
 

docs/auto_import_names.md

@@ -0,0 +1,70 @@
+# Auto Import Names
+
+Rector works with all class names as fully qualified by default, so it know the exact types. In most coding standard, that's not desired behavior, because short version with `use` statement is preferred:
+
+```diff
+-$object = new \App\Some\Namespace\SomeClass();
++use App\Some\Namespace\SomeClass;
++$object = new SomeClass();
+```
+
+
+To import FQN like these, configure `rector.php` with:
+
+```php
+$parameters->set(Option::AUTO_IMPORT_NAMES, true);
+```
+
+<br>
+
+If you enable this feature, the class names in docblocks are imported as well:
+
+```diff
++use App\Some\Namespace\SomeClass;
+-/** @var \App\Some\Namespace\SomeClass $someClass */
++/** @var SomeClass $someClass */
+ $someClass = ...;
+```
+
+Do you want to skip them?
+
+```php
+$parameters->set(Option::IMPORT_DOC_BLOCKS, false);
+```
+
+<br>
+
+Single short classes are imported too:
+
+```diff
++use DateTime;
+-$someClass = \DateTime();
++$someClass = DateTime();
+```
+
+Do you want to keep those?
+
+```php
+$parameters->set(Option::IMPORT_SHORT_CLASSES, false);
+```
+
+## How to Remove Unused Imports?
+
+To remove imports, use [ECS](github.com/symplify/easy-coding-standard) with [`NoUnusedImportsFixer`](https://github.com/FriendsOfPHP/PHP-CS-Fixer/blob/2.18/doc/rules/import/no_unused_imports.rst) rule:
+
+```php
+// ecs.php
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+use PhpCsFixer\Fixer\Import\NoUnusedImportsFixer;
+
+return static function (ContainerConfigurator $containerConfigurator): void {
+    $services = $containerConfigurator->services();
+    $services->set(NoUnusedImportsFixer::class);
+};
+```
+
+Run it:
+
+```bash
+vendor/bin/ecs check src --fix
+```