fix(FunctionCommentSniff): Improve detection of comments not belonging to the function (#2621450)

coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php

@@ -84,9 +84,14 @@ class Drupal_Sniffs_Commenting_FunctionCommentSniff implements PHP_CodeSniffer_S
         $find   = PHP_CodeSniffer_Tokens::$methodPrefixes;
         $find[] = T_WHITESPACE;
 
-        $commentEnd = $phpcsFile->findPrevious($find, ($stackPtr - 1), null, true);
-        if ($tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG
-            && $tokens[$commentEnd]['code'] !== T_COMMENT
+        $commentEnd       = $phpcsFile->findPrevious($find, ($stackPtr - 1), null, true);
+        $beforeCommentEnd = $phpcsFile->findPrevious(PHP_CodeSniffer_Tokens::$emptyTokens, ($commentEnd - 1), null, true);
+        if (($tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG
+            && $tokens[$commentEnd]['code'] !== T_COMMENT)
+            || ($beforeCommentEnd !== false
+            // If there is something more on the line than just the comment then the
+            // comment does not belong to the function.
+            && $tokens[$beforeCommentEnd]['line'] === $tokens[$commentEnd]['line'])
         ) {
             $fix = $phpcsFile->addFixableError('Missing function doc comment', $stackPtr, 'Missing');
             if ($fix === true) {

coder_sniffer/Drupal/Test/Commenting/FunctionCommentUnitTest.inc

@@ -392,3 +392,18 @@ class Test2 extends AbstractTest {
 function test31($a, $b) {
 
 }
+
+class PostcodeAnywhere_Interactive_Find {
+
+   private $UserName; //The username associated with the Royal Mail license (not required for click licenses).
+   private $Data; //Holds the results of the query
+
+   function PostcodeAnywhere_Interactive_Find($Key, $SearchTerm, $PreferredLanguage, $Filter, $UserName)
+   {
+      $this->Key = $Key;
+      $this->SearchTerm = $SearchTerm;
+      $this->PreferredLanguage = $PreferredLanguage;
+      $this->Filter = $Filter;
+      $this->UserName = $UserName;
+   }
+}

coder_sniffer/Drupal/Test/Commenting/FunctionCommentUnitTest.inc.fixed

@@ -404,3 +404,30 @@ class Test2 extends AbstractTest {
 function test31($a, $b) {
 
 }
+
+/**
+ *
+ */
+class PostcodeAnywhere_Interactive_Find {
+
+  /**
+   * The username associated with the Royal Mail license (not required for click licenses).
+   */
+  private $UserName;
+  /**
+   * Holds the results of the query.
+   */
+  private $Data;
+
+  /**
+   *
+   */
+  public function PostcodeAnywhere_Interactive_Find($Key, $SearchTerm, $PreferredLanguage, $Filter, $UserName) {
+    $this->Key = $Key;
+    $this->SearchTerm = $SearchTerm;
+    $this->PreferredLanguage = $PreferredLanguage;
+    $this->Filter = $Filter;
+    $this->UserName = $UserName;
+  }
+
+}

coder_sniffer/Drupal/Test/Commenting/FunctionCommentUnitTest.php

@@ -59,6 +59,7 @@ class Drupal_Sniffs_Commenting_FunctionCommentUnitTest extends CoderSniffUnitTes
                         371 => 1,
                         389 => 2,
                         390 => 2,
+                        401 => 1,
                        );
             case 'FunctionCommentUnitTest.1.inc':
                 return array();