A file docblock must have at least one empty newline after it (#133)

moodle/Tests/Util/DocblocksTest.php

@@ -123,6 +123,54 @@ public function testGetDocBlockClassOnly(): void {
         $this->assertCount(0, Docblocks::getMatchingDocTags($phpcsFile, $methodPointer, '@property'));
     }
 
+    /**
+     * Test that a file docblock and a class with no docblock correctly associated the docblock with the file
+     * and not the class.
+     */
+    public function testGetDocBlockClassWithoutDocblock(): void {
+        $phpcsConfig = new Config();
+        $phpcsRuleset = new Ruleset($phpcsConfig);
+        $phpcsFile = new \PHP_CodeSniffer\Files\LocalFile(
+            __DIR__ . '/fixtures/docblocks/file_followed_by_class_without_docblock.php',
+            $phpcsRuleset,
+            $phpcsConfig
+        );
+
+        $phpcsFile->process();
+        $filePointer = $phpcsFile->findNext(T_OPEN_TAG, 0);
+        $classPointer = $phpcsFile->findNext(T_CLASS, 0);
+
+        $fileDocBlock = Docblocks::getDocBlock($phpcsFile, $filePointer);
+        $this->assertNotNull($fileDocBlock);
+
+        $classDocBlock = Docblocks::getDocBlock($phpcsFile, $classPointer);
+        $this->assertNull($classDocBlock);
+    }
+
+    /**
+     * Test that a file docblock and a class with no docblock correctly associated the docblock with the file
+     * and not the class when the class has an Attribute.
+     */
+    public function testGetDocBlockClassWithAttribute(): void {
+        $phpcsConfig = new Config();
+        $phpcsRuleset = new Ruleset($phpcsConfig);
+        $phpcsFile = new \PHP_CodeSniffer\Files\LocalFile(
+            __DIR__ . '/fixtures/docblocks/file_followed_by_class_with_attribute.php',
+            $phpcsRuleset,
+            $phpcsConfig
+        );
+
+        $phpcsFile->process();
+        $filePointer = $phpcsFile->findNext(T_OPEN_TAG, 0);
+        $classPointer = $phpcsFile->findNext(T_CLASS, 0);
+
+        $fileDocBlock = Docblocks::getDocBlock($phpcsFile, $filePointer);
+        $this->assertNotNull($fileDocBlock);
+
+        $classDocBlock = Docblocks::getDocBlock($phpcsFile, $classPointer);
+        $this->assertNull($classDocBlock);
+    }
+
     /**
      * @dataProvider validTagsProvider
      */

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

@@ -0,0 +1,35 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace MoodleHQ\MoodleCS\moodle\Tests;
+
+use SomeDependency;
+
+/**
+ * Example File level docblock.
+ *
+ * @copyright  2024 Andrew Lyons <[email protected]>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+#[ExampleAttribute(
+    a: 'alpha',
+)]
+class example extends SomeDependency {
+    public static function exampleMethod() {
+        return 'example';
+    }
+}

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

@@ -0,0 +1,33 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace MoodleHQ\MoodleCS\moodle\Tests;
+
+use SomeDependency;
+
+/**
+ * Example File level docblock.
+ *
+ * @copyright  2024 Andrew Lyons <[email protected]>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+
+class example extends SomeDependency {
+    public static function exampleMethod() {
+        return 'example';
+    }
+}

moodle/Util/Docblocks.php

@@ -271,6 +271,7 @@ protected static function getDocTagFromOpenTag(
             T_INCLUDE_ONCE,
             T_REQUIRE,
             T_REQUIRE_ONCE,
+            T_ATTRIBUTE,
         ];
 
         while ($stackPtr = $phpcsFile->findNext($ignore, ($stackPtr + 1), null, true)) {
@@ -281,13 +282,15 @@ protected static function getDocTagFromOpenTag(
 
             if ($tokens[$stackPtr]['code'] === T_DOC_COMMENT_OPEN_TAG) {
                 $nextToken = $tokens[$stackPtr]['comment_closer'];
+                $closeLine = $tokens[$nextToken]['line'];
+
                 while ($nextToken = $phpcsFile->findNext(T_WHITESPACE, $nextToken + 1, null, true)) {
-                    if ($nextToken && $tokens[$nextToken]['code'] === T_ATTRIBUTE) {
-                        $nextToken = $tokens[$nextToken]['attribute_closer'] + 1;
-                        continue;
-                    }
                     if (in_array($tokens[$nextToken]['code'], $stopAtTypes)) {
-                        return null;
+                        // If the stop token is on the line immediately following the attribute or close comment
+                        // then it belongs to that stop token, and not the file.
+                        if ($tokens[$nextToken]['line'] === ($closeLine + 1)) {
+                            return null;
+                        }
                     }
                     break;
                 }