refactor: enhance documentation for ComposerJson, DevToolsCommandLoader, SystemClock, and DevToolsServiceProvider classes

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

src/Composer/Json/ComposerJson.php

@@ -21,12 +21,41 @@
 use Composer\Factory;
 use Composer\Json\JsonFile;
 
+/**
+ * Represents a specialized reader for a Composer JSON file.
+ *
+ * This class SHALL provide convenient accessors for commonly used
+ * `composer.json` metadata after reading and caching the file contents.
+ * Consumers SHOULD use this class when they need normalized access to
+ * package-level metadata. The internal data cache MUST reflect the
+ * contents returned by the underlying JSON file reader at construction
+ * time.
+ */
 final class ComposerJson extends JsonFile
 {
+    /**
+     * Stores the decoded Composer JSON document contents.
+     *
+     * This property MUST contain the data read from the target Composer
+     * file during construction. Consumers SHOULD treat the structure as
+     * internal implementation detail and SHALL rely on accessor methods
+     * instead of direct access.
+     *
+     * @var array<string, mixed>
+     */
     private array $data;
 
     /**
-     * @param string|null $path
+     * Initializes the Composer JSON reader.
+     *
+     * When no path is provided, the default Composer file location
+     * returned by Composer's factory SHALL be used. The constructor MUST
+     * immediately read and cache the JSON document contents so that
+     * subsequent accessor methods can operate on the in-memory data.
+     *
+     * @param string|null $path The absolute or relative path to a
+     *                          Composer JSON file. When omitted, the
+     *                          default Composer file path SHALL be used.
      */
     public function __construct(?string $path = null)
     {
@@ -35,23 +64,45 @@ public function __construct(?string $path = null)
     }
 
     /**
-     * @return string
+     * Returns the package name declared in the Composer file.
+     *
+     * This method SHALL return the value of the `name` key when present.
+     * If the package name is not defined, the method MUST return an
+     * empty string.
+     *
+     * @return string the package name, or an empty string when undefined
      */
     public function getPackageName(): string
     {
         return $this->data['name'] ?? '';
     }
 
     /**
-     * @return string
+     * Returns the package description declared in the Composer file.
+     *
+     * This method SHALL return the value of the `description` key when
+     * present. If the description is not defined, the method MUST return
+     * an empty string.
+     *
+     * @return string the package description, or an empty string when
+     *                undefined
      */
     public function getPackageDescription(): string
     {
         return $this->data['description'] ?? '';
     }
 
     /**
-     * @return string|null
+     * Returns the package license when it can be resolved to a single value.
+     *
+     * This method SHALL return the `license` value directly when it is a
+     * string. When the license is an array containing exactly one item,
+     * that single item SHALL be returned. When the license field is not
+     * present, is empty, or cannot be resolved to exactly one string
+     * value, the method MUST return null.
+     *
+     * @return string|null the resolved license identifier, or null when
+     *                     no single license value can be determined
      */
     public function getPackageLicense(): ?string
     {
@@ -69,25 +120,47 @@ public function getPackageLicense(): ?string
     }
 
     /**
-     * @return array
+     * Returns the package authors declared in the Composer file.
+     *
+     * This method SHALL return the value of the `authors` key when
+     * present. If the key is absent, the method MUST return an empty
+     * array.
+     *
+     * @return array the authors list as declared in the Composer file,
+     *               or an empty array when undefined
      */
     public function getAuthors(): array
     {
         return $this->data['authors'] ?? [];
     }
 
     /**
-     * @return array
+     * Returns the extra configuration section declared in the Composer file.
+     *
+     * This method SHALL return the value of the `extra` key when present.
+     * If the key is absent, the method MUST return an empty array.
+     *
+     * @return array the extra configuration data, or an empty array when
+     *               undefined
      */
     public function getExtra(): array
     {
         return $this->data['extra'] ?? [];
     }
 
     /**
-     * @param string $type
+     * Returns the autoload configuration for the requested autoload type.
+     *
+     * This method SHALL inspect the `autoload` section and return the
+     * nested configuration for the requested type, such as `psr-4`.
+     * When the `autoload` section or the requested type is not defined,
+     * the method MUST return an empty array.
+     *
+     * @param string $type The autoload mapping type to retrieve. This
+     *                     defaults to `psr-4`.
      *
-     * @return array
+     * @return array the autoload configuration for the requested type,
+     *               or an empty array when unavailable
      */
     public function getAutoload(string $type = 'psr-4'): array
     {

src/Console/CommandLoader/DevToolsCommandLoader.php

@@ -28,6 +28,12 @@
 final class DevToolsCommandLoader extends ContainerCommandLoader
 {
     /**
+     * Constructs the DevToolsCommandLoader.
+     *
+     * This constructor initializes the command loader by scanning the Command directory for classes that are
+     * instantiable and have the AsCommand attribute.
+     * It builds a command map associating command names with their respective classes.
+     *
      * @param Finder $finder
      * @param ContainerInterface $container
      */
@@ -37,6 +43,8 @@ public function __construct(Finder $finder, ContainerInterface $container)
     }
 
     /**
+     * Builds a command map by scanning the Command directory for classes that are instantiable and have the AsCommand attribute.
+     *
      * @param Finder $finder
      *
      * @return array

src/Console/DevTools.php

@@ -33,6 +33,9 @@
  */
 final class DevTools extends ComposerApplication
 {
+    /**
+     * @var ContainerInterface holds the static container instance for global access within the DevTools context
+     */
     private static ?ContainerInterface $container = null;
 
     /**

src/Psr/Clock/SystemClock.php

@@ -21,9 +21,16 @@
 use DateTimeImmutable;
 use Psr\Clock\ClockInterface;
 
+/**
+ * A clock implementation that returns the current system time.
+ *
+ * This class implements the ClockInterface and provides a method to get the current time as a DateTimeImmutable object.
+ */
 final class SystemClock implements ClockInterface
 {
     /**
+     * Returns the current time as a DateTimeImmutable Object.
+     *
      * @return DateTimeImmutable
      */
     public function now(): DateTimeImmutable

src/ServiceProvider/DevToolsServiceProvider.php

@@ -62,6 +62,12 @@
 use function DI\create;
 use function DI\get;
 
+/**
+ * DevToolsServiceProvider registers the services provided by this package.
+ *
+ * This class implements the ServiceProviderInterface from the PHP-Interop container package,
+ * allowing it to be used with any compatible dependency injection container.
+ */
 final class DevToolsServiceProvider implements ServiceProviderInterface
 {
     /**