From d4330c5f9c15847b5fce8308cedf14e310f85c83 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Wed, 1 Nov 2023 13:00:03 +0100
Subject: [PATCH 1/3] Commenting/FileComment: add notes about parse errors to a
 few test files

---
 Yoast/Tests/Commenting/FileCommentUnitTest.14.inc | 3 +++
 Yoast/Tests/Commenting/FileCommentUnitTest.7.inc  | 2 +-
 Yoast/Tests/Commenting/FileCommentUnitTest.8.inc  | 2 ++
 3 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.14.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.14.inc
index 2c68b4a1..f36845e5 100644
--- a/Yoast/Tests/Commenting/FileCommentUnitTest.14.inc
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.14.inc
@@ -2,6 +2,9 @@
 /**
  * File Comment for a file WITH a namespace. This should be flagged as unnecessary.
  *
+ * Note: a namespace _within_ a scoped `declare` statement is a parse error, but that's not the concern of this sniff.
+ * Scoped strict_types declare statements are also not allowed.
+ *
  * @package Some\Package
  */
 
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.7.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.7.inc
index 23a5bd25..77f049e4 100644
--- a/Yoast/Tests/Commenting/FileCommentUnitTest.7.inc
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.7.inc
@@ -1,6 +1,6 @@
 <?php
 /**
- * File Comment for a file with the namespace keyword, but no namespace.
+ * File Comment for a file with the namespace keyword, but no namespace (= parse error).
  *
  * @package    Some\Package
  * @subpackage Something\Else
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.8.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.8.inc
index 6f270ee1..935b7047 100644
--- a/Yoast/Tests/Commenting/FileCommentUnitTest.8.inc
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.8.inc
@@ -4,5 +4,7 @@ namespace;
 
 /**
  * Class docblock. A namespace keyword without actual namespace defaults to global namespace, so a file comment is needed, but missing.
+ *
+ * Note: an unscoped namespace declaration without a name is a parse error, but that's not the concern of this sniff.
  */
 class Testing {}

From 347caf6b6ac10573821752d3b3073ce3bbf76c8b Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sat, 14 Oct 2023 07:44:33 +0200
Subject: [PATCH 2/3] Commenting/FileComment: add extra tests

... for a few edge cases previously not covered by tests.
---
 Yoast/Tests/Commenting/FileCommentUnitTest.21.inc | 2 ++
 Yoast/Tests/Commenting/FileCommentUnitTest.22.inc | 8 ++++++++
 Yoast/Tests/Commenting/FileCommentUnitTest.php    | 6 ++++++
 3 files changed, 16 insertions(+)
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.21.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.22.inc

diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.21.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.21.inc
new file mode 100644
index 00000000..f2d31979
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.21.inc
@@ -0,0 +1,2 @@
+<!-- Edge case test: empty file, fall through to parent sniff and flag for missing file comment.
+<?php
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.22.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.22.inc
new file mode 100644
index 00000000..96fa1d3e
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.22.inc
@@ -0,0 +1,8 @@
+<?php
+
+namespace\functionCall();
+
+/**
+ * Class docblock. No namespace (above is operator, not declaration), file comment is needed, but missing.
+ */
+class Testing {}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.php b/Yoast/Tests/Commenting/FileCommentUnitTest.php
index 8a0d6ab6..d0fcd2a2 100644
--- a/Yoast/Tests/Commenting/FileCommentUnitTest.php
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.php
@@ -26,10 +26,16 @@ public function getErrorList( string $testFile = '' ): array {
 			case 'FileCommentUnitTest.8.inc':
 			case 'FileCommentUnitTest.10.inc':
 			case 'FileCommentUnitTest.12.inc':
+			case 'FileCommentUnitTest.22.inc':
 				return [
 					1 => 1,
 				];
 
+			case 'FileCommentUnitTest.21.inc':
+				return [
+					2 => 1,
+				];
+
 			default:
 				return [];
 		}

From 7eb259ef6bc1eaadb03167ed899315b54dbf7e6d Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Fri, 22 Sep 2023 01:38:43 +0200
Subject: [PATCH 3/3] Commenting/FileComment: allow for namespaced procedural
 files

The `Yoast.Commenting.FileComment` sniff would previously demand a file docblock for non-namespaced files and recommend a file docblock be removed for namespaced files.

This is all well and good for namespaced files containing an OO declaration, where the OO structure will generally have a docblock, but for namespaced procedural files, this might mean the file will end up having no documentation whatsoever, which could be counter-productive.

While namespaced procedural files are not that common in the Yoast codebases, typically a PHPUnit bootstrap file may be a namespaced procedural file.

This commit updates the sniff to only recommend removing the file docblock if the file _also_ contains a named OO declaration.

For namespaced files which don't contain an OO declaration, the file docblock will still be allowed (but not required) and will no longer be flagged as unnecessary.
If a docblock is found in such a file, it will be checked for compliance with file docblock rules like any other file docblock.

Includes ample tests.
Includes updated XML documentation.
---
 Yoast/Docs/Commenting/FileCommentStandard.xml |  2 +-
 Yoast/Sniffs/Commenting/FileCommentSniff.php  | 81 ++++++++++++-------
 .../Commenting/FileCommentUnitTest.13.inc     |  2 +-
 .../Commenting/FileCommentUnitTest.14.inc     |  2 +-
 .../Commenting/FileCommentUnitTest.20.inc     |  3 +-
 .../Commenting/FileCommentUnitTest.23.inc     | 20 +++++
 .../Commenting/FileCommentUnitTest.24.inc     |  9 +++
 .../Commenting/FileCommentUnitTest.25.inc     | 11 +++
 .../Commenting/FileCommentUnitTest.26.inc     | 15 ++++
 .../Commenting/FileCommentUnitTest.27.inc     | 22 +++++
 .../Commenting/FileCommentUnitTest.28.inc     |  6 ++
 .../Commenting/FileCommentUnitTest.29.inc     |  8 ++
 .../Commenting/FileCommentUnitTest.3.inc      |  2 +-
 .../Commenting/FileCommentUnitTest.30.inc     | 13 +++
 .../Commenting/FileCommentUnitTest.31.inc     | 22 +++++
 .../Commenting/FileCommentUnitTest.32.inc     |  6 ++
 .../Commenting/FileCommentUnitTest.33.inc     |  8 ++
 .../Commenting/FileCommentUnitTest.34.inc     | 13 +++
 .../Commenting/FileCommentUnitTest.35.inc     | 22 +++++
 .../Commenting/FileCommentUnitTest.36.inc     |  8 ++
 .../Commenting/FileCommentUnitTest.37.inc     | 10 +++
 .../Commenting/FileCommentUnitTest.38.inc     | 22 +++++
 .../Commenting/FileCommentUnitTest.39.inc     | 19 +++++
 .../Commenting/FileCommentUnitTest.4.inc      |  2 +-
 .../Commenting/FileCommentUnitTest.40.inc     | 21 +++++
 .../Commenting/FileCommentUnitTest.5.inc      |  2 +-
 .../Tests/Commenting/FileCommentUnitTest.php  |  7 ++
 27 files changed, 324 insertions(+), 34 deletions(-)
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.23.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.24.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.25.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.26.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.27.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.28.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.29.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.30.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.31.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.32.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.33.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.34.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.35.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.36.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.37.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.38.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.39.inc
 create mode 100644 Yoast/Tests/Commenting/FileCommentUnitTest.40.inc

diff --git a/Yoast/Docs/Commenting/FileCommentStandard.xml b/Yoast/Docs/Commenting/FileCommentStandard.xml
index 41da79db..ddbae88a 100644
--- a/Yoast/Docs/Commenting/FileCommentStandard.xml
+++ b/Yoast/Docs/Commenting/FileCommentStandard.xml
@@ -5,7 +5,7 @@
     >
     <standard>
     <![CDATA[
-    A file containing a (named) namespace declaration does not need a file docblock.
+    A file containing a (named) namespace declaration and an OO declaration does not need a file docblock.
     ]]>
     </standard>
     <code_comparison>
diff --git a/Yoast/Sniffs/Commenting/FileCommentSniff.php b/Yoast/Sniffs/Commenting/FileCommentSniff.php
index 421042fb..095c0118 100644
--- a/Yoast/Sniffs/Commenting/FileCommentSniff.php
+++ b/Yoast/Sniffs/Commenting/FileCommentSniff.php
@@ -5,9 +5,13 @@
 use PHP_CodeSniffer\Files\File;
 use PHP_CodeSniffer\Standards\Squiz\Sniffs\Commenting\FileCommentSniff as Squiz_FileCommentSniff;
 use PHP_CodeSniffer\Util\Tokens;
+use PHPCSUtils\Tokens\Collections;
 
 /**
- * Namespaced files do not need a file docblock in YoastCS.
+ * Namespaced files containing an OO structure do not need a file docblock in YoastCS.
+ *
+ * For namespaced files NOT containing an OO structure, a file docblock is permitted,
+ * though not required.
  *
  * Note: Files without a namespace declaration do still need a file docblock.
  * This includes files which have a non-named namespace declaration which
@@ -23,6 +27,8 @@
  * adjustments.}}
  *
  * @since 1.2.0
+ * @since 3.0.0 Behaviour for files containing an OO structure vs without has been updated
+ *              to allow a file docblock when there is no OO structure.
  */
 final class FileCommentSniff extends Squiz_FileCommentSniff {
 
@@ -38,6 +44,9 @@ public function process( File $phpcsFile, $stackPtr ) {
 
 		$tokens = $phpcsFile->getTokens();
 
+		/*
+		 * Check if the file is namespaced. If not, fall through to the parent sniff.
+		 */
 		$namespace_token = $stackPtr;
 		do {
 			$namespace_token = $phpcsFile->findNext( Tokens::$emptyTokens, ( $namespace_token + 1 ), null, true );
@@ -77,39 +86,57 @@ public function process( File $phpcsFile, $stackPtr ) {
 			return parent::process( $phpcsFile, $stackPtr );
 		}
 
+		/*
+		 * As of here, we know we are in a namespaced file.
+		 */
+
 		$comment_start = $phpcsFile->findNext( \T_WHITESPACE, ( $stackPtr + 1 ), $namespace_token, true );
 
-		if ( $comment_start !== false && $tokens[ $comment_start ]['code'] === \T_DOC_COMMENT_OPEN_TAG ) {
-
-			// Respect phpcs:disable comments in the file docblock.
-			$ignore = false;
-			if ( $phpcsFile->config->annotations === true && isset( $tokens[ $comment_start ]['comment_closer'] ) ) {
-				for ( $i = ( $comment_start + 1 ); $i < $tokens[ $comment_start ]['comment_closer']; $i++ ) {
-					if ( $tokens[ $i ]['code'] !== \T_PHPCS_DISABLE ) {
-						continue;
-					}
-
-					if ( empty( $tokens[ $i ]['sniffCodes'] ) === true
-						|| isset( $tokens[ $i ]['sniffCodes']['Yoast'] ) === true
-						|| isset( $tokens[ $i ]['sniffCodes']['Yoast.Commenting'] ) === true
-						|| isset( $tokens[ $i ]['sniffCodes']['Yoast.Commenting.FileComment'] ) === true
-						|| isset( $tokens[ $i ]['sniffCodes']['Yoast.Commenting.FileComment.Unnecessary'] ) === true
-					) {
-						$ignore = true;
-						break;
-					}
+		if ( $comment_start === false || $tokens[ $comment_start ]['code'] !== \T_DOC_COMMENT_OPEN_TAG ) {
+			// No file comment found, we're good.
+			return ( $phpcsFile->numTokens + 1 );
+		}
+
+		// Respect phpcs:disable comments in the file docblock.
+		if ( $phpcsFile->config->annotations === true && isset( $tokens[ $comment_start ]['comment_closer'] ) ) {
+			for ( $i = ( $comment_start + 1 ); $i < $tokens[ $comment_start ]['comment_closer']; $i++ ) {
+				if ( $tokens[ $i ]['code'] !== \T_PHPCS_DISABLE ) {
+					continue;
 				}
-			}
 
-			if ( $ignore === false ) {
-				$phpcsFile->addWarning(
-					'A file containing a (named) namespace declaration does not need a file docblock',
-					$comment_start,
-					'Unnecessary'
-				);
+				if ( empty( $tokens[ $i ]['sniffCodes'] ) === true
+					|| isset( $tokens[ $i ]['sniffCodes']['Yoast'] ) === true
+					|| isset( $tokens[ $i ]['sniffCodes']['Yoast.Commenting'] ) === true
+					|| isset( $tokens[ $i ]['sniffCodes']['Yoast.Commenting.FileComment'] ) === true
+					|| isset( $tokens[ $i ]['sniffCodes']['Yoast.Commenting.FileComment.Unnecessary'] ) === true
+				) {
+					// Applicable disable annotation found.
+					return ( $phpcsFile->numTokens + 1 );
+				}
 			}
 		}
 
+		/*
+		 * Okay, so we have a file docblock in a namespaced file, now check if there is a named
+		 * OO structure declaration.
+		 */
+		$find = Tokens::$ooScopeTokens;
+		unset( $find[ \T_ANON_CLASS ] );
+		$hasOODeclaration = $phpcsFile->findNext( $find, $next_non_empty );
+		if ( $hasOODeclaration === false ) {
+			/*
+			 * This is a file which doesn't contain (just) an OO declaration.
+			 * If there is a file docblock, allow it and check it like any other file docblock.
+			 */
+			return parent::process( $phpcsFile, $stackPtr );
+		}
+
+		$phpcsFile->addWarning(
+			'A file containing a (named) namespace declaration does not need a file docblock',
+			$comment_start,
+			'Unnecessary'
+		);
+
 		return ( $phpcsFile->numTokens + 1 );
 	}
 }
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.13.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.13.inc
index 8d5c53fc..d73859cf 100644
--- a/Yoast/Tests/Commenting/FileCommentUnitTest.13.inc
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.13.inc
@@ -5,6 +5,6 @@ declare(strict_types=1);
 namespace Yoast\Plugin\Sub;
 
 /**
- * Class docblock. A file docblock is not needed in a namespaced file.
+ * Class docblock. A file docblock is not needed in a namespaced file containing an OO structure.
  */
 class Testing {}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.14.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.14.inc
index f36845e5..f162ac7d 100644
--- a/Yoast/Tests/Commenting/FileCommentUnitTest.14.inc
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.14.inc
@@ -1,6 +1,6 @@
 <?php
 /**
- * File Comment for a file WITH a namespace. This should be flagged as unnecessary.
+ * File Comment for a file WITH a namespace and containing an OO structure. This should be flagged as unnecessary.
  *
  * Note: a namespace _within_ a scoped `declare` statement is a parse error, but that's not the concern of this sniff.
  * Scoped strict_types declare statements are also not allowed.
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.20.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.20.inc
index bef42685..10cf1b38 100644
--- a/Yoast/Tests/Commenting/FileCommentUnitTest.20.inc
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.20.inc
@@ -1,6 +1,7 @@
 <?php
 /**
- * File Comment for a file WITH a namespace, and containing irrelevant ignore comments. This should be flagged as unnecessary.
+ * File Comment for a file WITH a namespace and containing an OO structure, and containing irrelevant ignore comments.
+ * This should be flagged as unnecessary.
  *
  * @phpcs:disable Some.Other.SniffCode
  * @phpcs:disable Yet.Another.SniffCode
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.23.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.23.inc
new file mode 100644
index 00000000..08a77c48
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.23.inc
@@ -0,0 +1,20 @@
+<?php
+/**
+ * File Comment for a file without a namespace.
+ *
+ * For the purposes of the unit test, the docblock here needs to comply with the
+ * complete Squiz file comment rules as the ruleset is not taken into account
+ * when unit testing sniffs.
+ *
+ * @package    Some\Package
+ * @subpackage Something\Else
+ * @author     Squiz Pty Ltd <products@squiz.net>
+ * @copyright  2018 Squiz Pty Ltd (ABN 77 084 670 600)
+ */
+
+/**
+ * Interface docblock.
+ */
+interface Testing {
+	public function test();
+}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.24.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.24.inc
new file mode 100644
index 00000000..e6d24487
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.24.inc
@@ -0,0 +1,9 @@
+<?php
+
+/**
+ * Interface docblock. No namespace, file comment is needed, but missing.
+ */
+interface Testing {
+	public function test();
+}
+
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.25.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.25.inc
new file mode 100644
index 00000000..76923a44
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.25.inc
@@ -0,0 +1,11 @@
+<?php
+
+namespace Yoast\Plugin\Sub;
+
+/**
+ * Interface docblock. A file docblock is not needed in a namespaced file containing an OO structure.
+ */
+interface Testing {
+	public function test();
+}
+
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.26.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.26.inc
new file mode 100644
index 00000000..c5c81abf
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.26.inc
@@ -0,0 +1,15 @@
+<?php
+/**
+ * File Comment for a file WITH a namespace and containing an OO structure. This should be flagged as unnecessary.
+ *
+ * @package Some\Package
+ */
+
+namespace Yoast\Plugin\Sub;
+
+/**
+ * Interface docblock.
+ */
+interface Testing {
+	public function test();
+}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.27.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.27.inc
new file mode 100644
index 00000000..6675e604
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.27.inc
@@ -0,0 +1,22 @@
+<?php
+/**
+ * File Comment for a file without a namespace.
+ *
+ * For the purposes of the unit test, the docblock here needs to comply with the
+ * complete Squiz file comment rules as the ruleset is not taken into account
+ * when unit testing sniffs.
+ *
+ * @package    Some\Package
+ * @subpackage Something\Else
+ * @author     Squiz Pty Ltd <products@squiz.net>
+ * @copyright  2018 Squiz Pty Ltd (ABN 77 084 670 600)
+ */
+
+/**
+ * Trait docblock.
+ */
+trait Testing {
+	public function test() {
+		echo namespace\SomeClass::$static_property; // This is not a namespace declaration, but use of the namespace operator.
+	}
+}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.28.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.28.inc
new file mode 100644
index 00000000..16d21100
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.28.inc
@@ -0,0 +1,6 @@
+<?php
+
+/**
+ * Trait docblock. No namespace, file comment is needed, but missing.
+ */
+trait Testing {}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.29.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.29.inc
new file mode 100644
index 00000000..4dba74f1
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.29.inc
@@ -0,0 +1,8 @@
+<?php
+
+namespace Yoast\Plugin\Sub;
+
+/**
+ * Trait docblock. A file docblock is not needed in a namespaced file containing an OO structure.
+ */
+trait Testing {}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.3.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.3.inc
index 66201a03..4358c5dc 100644
--- a/Yoast/Tests/Commenting/FileCommentUnitTest.3.inc
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.3.inc
@@ -3,6 +3,6 @@
 namespace Yoast\Plugin\Sub;
 
 /**
- * Class docblock. A file docblock is not needed in a namespaced file.
+ * Class docblock. A file docblock is not needed in a namespaced file containing an OO structure.
  */
 class Testing {}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.30.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.30.inc
new file mode 100644
index 00000000..9516c46c
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.30.inc
@@ -0,0 +1,13 @@
+<?php
+/**
+ * File Comment for a file WITH a namespace and containing an OO structure. This should be flagged as unnecessary.
+ *
+ * @package Some\Package
+ */
+
+namespace Yoast\Plugin\Sub;
+
+/**
+ * Trait docblock.
+ */
+trait Testing {}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.31.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.31.inc
new file mode 100644
index 00000000..4d93346e
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.31.inc
@@ -0,0 +1,22 @@
+<?php
+/**
+ * File Comment for a file without a namespace.
+ *
+ * For the purposes of the unit test, the docblock here needs to comply with the
+ * complete Squiz file comment rules as the ruleset is not taken into account
+ * when unit testing sniffs.
+ *
+ * @package    Some\Package
+ * @subpackage Something\Else
+ * @author     Squiz Pty Ltd <products@squiz.net>
+ * @copyright  2018 Squiz Pty Ltd (ABN 77 084 670 600)
+ */
+
+/**
+ * Enum docblock.
+ */
+enum Testing {
+	public function test() {
+		echo namespace\SomeClass::$static_property; // This is not a namespace declaration, but use of the namespace operator.
+	}
+}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.32.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.32.inc
new file mode 100644
index 00000000..1a6d7308
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.32.inc
@@ -0,0 +1,6 @@
+<?php
+
+/**
+ * Enum docblock. No namespace, file comment is needed, but missing.
+ */
+enum Testing {}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.33.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.33.inc
new file mode 100644
index 00000000..7221e0b9
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.33.inc
@@ -0,0 +1,8 @@
+<?php
+
+namespace Yoast\Plugin\Sub;
+
+/**
+ * Enum docblock. A file docblock is not needed in a namespaced file containing an OO structure.
+ */
+enum Testing {}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.34.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.34.inc
new file mode 100644
index 00000000..1c7586f3
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.34.inc
@@ -0,0 +1,13 @@
+<?php
+/**
+ * File Comment for a file WITH a namespace and containing an OO structure. This should be flagged as unnecessary.
+ *
+ * @package Some\Package
+ */
+
+namespace Yoast\Plugin\Sub;
+
+/**
+ * Enum docblock.
+ */
+enum Testing {}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.35.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.35.inc
new file mode 100644
index 00000000..05b6f147
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.35.inc
@@ -0,0 +1,22 @@
+<?php
+/**
+ * File Comment for a file without a namespace and without OO structure.
+ *
+ * For the purposes of the unit test, the docblock here needs to comply with the
+ * complete Squiz file comment rules as the ruleset is not taken into account
+ * when unit testing sniffs.
+ *
+ * @package    Some\Package
+ * @subpackage Something\Else
+ * @author     Squiz Pty Ltd <products@squiz.net>
+ * @copyright  2018 Squiz Pty Ltd (ABN 77 084 670 600)
+ */
+
+do_something();
+
+/**
+ * Function docblock.
+ */
+function test() {
+	echo namespace\SomeClass::$static_property; // This is not a namespace declaration, but use of the namespace operator.
+}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.36.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.36.inc
new file mode 100644
index 00000000..0066f145
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.36.inc
@@ -0,0 +1,8 @@
+<?php
+
+/**
+ * Function docblock. No namespace, file comment is needed, but missing.
+ */
+function test() {}
+
+do_something();
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.37.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.37.inc
new file mode 100644
index 00000000..8811aec8
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.37.inc
@@ -0,0 +1,10 @@
+<?php
+
+namespace Yoast\Plugin\Sub;
+
+do_something();
+
+/**
+ * Function docblock. A file docblock is not needed in a namespaced file, but also not forbidden if the file doesn't contain an OO structure.
+ */
+function testing() {}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.38.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.38.inc
new file mode 100644
index 00000000..9c6f994c
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.38.inc
@@ -0,0 +1,22 @@
+<?php
+/**
+ * File Comment for a file WITH a namespace, but NOT containing an OO structure. This should NOT be flagged as unnecessary.
+ *
+ * For the purposes of the unit test, the docblock here needs to comply with the
+ * complete Squiz file comment rules as the ruleset is not taken into account
+ * when unit testing sniffs.
+ *
+ * @package    Some\Package
+ * @subpackage Something\Else
+ * @author     Squiz Pty Ltd <products@squiz.net>
+ * @copyright  2018 Squiz Pty Ltd (ABN 77 084 670 600)
+ */
+
+namespace Yoast\Plugin\Sub;
+
+use Ab\C;
+
+/**
+ * Function docblock.
+ */
+function test() {}
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.39.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.39.inc
new file mode 100644
index 00000000..310a38d7
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.39.inc
@@ -0,0 +1,19 @@
+<?php
+/**
+ * File Comment for a file WITH a namespace, but NOT containing a named OO structure. This should NOT be flagged as unnecessary.
+ *
+ * For the purposes of the unit test, the docblock here needs to comply with the
+ * complete Squiz file comment rules as the ruleset is not taken into account
+ * when unit testing sniffs.
+ *
+ * @package    Some\Package
+ * @subpackage Something\Else
+ * @author     Squiz Pty Ltd <products@squiz.net>
+ * @copyright  2018 Squiz Pty Ltd (ABN 77 084 670 600)
+ */
+
+namespace Yoast\Plugin\Sub;
+
+use Ab\C;
+
+$anon = new class extends C {};
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.4.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.4.inc
index 3108a255..0b705f1a 100644
--- a/Yoast/Tests/Commenting/FileCommentUnitTest.4.inc
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.4.inc
@@ -1,6 +1,6 @@
 <?php
 /**
- * File Comment for a file WITH a namespace. This should be flagged as unnecessary.
+ * File Comment for a file WITH a namespace and containing an OO structure. This should be flagged as unnecessary.
  *
  * @package Some\Package
  */
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.40.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.40.inc
new file mode 100644
index 00000000..182d3fe4
--- /dev/null
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.40.inc
@@ -0,0 +1,21 @@
+<?php
+/**
+ * File Comment for a file WITH a namespace, but NOT containing a named OO structure. This should NOT be flagged as unnecessary.
+ *
+ * For the purposes of the unit test, the docblock here needs to comply with the
+ * complete Squiz file comment rules as the ruleset is not taken into account
+ * when unit testing sniffs.
+ *
+ * @package    Some\Package
+ * @subpackage Something\Else
+ * @author     Squiz Pty Ltd <products@squiz.net>
+ * @copyright  2018 Squiz Pty Ltd (ABN 77 084 670 600)
+ */
+
+namespace Yoast\Plugin\Sub;
+
+use Ab\C;
+
+$closure = function() {
+	return new C();
+};
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.5.inc b/Yoast/Tests/Commenting/FileCommentUnitTest.5.inc
index 39ff51e2..be522035 100644
--- a/Yoast/Tests/Commenting/FileCommentUnitTest.5.inc
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.5.inc
@@ -3,7 +3,7 @@
 namespace Yoast\Plugin\Sub {
 
 	/**
-	 * Class docblock. A file docblock is not needed in a namespaced file, even when it contains scoped namespaces.
+	 * Class docblock. A file docblock is not needed in a namespaced file containing an OO structure, even when it contains scoped namespaces.
 	 */
 	class Testing {}
 }
diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.php b/Yoast/Tests/Commenting/FileCommentUnitTest.php
index d0fcd2a2..e2fcb468 100644
--- a/Yoast/Tests/Commenting/FileCommentUnitTest.php
+++ b/Yoast/Tests/Commenting/FileCommentUnitTest.php
@@ -27,6 +27,10 @@ public function getErrorList( string $testFile = '' ): array {
 			case 'FileCommentUnitTest.10.inc':
 			case 'FileCommentUnitTest.12.inc':
 			case 'FileCommentUnitTest.22.inc':
+			case 'FileCommentUnitTest.24.inc':
+			case 'FileCommentUnitTest.28.inc':
+			case 'FileCommentUnitTest.32.inc':
+			case 'FileCommentUnitTest.36.inc':
 				return [
 					1 => 1,
 				];
@@ -54,6 +58,9 @@ public function getWarningList( string $testFile = '' ): array {
 			case 'FileCommentUnitTest.6.inc':
 			case 'FileCommentUnitTest.14.inc':
 			case 'FileCommentUnitTest.20.inc':
+			case 'FileCommentUnitTest.26.inc':
+			case 'FileCommentUnitTest.30.inc':
+			case 'FileCommentUnitTest.34.inc':
 				return [
 					2 => 1,
 				];