Allow skipping of class annotations.

Author: dereuromark

docs/Annotations.md

@@ -334,6 +334,17 @@ verify the changes. This feature is still in a very alpha phase.
 Note that you can prevent removal (just as updating) by adding a comment to your annotation.
 That will skip any attempt to remove it.
 
+## Skipping annotations for a class
+Sometimes you are extending another class, in that case you can use `@inherit` tag as class doc block to skip annotating here.
+
+In this case this table extend the Images table, but use the same `protected $_entityClass = Image::class;`, so skipping:
+```php
+/**
+ * @inheritdoc
+ */
+class CustomImagesTable extends ImagesTable ...
+```
+
 ## Continuous integration support
 The tool can also be run like the coding standards check in your CI. 
 This way no annotation can be forgotten, when making PRs for your project.

src/Annotator/AbstractAnnotator.php

@@ -225,6 +225,9 @@ protected function _annotate($path, $content, array $annotations) {
 
 		$closeTagIndex = $file->findPrevious(T_DOC_COMMENT_CLOSE_TAG, $classIndex - 1, $prevCode);
 		$this->_resetCounter();
+		if ($closeTagIndex && $this->shouldSkip($file, $closeTagIndex)) {
+			return false;
+		}
 		if ($closeTagIndex && !$this->isInlineDocBlock($file, $closeTagIndex)) {
 			$newContent = $this->_appendToExistingDocBlock($file, $closeTagIndex, $annotations);
 		} else {
@@ -550,6 +553,27 @@ protected function isInlineDocBlock(File $file, $docBlockCloseIndex) {
 		return $tokens[$docBlockCloseIndex]['line'] === $tokens[$docBlockOpenIndex]['line'];
 	}
 
+	/**
+	 * @param \PHP_CodeSniffer\Files\File $file
+	 * @param int $docBlockCloseIndex
+	 * @return bool
+	 */
+	protected function shouldSkip(File $file, $docBlockCloseIndex) {
+		$tokens = $file->getTokens();
+		$docBlockOpenIndex = $tokens[$docBlockCloseIndex]['comment_opener'];
+
+		for ($i = $docBlockOpenIndex + 1; $i < $docBlockCloseIndex; $i++) {
+			if ($tokens[$i]['code'] !== T_DOC_COMMENT_TAG) {
+				continue;
+			}
+			if ($tokens[$i]['content'] === '@inheritdoc') {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
 	/**
 	 * @param array $usedModels
 	 * @param string $content

tests/TestCase/Annotator/ModelAnnotatorTest.php

@@ -167,6 +167,29 @@ public function testAnnotateExistingReplace() {
 		$this->assertTextContains('  -> 1 annotation updated', $output);
 	}
 
+	/**
+	 * @return void
+	 */
+	public function testAnnotateSkip() {
+		$annotator = $this->_getAnnotatorMock([]);
+
+		$expectedContent = str_replace("\r\n", "\n", file_get_contents(TEST_FILES . 'Model/Table/SkipMeTable.php'));
+		$callback = function($value) use ($expectedContent) {
+			$value = str_replace(["\r\n", "\r"], "\n", $value);
+			if ($value !== $expectedContent) {
+				$this->_displayDiff($expectedContent, $value);
+			}
+			return $value === $expectedContent;
+		};
+		$annotator->expects($this->never())->method('_storeFile')->with($this->anything(), $this->callback($callback));
+
+		$path = APP . 'Model/Table/SkipMeTable.php.php';
+		$annotator->annotate($path);
+
+		$output = (string)$this->out->output();
+		$this->assertSame('', $output);
+	}
+
 	/**
 	 * @return void
 	 */

tests/test_app/src/Model/Table/SkipMeTable.php

@@ -0,0 +1,22 @@
+<?php
+namespace App\Model\Table;
+
+use Cake\ORM\Table;
+
+/**
+ * @inheritDoc
+ */
+class SkipMeTable extends Table {
+
+	/**
+	 * @param array $config
+	 * @return void
+	 */
+	public function initialize(array $config) {
+		parent::initialize($config);
+
+		$this->table('wheels');
+		$this->belongsTo('Cars');
+	}
+
+}

tests/test_files/Model/Table/SkipMeTable.php

@@ -0,0 +1,22 @@
+<?php
+namespace App\Model\Table;
+
+use Cake\ORM\Table;
+
+/**
+ * @inheritDoc
+ */
+class SkipMeTable extends Table {
+
+	/**
+	 * @param array $config
+	 * @return void
+	 */
+	public function initialize(array $config) {
+		parent::initialize($config);
+
+		$this->table('wheels');
+		$this->belongsTo('Cars');
+	}
+
+}