Allow phpdoc blocks before "return new class extends" code

Mostly used by coverage info anon classes, but there may be
other cases, that sort of construction is allowed to have an
inline phpdoc block.

Covered with tests.

Author: stronk7

moodle/Sniffs/Commenting/InlineCommentSniff.php

@@ -115,6 +115,12 @@ public function process(File $phpcsFile, $stackPtr) {
                 return;
             }
 
+            // Allow phpdoc block before "return new class extends" expressions,
+            // we use those anon classes in places like coverage.php files.
+            if ($this->is_return_new_class_extends($phpcsFile, $stackPtr)) {
+                return;
+            }
+
             // Allow phpdoc before define() token (see CONTRIB-4150).
             if ($tokens[$nextToken]['code'] == T_STRING and $tokens[$nextToken]['content'] == 'define') {
                 return;
@@ -515,5 +521,45 @@ public function process(File $phpcsFile, $stackPtr) {
 
     }//end process()
 
+    /**
+     * This looks if there is a valid "return new class extends" expression allowed to have phpdoc block.
+     *
+     * @param File $file The file being scanned.
+     * @param int $pointer The position in the stack.
+     * @return bool true if is an allowed to have phpdoc block return new class code.
+     */
+    protected function is_return_new_class_extends(File $file, $pointer) {
+
+        $ignoredtokens = Tokens::$emptyTokens;
+
+        $tokens = $file->getTokens();
+
+        // Detect 'return'.
+        $pointer = $file->findNext($ignoredtokens, $pointer + 1, null, true);
+        if ($tokens[$pointer]['code'] !== T_RETURN) {
+            return false;
+        }
+
+        // Detect 'new'.
+        $pointer = $file->findNext($ignoredtokens, $pointer + 1, null, true);
+        if ($tokens[$pointer]['code'] !== T_NEW) {
+            return false;
+        }
+
+        // Detect 'class'.
+        $pointer = $file->findNext($ignoredtokens, $pointer + 1, null, true);
+        if ($tokens[$pointer]['code'] !== T_ANON_CLASS) {
+            return false;
+        }
+
+        // Detect 'extends'.
+        $pointer = $file->findNext($ignoredtokens, $pointer + 1, null, true);
+        if ($tokens[$pointer]['code'] !== T_EXTENDS) {
+            return false;
+        }
+
+        // Found a valid "return new class extends" expression, phpdoc block allowed.
+        return true;
+    }// end is_return_new_class_extends()
 
 }//end class

moodle/tests/fixtures/moodle_comenting_inlinecomment.php

@@ -113,3 +113,19 @@ final function afunction() {}
 foreach ($cms as $something) {
     echo 'This is a test';
 }
+
+// Allow phpdoc before "return new class extends" expressions.
+/** This is a phpdoc block */
+return new class extends xxxx {}
+
+// But don't allow it before other expressions.
+/** This is a phpdoc block */
+return new stdClass();
+/** This is a phpdoc block */
+return new class {}
+/** This is a phpdoc block */
+return class extends xxxx {}
+/** This is a phpdoc block */
+new class testphpdoc {}
+/** This is a phpdoc block */
+return new class implements something {}

moodle/tests/moodlestandard_test.php

@@ -92,7 +92,13 @@ public function test_moodle_commenting_inlinecomment() {
            91 => '\'$variable\' does not match next code line \'lets_execute_it...\'',
            94 => 1,
           102 => '\'$cm\' does not match next list() variables @Source: moodle.Commenting.InlineComment.TypeHintingList',
-          112 => '\'$cm\' does not match next foreach() as variable @Source: moodle.Commenting.InlineComment.TypeHintingFor'));
+          112 => '\'$cm\' does not match next foreach() as variable @Source: moodle.Commenting.InlineComment.TypeHintingFor',
+          118 => 0,
+          122 => 1,
+          124 => 1,
+          126 => 1,
+          128 => 1,
+          130 => 1));
         $this->set_warnings(array(
             4 => 0,
             6 => array(null, 'Commenting.InlineComment.InvalidEndChar'),
@@ -107,7 +113,9 @@ public function test_moodle_commenting_inlinecomment() {
            71 => 3,
            75 => 2,
            77 => 1,
-           79 => 1));
+           79 => 1,
+          118 => 0,
+          122 => 0));
 
         // Let's do all the hard work!
         $this->verify_cs_results();

tests/behat/ui.feature

@@ -21,7 +21,7 @@ Feature: Codechecker UI works as expected
       | local/codechecker/version.php           | Well done!                     | Invalid path   |
       | local/codechecker/moodle/tests/fixtures | Files found: 0                 | Invalid path   |
       | local/codechecker/tests/                | local_codechecker_testcase.php | Invalid path   |
-      | local/codechecker/tests/                | Files found: 1                 | Invalid path   |
+      | local/codechecker/tests/                | Files found: 2                 | Invalid path   |
       | local/codechecker/tests/                | Well done!                     | Invalid path   |
       | admin/index.php                         | Files found: 1                 | Invalid path   |
       | admin/index.php                         | Total:                         | Well done!     |