Ignore line length limit in docblocks

Note: This does not apply to inline docs.

We should _perhaps_ limit this to things like Behat @Given/When/Then
but there are other times when this is not helpful too.

Author: andrewnicols

moodle/Sniffs/Files/LineLengthSniff.php

@@ -24,8 +24,8 @@
 
 namespace MoodleHQ\MoodleCS\moodle\Sniffs\Files;
 
+use MoodleHQ\MoodleCS\moodle\Util\Docblocks;
 use PHP_CodeSniffer\Standards\Generic\Sniffs\Files\LineLengthSniff as GenericLineLengthSniff;
-use PHP_CodeSniffer\Sniffs\Sniff;
 use PHP_CodeSniffer\Files\File;
 
 class LineLengthSniff extends GenericLineLengthSniff
@@ -40,6 +40,17 @@ public function process(File $file, $stackptr) {
         if (strpos($file->getFilename(), DIRECTORY_SEPARATOR . 'lang' . DIRECTORY_SEPARATOR) !== false) {
             return;
         }
+
         parent::process($file, $stackptr);
     }
+
+    protected function checkLineLength($phpcsFile, $tokens, $stackPtr) {
+        // Ignore lines that are part of a docblock.
+        // We may extend this to only ignore certain tags in the future.
+        if (Docblocks::getStartOfCurrentDocblock($phpcsFile, $stackPtr) !== null) {
+            return;
+        }
+
+        parent::checkLineLength($phpcsFile, $tokens, $stackPtr);
+    }
 }

moodle/Tests/Sniffs/Files/LineLengthSniffTest.php

@@ -0,0 +1,75 @@
+<?php
+
+// This file is part of Moodle - https://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 <https://www.gnu.org/licenses/>.
+
+namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\Commenting;
+
+use MoodleHQ\MoodleCS\moodle\Tests\MoodleCSBaseTestCase;
+
+/**
+ * Test the MissingDocblockSniff sniff.
+ *
+ * @copyright  2024 onwards Andrew Lyons <andrew@nicols.co.uk>
+ * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * @covers \MoodleHQ\MoodleCS\moodle\Sniffs\Files\LineLengthSniff
+ */
+class LineLengthSniffTest extends MoodleCSBaseTestCase
+{
+    /**
+     * @dataProvider fixtureProvider
+     */
+    public function testSniffWithFixtures(
+        string $fixture,
+        ?string $fixturePath,
+        array $errors,
+        array $warnings
+    ): void {
+        // xdebug_break();
+        $this->setStandard('moodle');
+        $this->setSniff('moodle.Files.LineLength');
+        $this->setFixture(
+            sprintf("%s/fixtures/LineLength/%s.php", __DIR__, $fixture),
+            $fixturePath,
+        );
+        $this->setErrors($errors);
+        $this->setWarnings($warnings);
+
+        $this->verifyCsResults();
+    }
+
+    public static function fixtureProvider(): array {
+        $cases = [
+            [
+                'fixture' => 'langfile',
+                'fixturePath' => '/lang/en/assignfeedback_editpdf.php',
+                'errors' => [],
+                'warnings' => [],
+            ],
+            [
+                'fixture' => 'standard',
+                'fixturePath' => null,
+                'errors' => [
+                    13 => 'Line exceeds maximum limit of 180 characters; contains 182 characters',
+                ],
+                'warnings' => [
+
+                ],
+            ],
+        ];
+        return $cases;
+    }
+}

moodle/Tests/Sniffs/Files/fixtures/LineLength/langfile.php

@@ -0,0 +1,3 @@
+<?php
+
+$string['example_of_a_very_long_string_name'] = 'This is an example of a very long string with a vey long name which combined will exceed the maximum lenth of your typical Moodle coding style';

moodle/Tests/Sniffs/Files/fixtures/LineLength/standard.php

@@ -0,0 +1,16 @@
+<?php
+
+class Example
+{
+    /**
+     * This is an example of a very long string within the docblock of a class.
+     *
+     * Checks that all actiities in the specified section are hidden. You need to be in the course page. It can be used being logged as a student and as a teacher on editing mode.
+     *
+     * @Given /^I change the name of the "(?P<activity_name_string>(?:[^"]|\\")*)" activity name to "(?P<new_name_string>(?:[^"]|\\")*)"$/
+     */
+    public function i_change_names(): void {
+        // This is also a really stupidly long comment but this one is not allowed to be over long. The reason we accept long docblock strings but not long comments string is because
+        // docblocks are used as code.
+    }
+}