Merge pull request #155 from coenjacobs/enforce-docblocks-complexity

Enforce docblocks complexity via code checks

.github/workflows/main.yml

@@ -77,3 +77,20 @@ jobs:
           cache-to: type=gha,mode=max
       - name: Run mess detector
         run: docker compose run --rm actions-tester composer test:phpmd
+  doc-check:
+    runs-on: ubuntu-latest
+    name: Documentation check
+    steps:
+      - name: Setup Docker buildx
+        uses: docker/setup-buildx-action@v2
+      - uses: actions/checkout@v4
+      - name: Build Docker image
+        id: build-and-push
+        uses: docker/build-push-action@v4
+        with:
+          context: "{{defaultContext}}"
+          push: false
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      - name: Run doc check
+        run: docker compose run --rm actions-tester composer test:docs

composer.json

@@ -41,14 +41,16 @@
         "symfony/finder": "^5.4",
         "dealerdirect/phpcodesniffer-composer-installer": "^1.0",
         "phpcompatibility/php-compatibility": "dev-develop",
-        "phpmd/phpmd": "^2.15"
+        "phpmd/phpmd": "^2.15",
+        "niels-de-blaauw/php-doc-check": "^0.4.0"
     },
     "scripts": {
         "test": [
             "@test:lint",
             "@test:phpunit",
             "@test:phpstan",
-            "@test:phpmd"
+            "@test:phpmd",
+            "@test:docs"
         ],
         "test:lint": [
             "composer validate",
@@ -62,6 +64,9 @@
         ],
         "test:phpmd": [
             "./vendor/bin/phpmd src ansi phpmd.xml.dist"
+        ],
+        "test:docs": [
+            "./vendor/bin/php-doc-check src"
         ]
     }
 }

src/Composer/Autoload/Autoloader.php

@@ -17,5 +17,12 @@ public function getOutputDir(string $basePath, string $autoloadPath): string;
      * @return array<string,SplFileInfo>
      */
     public function getFiles(FilesHandler $files): array;
+    /**
+     * Returns the intended target path of a file, where it should be moved by
+     * the Mover class. This requires access to the Mozart configuration, for it
+     * to determine the target directory. This is done by checking the paths
+     * that are being registered for this autoloader, to see if they can be
+     * matched with the full path name of the provided file.
+     */
     public function getTargetFilePath(SplFileInfo $file): string;
 }

src/Composer/Autoload/NamespaceAutoloader.php

@@ -80,6 +80,9 @@ public function getFiles(FilesHandler $fileHandler): array
         return $filesToMove;
     }
 
+    /**
+     * @inheritdoc
+     */
     public function getTargetFilePath(SplFileInfo $file): string
     {
         $suffix = '';

src/Config/Autoload.php

@@ -10,6 +10,12 @@ class Autoload
     /** @var array<Autoloader> */
     public array $autoloaders = [];
 
+    /**
+     * Loads the autoloaders provided in the loaded composer.json file, which is
+     * then passed to this method as a stdClass. It registers each autoloader,
+     * which are then used to access the paths to read and replace contents of
+     * files that these autoloaders allow access to.
+     */
     public function setupAutoloaders(stdClass $autoloadData, Package $package): void
     {
         $autoloaders = [];

src/Config/Classmap.php

@@ -74,6 +74,9 @@ public function getFiles(FilesHandler $fileHandler): array
         return $filesToMove;
     }
 
+    /**
+     * @inheritdoc
+     */
     public function getTargetFilePath(SplFileInfo $file): string
     {
         $suffix = '';

src/Config/Package.php

@@ -85,6 +85,13 @@ public function getDependencies(): array
         return $this->dependencies;
     }
 
+    /**
+     * Loads and registers all dependencies of this package, by checking the
+     * require-object of the composer.json file of this package. Each package
+     * listed as a dependency is then loaded and registered as being a
+     * dependency of this package. Also flags this package for having its
+     * dependencies already loaded, so it doesn't duplicate dependencies.
+     */
     public function loadDependencies(PackageFinder $finder): void
     {
         if ($this->dependenciesLoaded) {

src/Mover.php

@@ -106,6 +106,11 @@ public function movePackages($packages): void
         $this->deleteEmptyDirs();
     }
 
+    /**
+     * Moves each file for each autoloader, for the provided package. Each
+     * package will only be moved once, to prevent duplicates, so the package
+     * name is registered at the end of the method.
+     */
     private function movePackage(Package $package): void
     {
         if (!$this->shouldPackageBeMoved($package)) {

src/PackageFinder.php

@@ -21,6 +21,12 @@ public function setConfig(Mozart $config): void
         $this->config = $config;
     }
 
+    /**
+     * Returns a Package object for the package based on the provided slug (in
+     * vendor/package format). The data of the package is loaded if a valid
+     * installed package could be found based on the slug, which is then being
+     * used to read the composer.json file of the package.
+     */
     public function getPackageBySlug(string $slug): ?Package
     {
         /**
@@ -54,6 +60,9 @@ public function getPackageBySlug(string $slug): ?Package
     }
 
     /**
+     * Returns Package objects which are loaded based on the provided array of
+     * slugs (in vendor/package format).
+     *
      * @param string[] $slugs
      * @return Package[]
      */

src/Replacer.php

@@ -81,6 +81,10 @@ public function getReplacerByAutoloader(Autoloader $autoloader): ReplacerInterfa
         return $replacer;
     }
 
+    /**
+     * Fetches the files or directories to perform a replace action on, based
+     * on the provided autoloader, for the provided package.
+     */
     public function replacePackageByAutoloader(Package $package, Autoloader $autoloader): void
     {
         if ($this->config->isExcludedPackage($package)) {
@@ -105,6 +109,11 @@ public function replacePackageByAutoloader(Package $package, Autoloader $autoloa
         }
     }
 
+    /**
+     * Replaces all occurances of previously replaced classes, in the provided
+     * directory. This to ensure that each package has its parents package
+     * classes also replaced in its own files.
+     */
     public function replaceParentClassesInDirectory(string $directory): void
     {
         if (count($this->replacedClasses)===0) {