From 4a5a07d1e5b1921f617886305f57672b3e26d344 Mon Sep 17 00:00:00 2001 From: Coen Jacobs Date: Thu, 19 Sep 2024 11:30:39 +0200 Subject: [PATCH 1/3] Enforce docblocks for complex methods by set thresholds --- composer.json | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/composer.json b/composer.json index 2170597c..140cc2fb 100644 --- a/composer.json +++ b/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" ] } } From 58e0644e7f157c051c676105382080ba1f716bb1 Mon Sep 17 00:00:00 2001 From: Coen Jacobs Date: Thu, 19 Sep 2024 13:38:18 +0200 Subject: [PATCH 2/3] Added enforced docblocks for complex methods --- src/Composer/Autoload/Autoloader.php | 7 +++++++ src/Composer/Autoload/NamespaceAutoloader.php | 3 +++ src/Config/Autoload.php | 6 ++++++ src/Config/Classmap.php | 3 +++ src/Config/Package.php | 7 +++++++ src/Mover.php | 5 +++++ src/PackageFinder.php | 9 +++++++++ src/Replacer.php | 9 +++++++++ 8 files changed, 49 insertions(+) diff --git a/src/Composer/Autoload/Autoloader.php b/src/Composer/Autoload/Autoloader.php index 06ea8f90..92a10ebf 100644 --- a/src/Composer/Autoload/Autoloader.php +++ b/src/Composer/Autoload/Autoloader.php @@ -17,5 +17,12 @@ public function getOutputDir(string $basePath, string $autoloadPath): string; * @return array */ 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; } diff --git a/src/Composer/Autoload/NamespaceAutoloader.php b/src/Composer/Autoload/NamespaceAutoloader.php index 071b5650..fab3d286 100644 --- a/src/Composer/Autoload/NamespaceAutoloader.php +++ b/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 = ''; diff --git a/src/Config/Autoload.php b/src/Config/Autoload.php index 617519d0..e6a0cddc 100644 --- a/src/Config/Autoload.php +++ b/src/Config/Autoload.php @@ -10,6 +10,12 @@ class Autoload /** @var array */ 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 = []; diff --git a/src/Config/Classmap.php b/src/Config/Classmap.php index 4788f3d2..5826db59 100644 --- a/src/Config/Classmap.php +++ b/src/Config/Classmap.php @@ -74,6 +74,9 @@ public function getFiles(FilesHandler $fileHandler): array return $filesToMove; } + /** + * @inheritdoc + */ public function getTargetFilePath(SplFileInfo $file): string { $suffix = ''; diff --git a/src/Config/Package.php b/src/Config/Package.php index 5e4dece2..9794c2e5 100644 --- a/src/Config/Package.php +++ b/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) { diff --git a/src/Mover.php b/src/Mover.php index d1994c42..3c928902 100644 --- a/src/Mover.php +++ b/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)) { diff --git a/src/PackageFinder.php b/src/PackageFinder.php index a257676e..1c6e268b 100644 --- a/src/PackageFinder.php +++ b/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[] */ diff --git a/src/Replacer.php b/src/Replacer.php index ae341d60..6179bbf1 100644 --- a/src/Replacer.php +++ b/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) { From e755e61937797a736a998dc3201243e7555735a7 Mon Sep 17 00:00:00 2001 From: Coen Jacobs Date: Thu, 19 Sep 2024 13:41:33 +0200 Subject: [PATCH 3/3] Add doc check to GitHub Actions steps --- .github/workflows/main.yml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 00f7d12e..5a74b2dd 100644 --- a/.github/workflows/main.yml +++ b/.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