Ensure we stop looking for file phpdoc block asap

Previously, we were allowing the getDocTagFromOpenTag()
method to advance too much when looking for file phpdoc
blocks. Now we stop as soon as any of the stop tokens is found.

Note that this case is very edge one, only reproducible when
there are lots of missing class/function phpdoc block, causing
some other phpdoc block to be picked.

In any case, I think that it's perfectly ok to shortcut the
search that way, it can save us some precious iterations.

Fixes moodlehq#172

CHANGELOG.md

@@ -10,6 +10,9 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt
 - The `moodle.NamingConventions.ValidFunctionName` sniff will now ignore errors on methods employing the `#[\Override]` attribute.
 - The `moodle.Commenting.MissingDocblock` sniff no longer warns about missing docs on non-global anonymous classes, for example those written as an instance class in a unit test.
 
+### Fixed
+- Fixed an edge case leading to the file phpdoc block being incorrectly detected by various sniffs.
+
 ## [v3.4.9] - 2024-06-19
 ### Fixed
 - Fixed a recent regression by allowing to the `moodle.Files.BoilerplateComment` sniff to contain "extra" consecutive comment lines immediately after the official boilerplate ends.

moodle/Tests/Util/DocblocksTest.php

@@ -33,7 +33,7 @@
  */
 class DocblocksTest extends MoodleCSBaseTestCase
 {
-    public function testgetDocBlockPointer(): void {
+    public function testGetDocBlockPointer(): void {
         $phpcsConfig = new Config();
         $phpcsRuleset = new Ruleset($phpcsConfig);
         $phpcsFile = new \PHP_CodeSniffer\Files\LocalFile(

moodle/Tests/Util/fixtures/docblocks/none.php

@@ -17,4 +17,9 @@
 namespace MoodleHQ\MoodleCS\moodle\Tests;
 
 class example {
+
+    public function get_something() {
+        /** @var int $variable */
+        $variable = 1;
+        return $variable;
 }

moodle/Util/Docblocks.php

@@ -256,6 +256,11 @@ protected static function getDocTagFromOpenTag(
         ];
 
         while ($stackPtr = $phpcsFile->findNext($ignore, ($stackPtr + 1), null, true)) {
+            // If we have arrived to a stop token, and haven't found the file docblock yet, then there isn't one.
+            if (in_array($tokens[$stackPtr]['code'], $stopAtTypes)) {
+                return null;
+            }
+
             if ($tokens[$stackPtr]['code'] === T_NAMESPACE || $tokens[$stackPtr]['code'] === T_USE) {
                 $stackPtr = $phpcsFile->findNext(T_SEMICOLON, $stackPtr + 1);
                 continue;