Add PHPDoc

Author: coisa

src/Command/AbstractCommand.php

@@ -30,12 +30,24 @@
 
 use function Safe\getcwd;
 
+/**
+ * Provides a base configuration and common utilities for Composer commands.
+ * Extending classes MUST rely on this base abstraction to interact with the console
+ * application gracefully, and SHALL adhere to the expected return types for commands.
+ */
 abstract class AbstractCommand extends BaseCommand
 {
+    /**
+     * @var Filesystem The filesystem instance used for file operations. This property MUST be utilized for interacting with the file system securely.
+     */
     protected readonly Filesystem $filesystem;
 
     /**
-     * @param Filesystem|null $filesystem
+     * Constructs a new AbstractCommand instance.
+     *
+     * The method MAY accept a Filesystem instance; if omitted, it SHALL instantiate a new one.
+     *
+     * @param Filesystem|null $filesystem the filesystem utility to use
      */
     public function __construct(?Filesystem $filesystem = null)
     {
@@ -45,10 +57,16 @@ public function __construct(?Filesystem $filesystem = null)
     }
 
     /**
-     * @param Process $command
-     * @param OutputInterface $output
+     * Executes a given system process gracefully and outputs its buffer.
+     *
+     * The method MUST execute the provided command ensuring the output is channeled
+     * to the OutputInterface. It SHOULD leverage TTY if supported. If the process
+     * fails, it MUST return `self::FAILURE`; otherwise, it SHALL return `self::SUCCESS`.
+     *
+     * @param Process $command the configured process instance to run
+     * @param OutputInterface $output the output interface to log warnings or results
      *
-     * @return int
+     * @return int the status code of the command execution
      */
     protected function runProcess(Process $command, OutputInterface $output): int
     {
@@ -86,7 +104,12 @@ protected function runProcess(Process $command, OutputInterface $output): int
     }
 
     /**
-     * @return string
+     * Retrieves the current working directory of the application.
+     *
+     * The method MUST return the initial working directory defined by the application.
+     * If not available, it SHALL fall back to the safe current working directory.
+     *
+     * @return string the absolute path to the current working directory
      */
     protected function getCurrentWorkingDirectory(): string
     {
@@ -95,9 +118,14 @@ protected function getCurrentWorkingDirectory(): string
     }
 
     /**
-     * @param string $relativePath
+     * Computes the absolute path for a given relative or absolute path.
      *
-     * @return string
+     * This method MUST return the exact path if it is already absolute.
+     * If relative, it SHALL make it absolute relying on the current working directory.
+     *
+     * @param string $relativePath the path to evaluate or resolve
+     *
+     * @return string the resolved absolute path
      */
     protected function getAbsolutePath(string $relativePath): string
     {
@@ -109,10 +137,15 @@ protected function getAbsolutePath(string $relativePath): string
     }
 
     /**
-     * @param string $filename
-     * @param bool $force
+     * Determines the correct absolute path to a configuration file.
+     *
+     * The method MUST attempt to resolve the configuration file locally in the working directory.
+     * If absent and not forced, it SHALL provide the default equivalent from the package itself.
      *
-     * @return string
+     * @param string $filename the name of the configuration file
+     * @param bool $force determines whether to bypass fallback and forcefully return the local file path
+     *
+     * @return string the resolved absolute path to the configuration file
      */
     protected function getConfigFile(string $filename, bool $force = false): string
     {
@@ -128,11 +161,16 @@ protected function getConfigFile(string $filename, bool $force = false): string
     }
 
     /**
-     * @param InputInterface $input
-     * @param string $commandName
-     * @param OutputInterface $output
+     * Configures and executes a registered console command by name.
+     *
+     * The method MUST look up the command from the application and run it. It SHALL ignore generic
+     * validation errors and route the custom input and output correctly.
      *
-     * @return int
+     * @param string $commandName the name of the required command
+     * @param array|InputInterface $input the input arguments or array definition
+     * @param OutputInterface $output the interface for buffering output
+     *
+     * @return int the status code resulting from the dispatched command
      */
     protected function runCommand(string $commandName, array|InputInterface $input, OutputInterface $output): int
     {
@@ -149,7 +187,12 @@ protected function runCommand(string $commandName, array|InputInterface $input,
     }
 
     /**
-     * @return array
+     * Retrieves configured PSR-4 namespaces from the composer configuration.
+     *
+     * This method SHALL parse the underlying `composer.json` using the Composer instance,
+     * and MUST provide an empty array if no specific paths exist.
+     *
+     * @return array the PSR-4 namespaces mappings
      */
     protected function getPsr4Namespaces(): array
     {
@@ -161,7 +204,12 @@ protected function getPsr4Namespaces(): array
     }
 
     /**
-     * @return string
+     * Computes the human-readable title or description of the current application.
+     *
+     * The method SHOULD utilize the package description as the title, but MUST provide
+     * the raw package name as a fallback mechanism.
+     *
+     * @return string the computed title or description string
      */
     protected function getTitle(): string
     {

src/Command/CodeStyleCommand.php

@@ -23,11 +23,23 @@
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Process\Process;
 
+/**
+ * Represents the command responsible for checking and fixing code style issues.
+ * This class MUST NOT be overridden and SHALL rely on external tools like ECS and Composer Normalize.
+ */
 final class CodeStyleCommand extends AbstractCommand
 {
+    /**
+     * @var string the default configuration file used for EasyCodingStandard
+     */
     public const string CONFIG = 'ecs.php';
 
     /**
+     * Configures the current command.
+     *
+     * This method MUST define the name, description, help text, and options for the command.
+     * It SHALL register the `--fix` option to allow automatic resolutions of style issues.
+     *
      * @return void
      */
     protected function configure(): void
@@ -45,10 +57,15 @@ protected function configure(): void
     }
 
     /**
-     * @param InputInterface $input
-     * @param OutputInterface $output
+     * Executes the code style checks and fixes block.
+     *
+     * The method MUST execute `composer update --lock`, `composer normalize`, and ECS using secure processes.
+     * It SHALL return `self::SUCCESS` if all commands succeed, or `self::FAILURE` otherwise.
+     *
+     * @param InputInterface $input the input interface to retrieve options
+     * @param OutputInterface $output the output interface to log messages
      *
-     * @return int
+     * @return int the status code of the command
      */
     protected function execute(InputInterface $input, OutputInterface $output): int
     {

src/Command/DocsCommand.php

@@ -23,9 +23,18 @@
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Process\Process;
 
+/**
+ * Handles the generation of API documentation for the project.
+ * This class MUST NOT be extended and SHALL utilize phpDocumentor to accomplish its task.
+ */
 final class DocsCommand extends AbstractCommand
 {
     /**
+     * Configures the command instance.
+     *
+     * The method MUST set up the name and description. It MAY accept an optional `--target` option
+     * pointing to an alternative configuration target path.
+     *
      * @return void
      */
     protected function configure(): void
@@ -43,10 +52,15 @@ protected function configure(): void
     }
 
     /**
-     * @param InputInterface $input
-     * @param OutputInterface $output
+     * Executes the generation of the documentation files.
+     *
+     * This method MUST compile arguments based on PSR-4 namespaces to feed into phpDocumentor.
+     * It SHOULD provide feedback on generation progress, and SHALL return `self::SUCCESS` on success.
+     *
+     * @param InputInterface $input the input details for the command
+     * @param OutputInterface $output the output mechanism for logging
      *
-     * @return int
+     * @return int the final execution status code
      */
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
@@ -56,6 +70,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $this->getAbsolutePath('vendor/bin/phpdoc'),
             '--cache-folder',
             $this->getCurrentWorkingDirectory() . '/tmp/cache/phpdoc',
+            '--visibility=public,protected',
         ];
 
         $psr4Namespaces = $this->getPsr4Namespaces();
@@ -81,6 +96,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             ...$arguments,
             '--target',
             $this->getCurrentWorkingDirectory() . '/docs/wiki',
+            '--visibility=public,protected',
             '--template',
             'vendor/saggre/phpdocumentor-markdown/themes/markdown',
         ]);

src/Command/PhpDocCommand.php

@@ -27,13 +27,27 @@
 
 use function Safe\file_get_contents;
 
+/**
+ * Provides operations to inspect, lint, and repair PHPDoc comments across the project.
+ * The class MUST NOT be extended and SHALL coordinate tools like PHP-CS-Fixer and Rector.
+ */
 final class PhpDocCommand extends AbstractCommand
 {
+    /**
+     * @var string determines the template filename for docheaders
+     */
     public const string FILENAME = '.docheader';
 
+    /**
+     * @var string stores the underlying configuration file for PHP-CS-Fixer
+     */
     public const string CONFIG = '.php-cs-fixer.dist.php';
 
     /**
+     * Configures the PHPDoc command.
+     *
+     * This method MUST securely configure the expected inputs, such as the `--fix` option.
+     *
      * @return void
      */
     protected function configure(): void
@@ -51,10 +65,15 @@ protected function configure(): void
     }
 
     /**
-     * @param InputInterface $input
-     * @param OutputInterface $output
+     * Executes the PHPDoc checks and rectifications.
      *
-     * @return int
+     * The method MUST ensure the `.docheader` template is present. It SHALL then invoke
+     * PHP-CS-Fixer and Rector. If both succeed, it MUST return `self::SUCCESS`.
+     *
+     * @param InputInterface $input the command input parameters
+     * @param OutputInterface $output the system output handler
+     *
+     * @return int the success or failure state
      */
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
@@ -69,10 +88,15 @@ protected function execute(InputInterface $input, OutputInterface $output): int
     }
 
     /**
-     * @param InputInterface $input
-     * @param OutputInterface $output
+     * Executes the PHP-CS-Fixer checks internally.
+     *
+     * The method SHOULD run in dry-run mode unless the fix flag is explicitly provided.
+     * It MUST return an integer describing the exit code.
+     *
+     * @param InputInterface $input the parsed console inputs
+     * @param OutputInterface $output the configured outputs
      *
-     * @return mixed
+     * @return int the status result of the underlying process
      */
     private function runPhpCsFixer(InputInterface $input, OutputInterface $output): int
     {
@@ -94,10 +118,15 @@ private function runPhpCsFixer(InputInterface $input, OutputInterface $output):
     }
 
     /**
-     * @param InputInterface $input
-     * @param OutputInterface $output
+     * Runs Rector to insert missing method block comments automatically.
      *
-     * @return mixed
+     * The method MUST apply the `AddMissingMethodPhpDocRector` constraint locally.
+     * It SHALL strictly return an integer denoting success or failure.
+     *
+     * @param InputInterface $input the incoming console parameters
+     * @param OutputInterface $output the outgoing console display
+     *
+     * @return int the code indicating the process result
      */
     private function runRector(InputInterface $input, OutputInterface $output): int
     {
@@ -122,7 +151,12 @@ private function runRector(InputInterface $input, OutputInterface $output): int
     }
 
     /**
-     * @param OutputInterface $output
+     * Creates the missing document header configuration file if needed.
+     *
+     * The method MUST query the local filesystem. If the file is missing, it SHOULD copy
+     * the tool template into the root folder.
+     *
+     * @param OutputInterface $output the logger where missing capabilities are announced
      *
      * @return void
      */

src/Command/RefactorCommand.php

@@ -23,11 +23,23 @@
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Process\Process;
 
+/**
+ * Provides functionality to execute automated code refactoring using Rector.
+ * This class MUST NOT be extended and SHALL encapsulate the logic for Rector invocation.
+ */
 final class RefactorCommand extends AbstractCommand
 {
+    /**
+     * @var string the default Rector configuration file
+     */
     public const string CONFIG = 'rector.php';
 
     /**
+     * Configures the refactor command options and description.
+     *
+     * This method MUST define the expected `--fix` option. It SHALL configure the command name
+     * and descriptions accurately.
+     *
      * @return void
      */
     protected function configure(): void
@@ -45,10 +57,15 @@ protected function configure(): void
     }
 
     /**
-     * @param InputInterface $input
-     * @param OutputInterface $output
+     * Executes the refactoring process securely.
+     *
+     * The method MUST execute Rector securely via `Process`. It SHALL use dry-run mode
+     * unless the `--fix` option is specified. It MUST return `self::SUCCESS` or `self::FAILURE`.
+     *
+     * @param InputInterface $input the input interface to retrieve arguments properly
+     * @param OutputInterface $output the output interface to log outputs
      *
-     * @return int
+     * @return int the status code denoting success or failure
      */
     protected function execute(InputInterface $input, OutputInterface $output): int
     {