Don't require comments for private methods

Author: colinodell

Unleashed/Sniffs/Commenting/FunctionCommentSniff.php

@@ -12,6 +12,7 @@
 
 use PHP_CodeSniffer\Files\File;
 use PHP_CodeSniffer\Standards\PEAR\Sniffs\Commenting\FunctionCommentSniff as Sniff;
+use PHP_CodeSniffer\Util\Tokens;
 
 /**
  * Symfony standard customization to PEARs FunctionCommentSniff.
@@ -25,6 +26,80 @@
  */
 class FunctionCommentSniff extends Sniff
 {
+    /**
+     * @inheritDoc
+     */
+    public function process(File $phpcsFile, $stackPtr)
+    {
+        $tokens = $phpcsFile->getTokens();
+        $find   = Tokens::$methodPrefixes;
+        $find[] = T_WHITESPACE;
+
+        $commentEnd = $phpcsFile->findPrevious($find, ($stackPtr - 1), null, true);
+        if ($tokens[$commentEnd]['code'] === T_COMMENT) {
+            // Inline comments might just be closing comments for
+            // control structures or functions instead of function comments
+            // using the wrong comment type. If there is other code on the line,
+            // assume they relate to that code.
+            $prev = $phpcsFile->findPrevious($find, ($commentEnd - 1), null, true);
+            if ($prev !== false && $tokens[$prev]['line'] === $tokens[$commentEnd]['line']) {
+                $commentEnd = $prev;
+            }
+        }
+
+        $properties = $phpcsFile->getMethodProperties($stackPtr);
+
+        if ($tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG
+            && $tokens[$commentEnd]['code'] !== T_COMMENT
+        ) {
+            $hasComment = false;
+            $phpcsFile->recordMetric($stackPtr, 'Function has doc comment', 'no');
+            if ($properties['scope'] !== 'private') {
+                $function = $phpcsFile->getDeclarationName($stackPtr);
+                $phpcsFile->addError(
+                    'Missing doc comment for function %s()',
+                    $stackPtr,
+                    'Missing',
+                    [$function]
+                );
+                return;
+            }
+        } else {
+            $hasComment = true;
+            $phpcsFile->recordMetric($stackPtr, 'Function has doc comment', 'yes');
+        }
+
+        if ($hasComment && $tokens[$commentEnd]['code'] === T_COMMENT) {
+            $phpcsFile->addError('You must use "/**" style comments for a function comment', $stackPtr, 'WrongStyle');
+            return;
+        }
+
+        if ($hasComment && $tokens[$commentEnd]['line'] !== ($tokens[$stackPtr]['line'] - 1)) {
+            $error = 'There must be no blank lines after the function comment';
+            $phpcsFile->addError($error, $commentEnd, 'SpacingAfter');
+        }
+
+        if (!$hasComment) {
+            return;
+        }
+
+        $commentStart = $tokens[$commentEnd]['comment_opener'];
+        foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
+            if ($tokens[$tag]['content'] === '@see') {
+                // Make sure the tag isn't empty.
+                $string = $phpcsFile->findNext(T_DOC_COMMENT_STRING, $tag, $commentEnd);
+                if ($string === false || $tokens[$string]['line'] !== $tokens[$tag]['line']) {
+                    $error = 'Content missing for @see tag in function comment';
+                    $phpcsFile->addError($error, $tag, 'EmptySees');
+                }
+            }
+        }
+
+        $this->processReturn($phpcsFile, $stackPtr, $commentStart);
+        $this->processThrows($phpcsFile, $stackPtr, $commentStart);
+        $this->processParams($phpcsFile, $stackPtr, $commentStart);
+    }
+
     /**
      * Process the return comment of this function comment.
      *