Merge branch 'skip-inheritdoc' of https://github.com/xjm/PHP_CodeSniffer

Author: gsherwood

src/Standards/Squiz/Sniffs/Commenting/FunctionCommentSniff.php

@@ -17,6 +17,13 @@
 class FunctionCommentSniff extends PEARFunctionCommentSniff
 {
 
+    /**
+     * Whether to skip inheritdoc comments.
+     *
+     * @var boolean
+     */
+    public $skipIfInheritdoc = false;
+
     /**
      * The current PHP version.
      *
@@ -40,6 +47,12 @@ protected function processReturn(File $phpcsFile, $stackPtr, $commentStart)
         $tokens = $phpcsFile->getTokens();
         $return = null;
 
+        if ($this->skipIfInheritdoc === true) {
+            if ($this->checkInheritdoc($phpcsFile, $stackPtr, $commentStart) === true) {
+                return;
+            }
+        }
+
         foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
             if ($tokens[$tag]['content'] === '@return') {
                 if ($return !== null) {
@@ -189,6 +202,12 @@ protected function processThrows(File $phpcsFile, $stackPtr, $commentStart)
     {
         $tokens = $phpcsFile->getTokens();
 
+        if ($this->skipIfInheritdoc === true) {
+            if ($this->checkInheritdoc($phpcsFile, $stackPtr, $commentStart) === true) {
+                return;
+            }
+        }
+
         foreach ($tokens[$commentStart]['comment_tags'] as $pos => $tag) {
             if ($tokens[$tag]['content'] !== '@throws') {
                 continue;
@@ -264,6 +283,12 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
 
         $tokens = $phpcsFile->getTokens();
 
+        if ($this->skipIfInheritdoc === true) {
+            if ($this->checkInheritdoc($phpcsFile, $stackPtr, $commentStart) === true) {
+                return;
+            }
+        }
+
         $params  = [];
         $maxType = 0;
         $maxVar  = 0;
@@ -695,4 +720,38 @@ protected function checkSpacingAfterParamName(File $phpcsFile, $param, $maxVar,
     }//end checkSpacingAfterParamName()
 
 
+    /**
+     * Determines whether the whole comment is an inheritdoc comment.
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile    The file being scanned.
+     * @param int                         $stackPtr     The position of the current token
+     *                                                  in the stack passed in $tokens.
+     * @param int                         $commentStart The position in the stack where the comment started.
+     *
+     * @return boolean TRUE if the docblock contains only {@inheritdoc} (case-insensitive).
+     */
+    protected function checkInheritdoc(File $phpcsFile, $stackPtr, $commentStart)
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        $allowedTokens = [
+            T_DOC_COMMENT_OPEN_TAG,
+            T_DOC_COMMENT_WHITESPACE,
+            T_DOC_COMMENT_STAR,
+        ];
+        for ($i = $commentStart; $i <= $tokens[$commentStart]['comment_closer']; $i++) {
+            if (in_array($tokens[$i]['code'], $allowedTokens) === false) {
+                $trimmedContent = strtolower(trim($tokens[$i]['content']));
+
+                if ($trimmedContent === '{@inheritdoc}') {
+                    return true;
+                } else {
+                    return false;
+                }
+            }
+        }
+
+    }//end checkInheritdoc()
+
+
 }//end class