From db843722f24728db5ba95e6480e7b3234e4b478a Mon Sep 17 00:00:00 2001
From: Andrew Nicols <andrew@nicols.co.uk>
Date: Thu, 20 Jun 2024 13:06:05 +0800
Subject: [PATCH] Ignore anonymous class docblocks if they have a parent

There's usually little need to document an anonymous class when it is
part of another method.
---
 CHANGELOG.md                                  |  1 +
 .../Commenting/MissingDocblockSniff.php       |  5 ++++
 .../Commenting/MissingDocblockSniffTest.php   | 25 +++++++++++++++++++
 .../entire_anonymous_class.php                |  5 ++++
 .../entire_anonymous_class_documented.php     |  8 ++++++
 .../nested_anonymous_class.php                | 15 +++++++++++
 6 files changed, 59 insertions(+)
 create mode 100644 moodle/Tests/Sniffs/Commenting/fixtures/MissingDocblock/entire_anonymous_class.php
 create mode 100644 moodle/Tests/Sniffs/Commenting/fixtures/MissingDocblock/entire_anonymous_class_documented.php
 create mode 100644 moodle/Tests/Sniffs/Commenting/fixtures/MissingDocblock/nested_anonymous_class.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 76eb967..8b013d1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,7 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt
 ## [Unreleased]
 ### Changed
 - 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.
 
 ## [v3.4.9] - 2024-06-19
 ### Fixed
diff --git a/moodle/Sniffs/Commenting/MissingDocblockSniff.php b/moodle/Sniffs/Commenting/MissingDocblockSniff.php
index 82bc55f..e2903ce 100644
--- a/moodle/Sniffs/Commenting/MissingDocblockSniff.php
+++ b/moodle/Sniffs/Commenting/MissingDocblockSniff.php
@@ -83,6 +83,11 @@ protected function processScopes(File $phpcsFile, int $stackPtr): void {
                 // Skip methods of classes, traits and interfaces.
                 continue;
             }
+            if ($token['code'] === T_ANON_CLASS && !empty($token['conditions'])) {
+                // Skip anonymous classes.
+                continue;
+            }
+
             $artifactCount++;
 
             if ($token['code'] === T_FUNCTION) {
diff --git a/moodle/Tests/Sniffs/Commenting/MissingDocblockSniffTest.php b/moodle/Tests/Sniffs/Commenting/MissingDocblockSniffTest.php
index a46ccb5..22bf815 100644
--- a/moodle/Tests/Sniffs/Commenting/MissingDocblockSniffTest.php
+++ b/moodle/Tests/Sniffs/Commenting/MissingDocblockSniffTest.php
@@ -199,6 +199,31 @@ public static function docblockCorrectnessProvider(): array {
                 'warnings' => [
                 ],
             ],
+            'Anonymous class as only class in file (documented)' => [
+                'fixture' => 'entire_anonymous_class_documented',
+                'fixtureFilename' => null,
+                'errors' => [
+                ],
+                'warnings' => [
+                ],
+            ],
+            'Anonymous class as only class in file (undocumented)' => [
+                'fixture' => 'entire_anonymous_class',
+                'fixtureFilename' => null,
+                'errors' => [
+                    5 => 'Missing docblock for class anonymous class',
+                ],
+                'warnings' => [
+                ],
+            ],
+            'Anonymous class as member of method' => [
+                'fixture' => 'nested_anonymous_class',
+                'fixtureFilename' => null,
+                'errors' => [
+                ],
+                'warnings' => [
+                ],
+            ],
         ];
 
         if (version_compare(PHP_VERSION, '8.0.0') >= 0) {
diff --git a/moodle/Tests/Sniffs/Commenting/fixtures/MissingDocblock/entire_anonymous_class.php b/moodle/Tests/Sniffs/Commenting/fixtures/MissingDocblock/entire_anonymous_class.php
new file mode 100644
index 0000000..05d18c6
--- /dev/null
+++ b/moodle/Tests/Sniffs/Commenting/fixtures/MissingDocblock/entire_anonymous_class.php
@@ -0,0 +1,5 @@
+<?php
+
+namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\PHPUnit;
+
+return new class() extends \stdClass {};
diff --git a/moodle/Tests/Sniffs/Commenting/fixtures/MissingDocblock/entire_anonymous_class_documented.php b/moodle/Tests/Sniffs/Commenting/fixtures/MissingDocblock/entire_anonymous_class_documented.php
new file mode 100644
index 0000000..68bf39d
--- /dev/null
+++ b/moodle/Tests/Sniffs/Commenting/fixtures/MissingDocblock/entire_anonymous_class_documented.php
@@ -0,0 +1,8 @@
+<?php
+
+namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\PHPUnit;
+
+/**
+ * Class level docblock.
+ */
+return new class() extends \stdClass {};
diff --git a/moodle/Tests/Sniffs/Commenting/fixtures/MissingDocblock/nested_anonymous_class.php b/moodle/Tests/Sniffs/Commenting/fixtures/MissingDocblock/nested_anonymous_class.php
new file mode 100644
index 0000000..fac3353
--- /dev/null
+++ b/moodle/Tests/Sniffs/Commenting/fixtures/MissingDocblock/nested_anonymous_class.php
@@ -0,0 +1,15 @@
+<?php
+
+namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\PHPUnit;
+
+/**
+ * Class level docblock.
+ */
+class class_with_anonymous_class_in_method {
+    /**
+     * Documented method.
+     */
+    public function test(): string {
+        return new class() extends \stdClass {};
+    }
+}