Polish project capability PHPDocs

Author: coisa

src/Project/ProjectCapabilities.php

@@ -20,11 +20,13 @@
 namespace FastForward\DevTools\Project;
 
 /**
- * Describes the documentation, testing, and wiki surfaces exposed by the current repository.
+ * Captures which documentation, testing, and wiki surfaces are available for the current repository.
  */
 final readonly class ProjectCapabilities
 {
     /**
+     * Creates a repository capability snapshot for reporting and documentation commands.
+     *
      * @param list<string> $apiDirectories project-relative directories that contain autoloaded PHP API source
      * @param string|null $defaultPackageName the default package name derived from Composer namespaces when available
      * @param bool $hasGuideDirectory whether the configured guide directory exists
@@ -42,87 +44,87 @@ public function __construct(
     ) {}
 
     /**
-     * @return list<string>
+     * Returns the project-relative directories that expose autoloaded PHP API source.
      */
     public function getApiDirectories(): array
     {
         return $this->apiDirectories;
     }
 
     /**
-     * @return string|null
+     * Returns the default API package name when one can be derived from Composer namespaces.
      */
     public function getDefaultPackageName(): ?string
     {
         return $this->defaultPackageName;
     }
 
     /**
-     * @return bool
+     * Detects whether the configured guide directory exists.
      */
     public function hasGuideDirectory(): bool
     {
         return $this->hasGuideDirectory;
     }
 
     /**
-     * @return bool
+     * Detects whether the configured tests directory exists.
      */
     public function hasTestsPath(): bool
     {
         return $this->hasTestsPath;
     }
 
     /**
-     * @return bool
+     * Detects whether the configured wiki target exists.
      */
     public function hasWikiTarget(): bool
     {
         return $this->hasWikiTarget;
     }
 
     /**
-     * @return bool
+     * Detects whether the repository exposes PHP source files outside generated and vendor areas.
      */
     public function hasPhpSourceFiles(): bool
     {
         return $this->hasPhpSourceFiles;
     }
 
     /**
-     * @return bool
+     * Detects whether the repository exposes autoloaded PHP API source.
      */
     public function canGenerateApiDocumentation(): bool
     {
         return [] !== $this->apiDirectories;
     }
 
     /**
-     * @return bool
+     * Detects whether the repository can generate guides, API documentation, or both.
      */
     public function canGenerateDocs(): bool
     {
         return $this->hasGuideDirectory || $this->canGenerateApiDocumentation();
     }
 
     /**
-     * @return bool
+     * Detects whether metrics generation has PHP source or test inputs to analyse.
      */
     public function canGenerateMetrics(): bool
     {
         return $this->hasTestsPath || $this->hasPhpSourceFiles;
     }
 
     /**
-     * @return bool
+     * Detects whether wiki generation can render API documentation into the configured wiki target.
      */
     public function canGenerateWiki(): bool
     {
         return $this->hasWikiTarget && $this->canGenerateApiDocumentation();
     }
 
     /**
-     * @return bool
+     * Detects whether the repository has enough PHP surface to justify running tests.
      */
     public function canRunTests(): bool
     {

src/Project/ProjectCapabilitiesResolver.php

@@ -39,20 +39,22 @@
     private const array API_AUTOLOAD_TYPES = ['psr-4', 'psr-0', 'classmap'];
 
     /**
-     * @param ComposerJsonInterface $composer
-     * @param FilesystemInterface $filesystem
+     * Creates a capability resolver backed by Composer autoload metadata and filesystem checks.
+     *
+     * @param ComposerJsonInterface $composer the composer.json accessor for autoload metadata
+     * @param FilesystemInterface $filesystem the filesystem used to resolve project-relative paths
      */
     public function __construct(
         private ComposerJsonInterface $composer,
         private FilesystemInterface $filesystem,
     ) {}
 
     /**
-     * @param string $testsPath
-     * @param string $guideDirectory
-     * @param string $wikiTarget
+     * Resolves which documentation, testing, and wiki surfaces are available for the current repository.
      *
-     * @return ProjectCapabilities
+     * @param string $testsPath the project-relative tests directory to inspect
+     * @param string $guideDirectory the project-relative guide directory to inspect
+     * @param string $wikiTarget the project-relative wiki output target to inspect
      */
     public function resolve(
         string $testsPath = ProjectCapabilitiesResolverInterface::DEFAULT_TESTS_PATH,
@@ -72,7 +74,9 @@ public function resolve(
     }
 
     /**
-     * @param array<string, mixed> $psr4Autoload
+     * Resolves the default API package name from the first PSR-4 namespace entry when available.
+     *
+     * @param array<string, mixed> $psr4Autoload the PSR-4 autoload map from composer.json
      */
     private function resolveDefaultPackageName(array $psr4Autoload): ?string
     {
@@ -86,6 +90,8 @@ private function resolveDefaultPackageName(array $psr4Autoload): ?string
     }
 
     /**
+     * Resolves project-relative API directories exposed by Composer autoload configuration.
+     *
      * @return list<string>
      */
     private function resolveApiDirectories(): array
@@ -108,9 +114,9 @@ private function resolveApiDirectories(): array
     }
 
     /**
-     * @param string $path
+     * Resolves a Composer autoload path into a project-relative API directory when it exists.
      *
-     * @return string|null
+     * @param string $path the Composer autoload path candidate
      */
     private function resolveRelativeApiDirectory(string $path): ?string
     {
@@ -128,7 +134,9 @@ private function resolveRelativeApiDirectory(string $path): ?string
     }
 
     /**
-     * @param array<string, mixed> $autoload
+     * Flattens Composer autoload path definitions into a normalized list of non-empty paths.
+     *
+     * @param array<string, mixed> $autoload the Composer autoload section to normalize
      *
      * @return list<string>
      */

src/Project/ProjectCapabilitiesResolverInterface.php

@@ -24,18 +24,27 @@
  */
 interface ProjectCapabilitiesResolverInterface
 {
+    /**
+     * @var string the default project-relative test directory checked by repository capability discovery
+     */
     public const string DEFAULT_TESTS_PATH = './tests';
 
+    /**
+     * @var string the default project-relative guide directory checked by repository capability discovery
+     */
     public const string DEFAULT_GUIDE_DIRECTORY = 'docs';
 
+    /**
+     * @var string the default project-relative wiki target used for generated API wiki output
+     */
     public const string DEFAULT_WIKI_TARGET = '.github/wiki';
 
     /**
-     * @param string $testsPath
-     * @param string $guideDirectory
-     * @param string $wikiTarget
+     * Resolves which documentation, testing, and wiki surfaces are available for the current repository.
      *
-     * @return ProjectCapabilities
+     * @param string $testsPath the project-relative tests directory to inspect
+     * @param string $guideDirectory the project-relative guide directory to inspect
+     * @param string $wikiTarget the project-relative wiki output target to inspect
      */
     public function resolve(
         string $testsPath = self::DEFAULT_TESTS_PATH,