Remove usage of @inheritdoc (#866)

adr/0001-inheritdoc.md

@@ -0,0 +1,29 @@
+# Inheritdoc usage [(#860)](https://github.com/infection/infection/issues/860)
+
+### Decision
+
+Do not use `@inheritdoc` tags or any of its variants.
+
+
+###Status
+
+Accepted
+
+
+### Context
+
+Using `@inheritdoc` was done inconsistently across the codebase so the decision of whether we use it
+systematically or remove it systematically had to be done.
+
+A number of points:
+
+- [PHPDoc](https://docs.phpdoc.org/guides/inheritance.html) provides inheritance of the docblocks
+  by default when appropriate
+- Static analysers such as PHPStan or Psalm can do without at the time of writting
+
+Also it has a very limited value.
+
+
+### Consequences
+
+`@inheritdoc` tags and its variants must be removed when submitting pull requests.

src/Locator/RootsFileLocator.php

@@ -62,9 +62,6 @@ public function __construct(array $roots, Filesystem $filesystem)
         $this->filesystem = $filesystem;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function locate(string $fileName): string
     {
         $canonicalFileName = Path::canonicalize($fileName);
@@ -90,9 +87,6 @@ public function locate(string $fileName): string
         throw FileNotFound::fromFileName($canonicalFileName, $this->roots);
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function locateOneOf(array $fileNames): string
     {
         $file = $this->innerLocateOneOf($fileNames);
@@ -104,9 +98,6 @@ public function locateOneOf(array $fileNames): string
         return $file;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     private function innerLocateOneOf(array $fileNames): ?string
     {
         if ($fileNames === []) {

tests/phpunit/Configuration/ConfigurationFactoryTest.php

@@ -66,17 +66,11 @@ final class ConfigurationFactoryTest extends TestCase
      */
     private $configFactory;
 
-    /**
-     * {@inheritdoc}
-     */
     public static function tearDownAfterClass(): void
     {
         self::$mutators = null;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     protected function setUp(): void
     {
         $this->configFactory = new ConfigurationFactory(

tests/phpunit/Fixtures/Mutator/Fake.php

@@ -40,24 +40,15 @@
 
 final class Fake extends Mutator
 {
-    /**
-     * {@inheritdoc}
-     */
     public function __construct()
     {
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function mutate(Node $node): void
     {
         throw new \LogicException('Not expected to be called');
     }
 
-    /**
-     * {@inheritdoc}
-     */
     protected function mutatesNode(Node $node): bool
     {
         throw new \LogicException('Not expected to be called');