Docs: remove redundant @package tags

`@package` tags are an arcane manner to group related files as belonging to one project. For projects using namespaces, the current recommendation is to only have `@package` tags when they have supplemental information to the namespace. As that isn't the case in YoastCS (with the exception of the non-namespaced test bootstrap file), I'm proposing to remove the `@package` tags from the YoastCS class docblocks. Along the same lines, the `@author` tag is also an outdated practice as `git blame` will work just fine, so I'm removing those too. Includes cleaning up (normalizing) the tag description alignments in the class docblocks. :point_right: reviewing with whitespace changes ignored should make it easier to see that the only real change is the removal of the package/author tags. Refs: * https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/package.html#package * https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc-tags.md#59-package
Yoast · Nov 3, 2023 · 820adfb · 820adfb
1 parent 6754fc3
commit 820adfb
Show file tree

Hide file tree

Showing 25 changed files with 38 additions and 97 deletions.
diff --git a/Yoast/Sniffs/Commenting/CodeCoverageIgnoreDeprecatedSniff.php b/Yoast/Sniffs/Commenting/CodeCoverageIgnoreDeprecatedSniff.php
@@ -10,10 +10,7 @@
  * Verifies functions which are marked as `deprecated` have a `codeCoverageIgnore` tag
  * in their docblock.
  *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- *
- * @since   1.1.0
+ * @since 1.1.0
  */
 class CodeCoverageIgnoreDeprecatedSniff implements Sniff {
 

diff --git a/Yoast/Sniffs/Commenting/CoversTagSniff.php b/Yoast/Sniffs/Commenting/CoversTagSniff.php
@@ -14,10 +14,7 @@
  * - there are no duplicate @coversNothing tags;
  * - a method does not have both a @covers as well as a @coversNothing tag.
  *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- *
- * @since   1.3.0
+ * @since 1.3.0
  */
 class CoversTagSniff implements Sniff {
 

diff --git a/Yoast/Sniffs/Commenting/FileCommentSniff.php b/Yoast/Sniffs/Commenting/FileCommentSniff.php
@@ -22,10 +22,7 @@
  * see if it's still relevant to have this sniff and if so, if the sniff needs
  * adjustments.}}
  *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- *
- * @since   1.2.0
+ * @since 1.2.0
  */
 class FileCommentSniff extends Squiz_FileCommentSniff {
 

diff --git a/Yoast/Sniffs/Commenting/TestsHaveCoversTagSniff.php b/Yoast/Sniffs/Commenting/TestsHaveCoversTagSniff.php
@@ -9,10 +9,7 @@
 /**
  * Verifies that all test functions have at least one @covers tag.
  *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- *
- * @since   1.3.0
+ * @since 1.3.0
  */
 class TestsHaveCoversTagSniff implements Sniff {
 

diff --git a/Yoast/Sniffs/Files/FileNameSniff.php b/Yoast/Sniffs/Files/FileNameSniff.php
@@ -19,9 +19,7 @@
  * - Files which don't contain an object structure, but do contain function declarations should
  *   have a "-functions" suffix.
  *
- * @package Yoast\YoastCS
- *
- * @since   0.5
+ * @since 0.5
  */
 class FileNameSniff implements Sniff {
 

diff --git a/Yoast/Sniffs/Files/TestDoublesSniff.php b/Yoast/Sniffs/Files/TestDoublesSniff.php
@@ -11,9 +11,7 @@
  * Additionally, checks that all classes in the `doubles` directory/directories
  * have `Double` or `Mock` in the class name.
  *
- * @package Yoast\YoastCS
- *
- * @since   1.0.0
+ * @since 1.0.0
  */
 class TestDoublesSniff implements Sniff {
 

diff --git a/Yoast/Sniffs/NamingConventions/NamespaceNameSniff.php b/Yoast/Sniffs/NamingConventions/NamespaceNameSniff.php
@@ -19,10 +19,7 @@
  * as well as that the levels directly translate to the (sub-)directory a file is
  * placed in.
  *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- *
- * @since   2.0.0
+ * @since 2.0.0
  */
 class NamespaceNameSniff implements Sniff {
 

diff --git a/Yoast/Sniffs/NamingConventions/ObjectNameDepthSniff.php b/Yoast/Sniffs/NamingConventions/ObjectNameDepthSniff.php
@@ -7,10 +7,7 @@
 /**
  * Check the number of words in object names declared within a namespace.
  *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- *
- * @since   2.0.0
+ * @since 2.0.0
  */
 class ObjectNameDepthSniff extends WPCS_Sniff {
 

diff --git a/Yoast/Sniffs/NamingConventions/ValidHookNameSniff.php b/Yoast/Sniffs/NamingConventions/ValidHookNameSniff.php
@@ -27,10 +27,7 @@
  *            namespace-like prefix for hooks, the `WrongPrefix` warning should be
  *            changed to an error and only namespace-like prefixes should be allowed.}
  *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- *
- * @since   2.0.0
+ * @since 2.0.0
  */
 class ValidHookNameSniff extends WPCS_ValidHookNameSniff {
 

diff --git a/Yoast/Sniffs/Tools/BrainMonkeyRaceConditionSniff.php b/Yoast/Sniffs/Tools/BrainMonkeyRaceConditionSniff.php
@@ -11,9 +11,6 @@
  * @link https://github.com/Yoast/yoastcs/issues/264
  *
  * @since 2.3.0
- *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
  */
 class BrainMonkeyRaceConditionSniff extends Sniff {
 

diff --git a/Yoast/Sniffs/WhiteSpace/FunctionSpacingSniff.php b/Yoast/Sniffs/WhiteSpace/FunctionSpacingSniff.php
@@ -13,10 +13,7 @@
  * in the global namespace as those are often wrapped in an if clause which causes
  * a fixer conflict.
  *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- *
- * @since   1.0.0
+ * @since 1.0.0
  */
 class FunctionSpacingSniff extends Squiz_FunctionSpacingSniff {
 

diff --git a/Yoast/Sniffs/Yoast/AlternativeFunctionsSniff.php b/Yoast/Sniffs/Yoast/AlternativeFunctionsSniff.php
@@ -7,10 +7,7 @@
 /**
  * Discourages the use of various functions and suggests (Yoast) alternatives.
  *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- *
- * @since   1.3.0
+ * @since 1.3.0
  */
 class AlternativeFunctionsSniff extends AbstractFunctionRestrictionsSniff {
 

diff --git a/Yoast/Tests/Commenting/CodeCoverageIgnoreDeprecatedUnitTest.php b/Yoast/Tests/Commenting/CodeCoverageIgnoreDeprecatedUnitTest.php
@@ -7,11 +7,9 @@
 /**
  * Unit test class for the CodeCoverageIgnoreDeprecated sniff.
  *
- * @package Yoast\YoastCS
+ * @since 1.1.0
  *
- * @since   1.1.0
- *
- * @covers  YoastCS\Yoast\Sniffs\Commenting\CodeCoverageIgnoreDeprecatedSniff
+ * @covers YoastCS\Yoast\Sniffs\Commenting\CodeCoverageIgnoreDeprecatedSniff
  */
 class CodeCoverageIgnoreDeprecatedUnitTest extends AbstractSniffUnitTest {
 

diff --git a/Yoast/Tests/Commenting/CoversTagUnitTest.php b/Yoast/Tests/Commenting/CoversTagUnitTest.php
@@ -7,11 +7,9 @@
 /**
  * Unit test class for the CoversTag sniff.
  *
- * @package Yoast\YoastCS
+ * @since 1.3.0
  *
- * @since   1.3.0
- *
- * @covers  YoastCS\Yoast\Sniffs\Commenting\CoversTagSniff
+ * @covers YoastCS\Yoast\Sniffs\Commenting\CoversTagSniff
  */
 class CoversTagUnitTest extends AbstractSniffUnitTest {
 

diff --git a/Yoast/Tests/Commenting/FileCommentUnitTest.php b/Yoast/Tests/Commenting/FileCommentUnitTest.php
@@ -7,11 +7,9 @@
 /**
  * Unit test class for the FileComment sniff.
  *
- * @package Yoast\YoastCS
+ * @since 1.2.0
  *
- * @since   1.2.0
- *
- * @covers  YoastCS\Yoast\Sniffs\Commenting\FileCommentSniff
+ * @covers YoastCS\Yoast\Sniffs\Commenting\FileCommentSniff
  */
 class FileCommentUnitTest extends AbstractSniffUnitTest {
 

diff --git a/Yoast/Tests/Commenting/TestsHaveCoversTagUnitTest.php b/Yoast/Tests/Commenting/TestsHaveCoversTagUnitTest.php
@@ -7,11 +7,9 @@
 /**
  * Unit test class for the TestsHaveCoversTag sniff.
  *
- * @package Yoast\YoastCS
+ * @since 1.3.0
  *
- * @since   1.3.0
- *
- * @covers  YoastCS\Yoast\Sniffs\Commenting\TestsHaveCoversTagSniff
+ * @covers YoastCS\Yoast\Sniffs\Commenting\TestsHaveCoversTagSniff
  */
 class TestsHaveCoversTagUnitTest extends AbstractSniffUnitTest {
 

diff --git a/Yoast/Tests/Files/FileNameUnitTest.php b/Yoast/Tests/Files/FileNameUnitTest.php
@@ -8,11 +8,9 @@
 /**
  * Unit test class for the FileName sniff.
  *
- * @package Yoast\YoastCS
+ * @since 0.5
  *
- * @since   0.5
- *
- * @covers  YoastCS\Yoast\Sniffs\Files\FileNameSniff
+ * @covers YoastCS\Yoast\Sniffs\Files\FileNameSniff
  */
 class FileNameUnitTest extends AbstractSniffUnitTest {
 

diff --git a/Yoast/Tests/Files/TestDoublesUnitTest.php b/Yoast/Tests/Files/TestDoublesUnitTest.php
@@ -8,11 +8,9 @@
 /**
  * Unit test class for the TestDoubles sniff.
  *
- * @package Yoast\YoastCS
+ * @since 1.0.0
  *
- * @since   1.0.0
- *
- * @covers  YoastCS\Yoast\Sniffs\Files\TestDoublesSniff
+ * @covers YoastCS\Yoast\Sniffs\Files\TestDoublesSniff
  */
 class TestDoublesUnitTest extends AbstractSniffUnitTest {
 

diff --git a/Yoast/Tests/NamingConventions/NamespaceNameUnitTest.php b/Yoast/Tests/NamingConventions/NamespaceNameUnitTest.php
@@ -8,12 +8,10 @@
 /**
  * Unit test class for the NamespaceName sniff.
  *
- * @package Yoast\YoastCS
+ * @since 2.0.0
  *
- * @since   2.0.0
- *
- * @covers  YoastCS\Yoast\Sniffs\NamingConventions\NamespaceNameSniff
- * @covers  YoastCS\Yoast\Utils\CustomPrefixesTrait
+ * @covers YoastCS\Yoast\Sniffs\NamingConventions\NamespaceNameSniff
+ * @covers YoastCS\Yoast\Utils\CustomPrefixesTrait
  */
 class NamespaceNameUnitTest extends AbstractSniffUnitTest {
 

diff --git a/Yoast/Tests/NamingConventions/ObjectNameDepthUnitTest.php b/Yoast/Tests/NamingConventions/ObjectNameDepthUnitTest.php
@@ -7,11 +7,9 @@
 /**
  * Unit test class for the ObjectNameDepth sniff.
  *
- * @package Yoast\YoastCS
+ * @since 2.0.0
  *
- * @since   2.0.0
- *
- * @covers  YoastCS\Yoast\Sniffs\NamingConventions\ObjectNameDepthSniff
+ * @covers YoastCS\Yoast\Sniffs\NamingConventions\ObjectNameDepthSniff
  */
 class ObjectNameDepthUnitTest extends AbstractSniffUnitTest {
 

diff --git a/Yoast/Tests/NamingConventions/ValidHookNameUnitTest.php b/Yoast/Tests/NamingConventions/ValidHookNameUnitTest.php
@@ -8,12 +8,10 @@
 /**
  * Unit test class for the ValidHookName sniff.
  *
- * @package Yoast\YoastCS
+ * @since 2.0.0
  *
- * @since   2.0.0
- *
- * @covers  YoastCS\Yoast\Sniffs\NamingConventions\ValidHookNameSniff
- * @covers  YoastCS\Yoast\Utils\CustomPrefixesTrait
+ * @covers YoastCS\Yoast\Sniffs\NamingConventions\ValidHookNameSniff
+ * @covers YoastCS\Yoast\Utils\CustomPrefixesTrait
  */
 class ValidHookNameUnitTest extends AbstractSniffUnitTest {
 

diff --git a/Yoast/Tests/Tools/BrainMonkeyRaceConditionUnitTest.php b/Yoast/Tests/Tools/BrainMonkeyRaceConditionUnitTest.php
@@ -7,9 +7,9 @@
 /**
  * Unit test class for the BrainMonkeyRaceCondition sniff.
  *
- * @package Yoast\YoastCS
+ * @since 2.3.0
  *
- * @covers  YoastCS\Yoast\Sniffs\Tools\BrainMonkeyRaceConditionSniff
+ * @covers YoastCS\Yoast\Sniffs\Tools\BrainMonkeyRaceConditionSniff
  */
 class BrainMonkeyRaceConditionUnitTest extends AbstractSniffUnitTest {
 

diff --git a/Yoast/Tests/WhiteSpace/FunctionSpacingUnitTest.php b/Yoast/Tests/WhiteSpace/FunctionSpacingUnitTest.php
@@ -7,11 +7,9 @@
 /**
  * Unit test class for the FunctionSpacing sniff.
  *
- * @package Yoast\YoastCS
+ * @since 1.0.0
  *
- * @since   1.0.0
- *
- * @covers  YoastCS\Yoast\Sniffs\WhiteSpace\FunctionSpacingSniff
+ * @covers YoastCS\Yoast\Sniffs\WhiteSpace\FunctionSpacingSniff
  */
 class FunctionSpacingUnitTest extends AbstractSniffUnitTest {
 

diff --git a/Yoast/Tests/Yoast/AlternativeFunctionsUnitTest.php b/Yoast/Tests/Yoast/AlternativeFunctionsUnitTest.php
@@ -7,11 +7,9 @@
 /**
  * Unit test class for the AlternativeFunctions sniff.
  *
- * @package Yoast\YoastCS
+ * @since 1.3.0
  *
- * @since   1.3.0
- *
- * @covers  YoastCS\Yoast\Sniffs\Yoast\AlternativeFunctionsSniff
+ * @covers YoastCS\Yoast\Sniffs\Yoast\AlternativeFunctionsSniff
  */
 class AlternativeFunctionsUnitTest extends AbstractSniffUnitTest {
 

diff --git a/Yoast/Utils/CustomPrefixesTrait.php b/Yoast/Utils/CustomPrefixesTrait.php
@@ -6,10 +6,7 @@
  * Trait to add a custom `$prefixes` property to sniffs and utility functions
  * to validate the property value.
  *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- *
- * @since   2.0.0
+ * @since 2.0.0
  */
 trait CustomPrefixesTrait {