Tidy documentation

README.md

@@ -4,11 +4,11 @@
 [![Code Coverage](https://coveralls.io/repos/github/olvlvl/composer-attribute-collector/badge.svg?branch=main)](https://coveralls.io/r/olvlvl/composer-attribute-collector?branch=main)
 [![Downloads](https://img.shields.io/packagist/dt/olvlvl/composer-attribute-collector.svg)](https://packagist.org/packages/olvlvl/composer-attribute-collector)
 
-composer-attribute-collector is a plugin for [Composer][]. Its ambition is to provide a convenient
-way—and near zero cost—to retrieve targets of PHP 8 attributes. After the autoloader has been
-dumped, the plugin collects attribute targets and generates a static file. Later, these targets can
-be retrieved through a convenient interface, without reflection. The plugin is useful when you need
-to _discover_ attribute targets in a codebase—for known targets you can use reflection.
+**composer-attribute-collector** is a plugin for [Composer][]. Its ambition is to provide a
+convenient way—and near zero cost—to retrieve targets of PHP 8 attributes. After the autoloader has
+been dumped, the plugin collects attribute targets and generates a static file. These targets can be
+retrieved through a convenient interface, without reflection. The plugin is useful when you need to
+_discover_ attribute targets in a codebase—for known targets you can use reflection.
 
 
 
@@ -21,6 +21,10 @@ to _discover_ attribute targets in a codebase—for known targets you can use re
 - A single interface to get attribute targets: classes, methods, and properties
 - Can cache discoveries to speed up consecutive runs.
 
+> [!NOTE]
+> Currently, the plugin supports class, method, and property targets.
+> You're welcome to [contribute](CONTRIBUTING.md) if you're interested in expending its support.
+
 
 
 #### Usage
@@ -77,26 +81,13 @@ var_dump($attributes->propertyAttributes);
 
 ## Getting started
 
+Here are a few steps to get you started.
 
-### Installation
-
-```shell
-composer require olvlvl/composer-attribute-collector
-```
-
-The plugin is currently experimental and its interface subject to change. At the moment, it only
-supports class, method, and property targets. Please [contribute](CONTRIBUTING.md) if you're interested in
-shaping its future.
-
-
-
-### Sample configuration
+### 1\. Configure the plugin
 
-The plugin only inspects paths and files specified in the configuration with the direction
-`include`. That's usually your "src" directory. Add this section to your `composer.json` file to
-enable the generation of the attributes file on autoload dump.
-
-Check the [Configuration options](#configuration) for more details.
+The plugin only inspects paths and files specified in the configuration with the `include` property.
+That is usually your "src" directory. Add this section to your `composer.json` file to enable the
+generation of the "attributes" file when the autoloader is dumped.
 
 ```json
 {
@@ -110,12 +101,39 @@ Check the [Configuration options](#configuration) for more details.
 }
 ```
 
+Check the [Configuration options](#configuration) for more details.
+
 
 
-### Autoloading
+### 2\. Install the plugin
 
-You can require the attributes file using `require_once 'vendor/attributes.php';` but you might
-prefer using Composer's autoloading feature:
+Use [Composer][] to install the plugin.
+You will be asked if you trust the plugin and wish to activate it.
+Select `y` to proceed.
+
+```shell
+composer require olvlvl/composer-attribute-collector
+```
+
+You should see log messages similar to this:
+
+```
+Generating autoload files
+Generating attributes file
+Generated attributes file in 9.137 ms
+Generated autoload files
+```
+
+> [!TIP]
+> See the [Frequently Asked Questions](#frequently-asked-questions) section
+> to automatically refresh the "attributes" file during development.
+
+
+
+### 3\. Autoload the "attributes" file
+
+You can require the "attributes" file using `require_once 'vendor/attributes.php';` but you might
+prefer to use Composer's autoloading feature:
 
 ```json
 {
@@ -131,10 +149,14 @@ prefer using Composer's autoloading feature:
 
 ## Configuration
 
+Here are a few ways you can configure the plugin.
+
+
+
 ### Including paths or files ([root-only][])
 
 Use the `include` property to define the paths or files to inspect for attributes. Without this
-property, the attributes file will be empty.
+property, the "attributes" file will be empty.
 
 The specified paths are relative to the `composer.json` file, and the `{vendor}` placeholder is
 replaced with the path to the vendor folder.
@@ -178,48 +200,24 @@ set the environment variable `COMPOSER_ATTRIBUTE_COLLECTOR_USE_CACHE` to `1`, `y
 Cache items are persisted in the `.composer-attribute-collector` directory, you might want to add
 it to your `.gitignore` file.
 
+```shell
+COMPOSER_ATTRIBUTE_COLLECTOR_USE_CACHE=1 composer dump-autoload
+```
+
 
 
 ## Test drive with the Symfony Demo
 
 You can try the plugin with a fresh installation of the [Symfony Demo Application](https://github.com/symfony/demo).
 
-Add the `composer-attribute-collector` node to `extra` and the autoload item to the `composer.json` file:
-
-```json
-{
-  "autoload": {
-    "files": [
-        "vendor/attributes.php"
-    ]
-  },
-  "extra": {
-    "composer-attribute-collector": {
-      "include": [
-        "src"
-      ]
-    }
-  }
-}
-```
-
-Use Composer to install the plugin. You'll be asked if you trust the plugin and wish to activate it.
-If you wish to continue, choose `y`.
-
-```shell
-composer require olvlvl/composer-attribute-collector
-```
-
-You should see log messages similar to this:
+> [!TIP]
+> The demo application configured with the plugin is [available on GitHub](https://github.com/olvlvl/composer-attribute-collector-usecase-symfony).
 
-```
-Generating autoload files
-Generating attributes file
-Generated attributes file in 9.137 ms
-Generated autoload files
-```
+See the [Getting started](#getting-started) section to set up the plugin. If all went well, the file
+`vendor/attributes.php` should be available.
 
-The plugin should have generated the file `vendor/attributes.php`. Let's see if we can get the controller methods tagged as routes. Create a PHP file with the following content and run it:
+Now, you can try to get the controller methods tagged as routes. Create a PHP file with the
+following content and run it:
 
 ```php
 <?php
@@ -248,8 +246,6 @@ action: App\Controller\BlogController#commentNew, path: /comment/{postSlug}/new
 action: App\Controller\BlogController#search, path: /search
 ```
 
-The demo application configured with the plugin is [available on GitHub](https://github.com/olvlvl/composer-attribute-collector-usecase-symfony).
-
 
 
 ## Frequently Asked Questions
@@ -261,15 +257,15 @@ to Composer to find classes. Anything that works with Composer should work with
 
 **Can I use the plugin during development?**
 
-Yes, you can use the plugin during development, but keep in mind the attributes file is only
-generated after the autoloader is dumped. If you modify attributes you'll have to run
-`composer dump` to refresh the attributes file.
+Yes, you can use the plugin during development, but keep in mind the "attributes" file is only
+generated after the autoloader is dumped. If you modify attributes you will have to run
+`composer dump-autoload` to refresh the "attributes" file.
 
 As a workaround you could have watchers on the directories that contain classes with attributes to
-run `XDEBUG_MODE=off composer dump` when you make changes. [PhpStorm offers file watchers][phpstorm-watchers].
-You could also use [spatie/file-system-watcher][], it only requires PHP. If the plugin is too slow
-for your liking, try running the command with `COMPOSER_ATTRIBUTE_COLLECTOR_USE_CACHE=yes`, it will
-enable caching and speed up consecutive runs.
+run `XDEBUG_MODE=off composer dump-autoload` when you make changes. [PhpStorm offers file
+watchers][phpstorm-watchers]. You could also use [spatie/file-system-watcher][], it only requires
+PHP. If the plugin is too slow for your liking, try running the command with
+`COMPOSER_ATTRIBUTE_COLLECTOR_USE_CACHE=yes`, it will enable caching and speed up consecutive runs.
 
 
 

src/Attributes.php

@@ -1,12 +1,5 @@
 <?php
 
-/*
- * (c) Olivier Laviale <[email protected]>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-
 namespace olvlvl\ComposerAttributeCollector;
 
 use Closure;

src/ClassAttributeCollector.php

@@ -7,7 +7,6 @@
 use ReflectionAttribute;
 use ReflectionClass;
 use ReflectionException;
-use Throwable;
 
 /**
  * @internal
@@ -27,8 +26,6 @@ public function __construct(
      *     array<TransientTargetMethod>,
      *     array<TransientTargetProperty>,
      * }
-     *     Where `0` is an array of class attributes, `1` is an array of method attributes,
-     *     and `2` is an array of property attributes.
      *
      * @throws ReflectionException
      */

src/Collection.php

@@ -1,12 +1,5 @@
 <?php
 
-/*
- * (c) Olivier Laviale <[email protected]>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-
 namespace olvlvl\ComposerAttributeCollector;
 
 use RuntimeException;

src/Config.php

@@ -2,7 +2,6 @@
 
 namespace olvlvl\ComposerAttributeCollector;
 
-use Composer\Composer;
 use Composer\Factory;
 use Composer\PartialComposer;
 use Composer\Util\Platform;
@@ -91,9 +90,9 @@ public static function resolveVendorDir(PartialComposer $composer): string
      * @param non-empty-string $attributesFile
      *     Absolute path to the `attributes.php` file.
      * @param non-empty-string[] $include
-     *     Paths that should be included to attributes collection.
+     *     Paths that should be included in the attribute collection.
      * @param non-empty-string[] $exclude
-     *     Paths that should be excluded from attributes collection.
+     *     Paths that should be excluded from the attribute collection.
      * @param bool $useCache
      *     Whether a cache should be used during the process.
      */

src/Filter/Chain.php

@@ -1,12 +1,5 @@
 <?php
 
-/*
- * (c) Olivier Laviale <[email protected]>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-
 namespace olvlvl\ComposerAttributeCollector\Filter;
 
 use Composer\IO\IOInterface;

src/Filter/ContentFilter.php

@@ -1,12 +1,5 @@
 <?php
 
-/*
- * (c) Olivier Laviale <[email protected]>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-
 namespace olvlvl\ComposerAttributeCollector\Filter;
 
 use Composer\IO\IOInterface;

src/Filter/InterfaceFilter.php

@@ -1,12 +1,5 @@
 <?php
 
-/*
- * (c) Olivier Laviale <[email protected]>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-
 namespace olvlvl\ComposerAttributeCollector\Filter;
 
 use Composer\IO\IOInterface;

src/MemoizeAttributeCollector.php

@@ -45,8 +45,6 @@ public function __construct(
     /**
      * @param array<class-string, string> $classMap
      *     Where _key_ is a class and _value_ its pathname.
-     *
-     * @throws ReflectionException
      */
     public function collectAttributes(array $classMap): TransientCollection
     {
@@ -95,7 +93,7 @@ public function collectAttributes(array $classMap): TransientCollection
         }
 
         /**
-         * Classes might have been removed, we need to filter according to the classes found.
+         * Classes might have been removed, we need to filter entries according to the classes found.
          */
         $this->state = array_filter(
             $this->state,

src/MemoizeClassMapFilter.php

@@ -70,7 +70,7 @@ public function filter(array $classMap, Closure $filter): array
         }
 
         /**
-         * Paths might have been removed, we need to filter according to the paths found.
+         * Paths might have been removed, we need to filter entries according to the paths found.
          */
         $this->state = array_filter(
             $this->state,

src/MemoizeClassMapGenerator.php

@@ -112,7 +112,7 @@ private function shouldUpdate(int $timestamp, string $path): bool
             return true;
         }
 
-        // Could be a file referenced as class map, we don't want to iterate over that.
+        // Could be a file referenced as a class map, we don't want to iterate over that.
         if (!is_dir($path)) {
             return false;
         }

src/Plugin.php

@@ -96,7 +96,7 @@ public static function onPostAutoloadDump(Event $event): void
     public static function dump(Config $config, IOInterface $io): void
     {
         //
-        // Scan include paths
+        // Scan the included paths
         //
         $start = microtime(true);
         $datastore = self::buildDefaultDatastore($config, $io);

src/TargetClass.php

@@ -1,12 +1,5 @@
 <?php
 
-/*
- * (c) Olivier Laviale <[email protected]>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-
 namespace olvlvl\ComposerAttributeCollector;
 
 /**
@@ -19,6 +12,7 @@ final class TargetClass
     /**
      * @param T $attribute
      * @param class-string $name
+     *     The name of the target class.
      */
     public function __construct(
         public object $attribute,