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. That is only in a very limited way the case in WPCS, so I'm proposing to remove the `@package` tags from the WPCS class docblocks, though leaving them for now in the file docblocks. At the very least, this removed duplicate information for which there is no reason for the duplication. 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 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
WordPress · Aug 11, 2023 · 38c950e · 38c950e
1 parent 306542c
commit 38c950e
Show file tree

Hide file tree

Showing 138 changed files with 426 additions and 681 deletions.
diff --git a/WordPress/AbstractArrayAssignmentRestrictionsSniff.php b/WordPress/AbstractArrayAssignmentRestrictionsSniff.php
@@ -20,13 +20,11 @@
 /**
  * Restricts array assignment of certain keys.
  *
- * @package WPCS\WordPressCodingStandards
- *
- * @since   0.3.0
- * @since   0.10.0 Class became a proper abstract class. This was already the behaviour.
- *                 Moved the file and renamed the class from
- *                 `\WordPressCS\WordPress\Sniffs\Arrays\ArrayAssignmentRestrictionsSniff` to
- *                 `\WordPressCS\WordPress\AbstractArrayAssignmentRestrictionsSniff`.
+ * @since 0.3.0
+ * @since 0.10.0 Class became a proper abstract class. This was already the behaviour.
+ *               Moved the file and renamed the class from
+ *               `\WordPressCS\WordPress\Sniffs\Arrays\ArrayAssignmentRestrictionsSniff` to
+ *               `\WordPressCS\WordPress\AbstractArrayAssignmentRestrictionsSniff`.
  */
 abstract class AbstractArrayAssignmentRestrictionsSniff extends Sniff {
 

diff --git a/WordPress/AbstractClassRestrictionsSniff.php b/WordPress/AbstractClassRestrictionsSniff.php
@@ -19,9 +19,7 @@
 /**
  * Restricts usage of some classes.
  *
- * @package WPCS\WordPressCodingStandards
- *
- * @since   0.10.0
+ * @since 0.10.0
  */
 abstract class AbstractClassRestrictionsSniff extends AbstractFunctionRestrictionsSniff {
 

diff --git a/WordPress/AbstractFunctionParameterSniff.php b/WordPress/AbstractFunctionParameterSniff.php
@@ -15,9 +15,7 @@
 /**
  * Advises about parameters used in function calls.
  *
- * @package WPCS\WordPressCodingStandards
- *
- * @since   0.11.0
+ * @since 0.11.0
  */
 abstract class AbstractFunctionParameterSniff extends AbstractFunctionRestrictionsSniff {
 

diff --git a/WordPress/AbstractFunctionRestrictionsSniff.php b/WordPress/AbstractFunctionRestrictionsSniff.php
@@ -19,14 +19,12 @@
 /**
  * Restricts usage of some functions.
  *
- * @package WPCS\WordPressCodingStandards
- *
- * @since   0.3.0
- * @since   0.10.0 Class became a proper abstract class. This was already the behaviour.
- *                 Moved the file and renamed the class from
- *                 `\WordPressCS\WordPress\Sniffs\Functions\FunctionRestrictionsSniff` to
- *                 `\WordPressCS\WordPress\AbstractFunctionRestrictionsSniff`.
- * @since   0.11.0 Extends the WordPressCS native `Sniff` class.
+ * @since 0.3.0
+ * @since 0.10.0 Class became a proper abstract class. This was already the behaviour.
+ *               Moved the file and renamed the class from
+ *               `\WordPressCS\WordPress\Sniffs\Functions\FunctionRestrictionsSniff` to
+ *               `\WordPressCS\WordPress\AbstractFunctionRestrictionsSniff`.
+ * @since 0.11.0 Extends the WordPressCS native `Sniff` class.
  */
 abstract class AbstractFunctionRestrictionsSniff extends Sniff {
 

diff --git a/WordPress/Helpers/ArrayWalkingFunctionsHelper.php b/WordPress/Helpers/ArrayWalkingFunctionsHelper.php
@@ -15,9 +15,8 @@
 /**
  * Helper functions and function lists for checking whether a function applies a callback to an array.
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The property in this class was previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and has been moved here.
+ * @since 3.0.0 The property in this class was previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and has been moved here.
  */
 final class ArrayWalkingFunctionsHelper {
 

diff --git a/WordPress/Helpers/ConstantsHelper.php b/WordPress/Helpers/ConstantsHelper.php
@@ -28,9 +28,8 @@
  *
  * @internal
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The method in this class was previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and has been moved here.
+ * @since 3.0.0 The method in this class was previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and has been moved here.
  */
 final class ConstantsHelper {
 

diff --git a/WordPress/Helpers/ContextHelper.php b/WordPress/Helpers/ContextHelper.php
@@ -25,9 +25,8 @@
  *
  * @internal
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The methods in this class were previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and have been moved here.
+ * @since 3.0.0 The methods in this class were previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and have been moved here.
  */
 final class ContextHelper {
 

diff --git a/WordPress/Helpers/DeprecationHelper.php b/WordPress/Helpers/DeprecationHelper.php
@@ -25,9 +25,8 @@
  *
  * @internal
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The method in this class was previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and has been moved here.
+ * @since 3.0.0 The method in this class was previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and has been moved here.
  */
 final class DeprecationHelper {
 

diff --git a/WordPress/Helpers/EscapingFunctionsTrait.php b/WordPress/Helpers/EscapingFunctionsTrait.php
@@ -19,10 +19,9 @@
  * - `customEscapingFunctions`.
  * - `customAutoEscapedFunctions`
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The properties in this trait were previously contained partially in the
- *                `WordPressCS\WordPress\Sniff` class and partially in the `EscapeOutputSniff`
- *                class and have been moved here.
+ * @since 3.0.0 The properties in this trait were previously contained partially in the
+ *              `WordPressCS\WordPress\Sniff` class and partially in the `EscapeOutputSniff`
+ *              class and have been moved here.
  */
 trait EscapingFunctionsTrait {
 

diff --git a/WordPress/Helpers/FormattingFunctionsHelper.php b/WordPress/Helpers/FormattingFunctionsHelper.php
@@ -12,9 +12,8 @@
 /**
  * Helper functions and function lists for checking whether a function is a formatting function.
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The property in this class was previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and has been moved here.
+ * @since 3.0.0 The property in this class was previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and has been moved here.
  */
 final class FormattingFunctionsHelper {
 

diff --git a/WordPress/Helpers/IsUnitTestTrait.php b/WordPress/Helpers/IsUnitTestTrait.php
@@ -26,9 +26,8 @@
  * - The sniff can call the `is_test_class()` method in this trait to verify if a class is
  *   a test class. The `is_test_class()` method will take the custom property into account.
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The properties and method in this trait were previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and have been moved here.
+ * @since 3.0.0 The properties and method in this trait were previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and have been moved here.
  */
 trait IsUnitTestTrait {
 

diff --git a/WordPress/Helpers/ListHelper.php b/WordPress/Helpers/ListHelper.php
@@ -27,9 +27,8 @@
  *
  * @internal
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The method in this class was previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and has been moved here.
+ * @since 3.0.0 The method in this class was previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and has been moved here.
  */
 final class ListHelper {
 

diff --git a/WordPress/Helpers/MinimumWPVersionTrait.php b/WordPress/Helpers/MinimumWPVersionTrait.php
@@ -22,9 +22,8 @@
  * - After that, the `MinimumWPVersionTrait::$minimum_wp_version` property can be freely used
  *   in the sniff.
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The property and method in this trait were previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and have been moved here.
+ * @since 3.0.0 The property and method in this trait were previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and have been moved here.
  */
 trait MinimumWPVersionTrait {
 

diff --git a/WordPress/Helpers/PrintingFunctionsTrait.php b/WordPress/Helpers/PrintingFunctionsTrait.php
@@ -18,10 +18,9 @@
  * following `public` property which can be changed from within a custom ruleset:
  * - `customPrintingFunctions`.
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The properties in this trait were previously contained partially in the
- *                `WordPressCS\WordPress\Sniff` class and partially in the `EscapeOutputSniff`
- *                class and have been moved here.
+ * @since 3.0.0 The properties in this trait were previously contained partially in the
+ *              `WordPressCS\WordPress\Sniff` class and partially in the `EscapeOutputSniff`
+ *              class and have been moved here.
  */
 trait PrintingFunctionsTrait {
 

diff --git a/WordPress/Helpers/RulesetPropertyHelper.php b/WordPress/Helpers/RulesetPropertyHelper.php
@@ -19,9 +19,8 @@
  *
  * @internal
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The method in this class was previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and has been moved here.
+ * @since 3.0.0 The method in this class was previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and has been moved here.
  */
 final class RulesetPropertyHelper {
 

diff --git a/WordPress/Helpers/SanitizingFunctionsTrait.php b/WordPress/Helpers/SanitizingFunctionsTrait.php
@@ -19,10 +19,9 @@
  * - `customSanitizingFunctions`.
  * - `customUnslashingSanitizingFunctions`
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The properties in this trait were previously contained partially in the
- *                `WordPressCS\WordPress\Sniff` class and partially in the `NonceVerificationSniff`
- *                and the `ValidatedSanitizedInputSniff` classes and have been moved here.
+ * @since 3.0.0 The properties in this trait were previously contained partially in the
+ *              `WordPressCS\WordPress\Sniff` class and partially in the `NonceVerificationSniff`
+ *              and the `ValidatedSanitizedInputSniff` classes and have been moved here.
  */
 trait SanitizingFunctionsTrait {
 

diff --git a/WordPress/Helpers/SnakeCaseHelper.php b/WordPress/Helpers/SnakeCaseHelper.php
@@ -24,9 +24,8 @@
  *
  * @internal
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The method in this class was previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and has been moved here.
+ * @since 3.0.0 The method in this class was previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and has been moved here.
  */
 final class SnakeCaseHelper {
 

diff --git a/WordPress/Helpers/UnslashingFunctionsHelper.php b/WordPress/Helpers/UnslashingFunctionsHelper.php
@@ -12,9 +12,8 @@
 /**
  * Helper functions and function lists for checking whether a function is an unslashing function.
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The property in this class was previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and has been moved here.
+ * @since 3.0.0 The property in this class was previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and has been moved here.
  */
 final class UnslashingFunctionsHelper {
 

diff --git a/WordPress/Helpers/ValidationHelper.php b/WordPress/Helpers/ValidationHelper.php
@@ -21,9 +21,8 @@
 /**
  * Helper function for checking whether a token is validated.
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The method in this class was previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and has been moved here.
+ * @since 3.0.0 The method in this class was previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and has been moved here.
  */
 final class ValidationHelper {
 

diff --git a/WordPress/Helpers/VariableHelper.php b/WordPress/Helpers/VariableHelper.php
@@ -27,9 +27,8 @@
  *
  * @internal
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The methods in this class were previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and have been moved here.
+ * @since 3.0.0 The methods in this class were previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and have been moved here.
  */
 final class VariableHelper {
 

diff --git a/WordPress/Helpers/WPDBTrait.php b/WordPress/Helpers/WPDBTrait.php
@@ -17,10 +17,8 @@
 /**
  * Helper utilities for sniffs which examine WPDB method calls.
  *
- * @package WPCS\WordPressCodingStandards
- *
- * @since   3.0.0 The method in this trait was previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and has been moved here.
+ * @since 3.0.0 The method in this trait was previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and has been moved here.
  */
 trait WPDBTrait {
 

diff --git a/WordPress/Helpers/WPGlobalVariablesHelper.php b/WordPress/Helpers/WPGlobalVariablesHelper.php
@@ -12,9 +12,8 @@
 /**
  * Helper utilities for recognizing WP global variables.
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The property in this class was previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and has been moved here.
+ * @since 3.0.0 The property in this class was previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and has been moved here.
  */
 final class WPGlobalVariablesHelper {
 

diff --git a/WordPress/Helpers/WPHookHelper.php b/WordPress/Helpers/WPHookHelper.php
@@ -14,9 +14,8 @@
 /**
  * Helper utilities for recognizing functions related to the WP Hook mechanism.
  *
- * @package WPCS\WordPressCodingStandards
- * @since   3.0.0 The property in this class was previously contained in the
- *                `WordPressCS\WordPress\Sniff` class and has been moved here.
+ * @since 3.0.0 The property in this class was previously contained in the
+ *              `WordPressCS\WordPress\Sniff` class and has been moved here.
  */
 final class WPHookHelper {
 

diff --git a/WordPress/Sniff.php b/WordPress/Sniff.php
@@ -23,8 +23,7 @@
  *
  * Provides a bootstrap for the sniffs, to reduce code duplication.
  *
- * @package WPCS\WordPressCodingStandards
- * @since   0.4.0
+ * @since 0.4.0
  */
 abstract class Sniff implements PHPCS_Sniff {
 

diff --git a/WordPress/Sniffs/Arrays/ArrayDeclarationSpacingSniff.php b/WordPress/Sniffs/Arrays/ArrayDeclarationSpacingSniff.php
@@ -22,24 +22,22 @@
  * - Checks that associative arrays are multi-line.
  * - Checks that each array item in a multi-line array starts on a new line.
  *
- * @link    https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#indentation
+ * @link https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#indentation
  *
- * @package WPCS\WordPressCodingStandards
- *
- * @since   0.11.0 - The WordPress specific additional checks have now been split off
- *                   from the `WordPress.Arrays.ArrayDeclaration` sniff into this sniff.
- *                 - Added sniffing & fixing for associative arrays.
- * @since   0.12.0 Decoupled this sniff from the upstream sniff completely.
- *                 This sniff now extends the WordPressCS native `Sniff` class instead.
- * @since   0.13.0 Added the last remaining checks from the `WordPress.Arrays.ArrayDeclaration`
- *                 sniff which were not covered elsewhere.
- *                 The `WordPress.Arrays.ArrayDeclaration` sniff has now been deprecated.
- * @since   0.13.0 Class name changed: this class is now namespaced.
- * @since   0.14.0 Single item associative arrays are now by default exempt from the
- *                 "must be multi-line" rule. This behaviour can be changed using the
- *                 `allow_single_item_single_line_associative_arrays` property.
- * @since   3.0.0  Removed various whitespace related checks and fixers in favour of the PHPCSExtra
- *                 `NormalizedArrays.Arrays.ArrayBraceSpacing` sniff.
+ * @since 0.11.0 - The WordPress specific additional checks have now been split off
+ *                 from the `WordPress.Arrays.ArrayDeclaration` sniff into this sniff.
+ *               - Added sniffing & fixing for associative arrays.
+ * @since 0.12.0 Decoupled this sniff from the upstream sniff completely.
+ *               This sniff now extends the WordPressCS native `Sniff` class instead.
+ * @since 0.13.0 Added the last remaining checks from the `WordPress.Arrays.ArrayDeclaration`
+ *               sniff which were not covered elsewhere.
+ *               The `WordPress.Arrays.ArrayDeclaration` sniff has now been deprecated.
+ * @since 0.13.0 Class name changed: this class is now namespaced.
+ * @since 0.14.0 Single item associative arrays are now by default exempt from the
+ *               "must be multi-line" rule. This behaviour can be changed using the
+ *               `allow_single_item_single_line_associative_arrays` property.
+ * @since 3.0.0  Removed various whitespace related checks and fixers in favour of the PHPCSExtra
+ *               `NormalizedArrays.Arrays.ArrayBraceSpacing` sniff.
  */
 final class ArrayDeclarationSpacingSniff extends Sniff {
 

diff --git a/WordPress/Sniffs/Arrays/ArrayIndentationSniff.php b/WordPress/Sniffs/Arrays/ArrayIndentationSniff.php
@@ -19,12 +19,10 @@
 /**
  * Enforces WordPress array indentation for multi-line arrays.
  *
- * @link    https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#indentation
+ * @link https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#indentation
  *
- * @package WPCS\WordPressCodingStandards
- *
- * @since   0.12.0
- * @since   0.13.0 Class name changed: this class is now namespaced.
+ * @since 0.12.0
+ * @since 0.13.0 Class name changed: this class is now namespaced.
  *
  * {@internal This sniff should eventually be pulled upstream as part of a solution
  * for https://github.com/squizlabs/PHP_CodeSniffer/issues/582 }}

diff --git a/WordPress/Sniffs/Arrays/ArrayKeySpacingRestrictionsSniff.php b/WordPress/Sniffs/Arrays/ArrayKeySpacingRestrictionsSniff.php
@@ -15,15 +15,13 @@
 /**
  * Check for proper spacing in array key references.
  *
- * @link    https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#space-usage
+ * @link https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#space-usage
  *
- * @package WPCS\WordPressCodingStandards
- *
- * @since   0.3.0
- * @since   0.7.0  This sniff now has the ability to fix a number of the issues it flags.
- * @since   0.12.0 This class now extends the WordPressCS native `Sniff` class.
- * @since   0.13.0 Class name changed: this class is now namespaced.
- * @since   2.2.0  The sniff now also checks the size of the spacing, if applicable.
+ * @since 0.3.0
+ * @since 0.7.0  This sniff now has the ability to fix a number of the issues it flags.
+ * @since 0.12.0 This class now extends the WordPressCS native `Sniff` class.
+ * @since 0.13.0 Class name changed: this class is now namespaced.
+ * @since 2.2.0  The sniff now also checks the size of the spacing, if applicable.
  */
 final class ArrayKeySpacingRestrictionsSniff extends Sniff {
 

diff --git a/WordPress/Sniffs/Arrays/MultipleStatementAlignmentSniff.php b/WordPress/Sniffs/Arrays/MultipleStatementAlignmentSniff.php
@@ -22,11 +22,9 @@
  * - Allows for new line(s) before a double arrow (configurable).
  * - Allows for handling multi-line array items differently if so desired (configurable).
  *
- * @link    https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#indentation
+ * @link https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#indentation
  *
- * @package WPCS\WordPressCodingStandards
- *
- * @since   0.14.0
+ * @since 0.14.0
  *
  * {@internal This sniff should eventually be pulled upstream as part of a solution
  * for https://github.com/squizlabs/PHP_CodeSniffer/issues/582 }}