Skip to content

Commit 38c950e

Browse files
jrfnljrfnl
committed
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
1 parent 306542c commit 38c950e

File tree

138 files changed

+426
-681
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

138 files changed

+426
-681
lines changed

‎WordPress/AbstractArrayAssignmentRestrictionsSniff.php

+5-7
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,11 @@
2020
/**
2121
* Restricts array assignment of certain keys.
2222
*
23-
* @package WPCS\WordPressCodingStandards
24-
*
25-
* @since 0.3.0
26-
* @since 0.10.0 Class became a proper abstract class. This was already the behaviour.
27-
* Moved the file and renamed the class from
28-
* `\WordPressCS\WordPress\Sniffs\Arrays\ArrayAssignmentRestrictionsSniff` to
29-
* `\WordPressCS\WordPress\AbstractArrayAssignmentRestrictionsSniff`.
23+
* @since 0.3.0
24+
* @since 0.10.0 Class became a proper abstract class. This was already the behaviour.
25+
* Moved the file and renamed the class from
26+
* `\WordPressCS\WordPress\Sniffs\Arrays\ArrayAssignmentRestrictionsSniff` to
27+
* `\WordPressCS\WordPress\AbstractArrayAssignmentRestrictionsSniff`.
3028
*/
3129
abstract class AbstractArrayAssignmentRestrictionsSniff extends Sniff {
3230

‎WordPress/AbstractClassRestrictionsSniff.php

+1-3
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,7 @@
1919
/**
2020
* Restricts usage of some classes.
2121
*
22-
* @package WPCS\WordPressCodingStandards
23-
*
24-
* @since 0.10.0
22+
* @since 0.10.0
2523
*/
2624
abstract class AbstractClassRestrictionsSniff extends AbstractFunctionRestrictionsSniff {
2725

‎WordPress/AbstractFunctionParameterSniff.php

+1-3
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,7 @@
1515
/**
1616
* Advises about parameters used in function calls.
1717
*
18-
* @package WPCS\WordPressCodingStandards
19-
*
20-
* @since 0.11.0
18+
* @since 0.11.0
2119
*/
2220
abstract class AbstractFunctionParameterSniff extends AbstractFunctionRestrictionsSniff {
2321

‎WordPress/AbstractFunctionRestrictionsSniff.php

+6-8
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,12 @@
1919
/**
2020
* Restricts usage of some functions.
2121
*
22-
* @package WPCS\WordPressCodingStandards
23-
*
24-
* @since 0.3.0
25-
* @since 0.10.0 Class became a proper abstract class. This was already the behaviour.
26-
* Moved the file and renamed the class from
27-
* `\WordPressCS\WordPress\Sniffs\Functions\FunctionRestrictionsSniff` to
28-
* `\WordPressCS\WordPress\AbstractFunctionRestrictionsSniff`.
29-
* @since 0.11.0 Extends the WordPressCS native `Sniff` class.
22+
* @since 0.3.0
23+
* @since 0.10.0 Class became a proper abstract class. This was already the behaviour.
24+
* Moved the file and renamed the class from
25+
* `\WordPressCS\WordPress\Sniffs\Functions\FunctionRestrictionsSniff` to
26+
* `\WordPressCS\WordPress\AbstractFunctionRestrictionsSniff`.
27+
* @since 0.11.0 Extends the WordPressCS native `Sniff` class.
3028
*/
3129
abstract class AbstractFunctionRestrictionsSniff extends Sniff {
3230

‎WordPress/Helpers/ArrayWalkingFunctionsHelper.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,8 @@
1515
/**
1616
* Helper functions and function lists for checking whether a function applies a callback to an array.
1717
*
18-
* @package WPCS\WordPressCodingStandards
19-
* @since 3.0.0 The property in this class was previously contained in the
20-
* `WordPressCS\WordPress\Sniff` class and has been moved here.
18+
* @since 3.0.0 The property in this class was previously contained in the
19+
* `WordPressCS\WordPress\Sniff` class and has been moved here.
2120
*/
2221
final class ArrayWalkingFunctionsHelper {
2322

‎WordPress/Helpers/ConstantsHelper.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,8 @@
2828
*
2929
* @internal
3030
*
31-
* @package WPCS\WordPressCodingStandards
32-
* @since 3.0.0 The method in this class was previously contained in the
33-
* `WordPressCS\WordPress\Sniff` class and has been moved here.
31+
* @since 3.0.0 The method in this class was previously contained in the
32+
* `WordPressCS\WordPress\Sniff` class and has been moved here.
3433
*/
3534
final class ConstantsHelper {
3635

‎WordPress/Helpers/ContextHelper.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,8 @@
2525
*
2626
* @internal
2727
*
28-
* @package WPCS\WordPressCodingStandards
29-
* @since 3.0.0 The methods in this class were previously contained in the
30-
* `WordPressCS\WordPress\Sniff` class and have been moved here.
28+
* @since 3.0.0 The methods in this class were previously contained in the
29+
* `WordPressCS\WordPress\Sniff` class and have been moved here.
3130
*/
3231
final class ContextHelper {
3332

‎WordPress/Helpers/DeprecationHelper.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,8 @@
2525
*
2626
* @internal
2727
*
28-
* @package WPCS\WordPressCodingStandards
29-
* @since 3.0.0 The method in this class was previously contained in the
30-
* `WordPressCS\WordPress\Sniff` class and has been moved here.
28+
* @since 3.0.0 The method in this class was previously contained in the
29+
* `WordPressCS\WordPress\Sniff` class and has been moved here.
3130
*/
3231
final class DeprecationHelper {
3332

‎WordPress/Helpers/EscapingFunctionsTrait.php

+3-4
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,9 @@
1919
* - `customEscapingFunctions`.
2020
* - `customAutoEscapedFunctions`
2121
*
22-
* @package WPCS\WordPressCodingStandards
23-
* @since 3.0.0 The properties in this trait were previously contained partially in the
24-
* `WordPressCS\WordPress\Sniff` class and partially in the `EscapeOutputSniff`
25-
* class and have been moved here.
22+
* @since 3.0.0 The properties in this trait were previously contained partially in the
23+
* `WordPressCS\WordPress\Sniff` class and partially in the `EscapeOutputSniff`
24+
* class and have been moved here.
2625
*/
2726
trait EscapingFunctionsTrait {
2827

‎WordPress/Helpers/FormattingFunctionsHelper.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,8 @@
1212
/**
1313
* Helper functions and function lists for checking whether a function is a formatting function.
1414
*
15-
* @package WPCS\WordPressCodingStandards
16-
* @since 3.0.0 The property in this class was previously contained in the
17-
* `WordPressCS\WordPress\Sniff` class and has been moved here.
15+
* @since 3.0.0 The property in this class was previously contained in the
16+
* `WordPressCS\WordPress\Sniff` class and has been moved here.
1817
*/
1918
final class FormattingFunctionsHelper {
2019

‎WordPress/Helpers/IsUnitTestTrait.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,8 @@
2626
* - The sniff can call the `is_test_class()` method in this trait to verify if a class is
2727
* a test class. The `is_test_class()` method will take the custom property into account.
2828
*
29-
* @package WPCS\WordPressCodingStandards
30-
* @since 3.0.0 The properties and method in this trait were previously contained in the
31-
* `WordPressCS\WordPress\Sniff` class and have been moved here.
29+
* @since 3.0.0 The properties and method in this trait were previously contained in the
30+
* `WordPressCS\WordPress\Sniff` class and have been moved here.
3231
*/
3332
trait IsUnitTestTrait {
3433

‎WordPress/Helpers/ListHelper.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,8 @@
2727
*
2828
* @internal
2929
*
30-
* @package WPCS\WordPressCodingStandards
31-
* @since 3.0.0 The method in this class was previously contained in the
32-
* `WordPressCS\WordPress\Sniff` class and has been moved here.
30+
* @since 3.0.0 The method in this class was previously contained in the
31+
* `WordPressCS\WordPress\Sniff` class and has been moved here.
3332
*/
3433
final class ListHelper {
3534

‎WordPress/Helpers/MinimumWPVersionTrait.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,8 @@
2222
* - After that, the `MinimumWPVersionTrait::$minimum_wp_version` property can be freely used
2323
* in the sniff.
2424
*
25-
* @package WPCS\WordPressCodingStandards
26-
* @since 3.0.0 The property and method in this trait were previously contained in the
27-
* `WordPressCS\WordPress\Sniff` class and have been moved here.
25+
* @since 3.0.0 The property and method in this trait were previously contained in the
26+
* `WordPressCS\WordPress\Sniff` class and have been moved here.
2827
*/
2928
trait MinimumWPVersionTrait {
3029

‎WordPress/Helpers/PrintingFunctionsTrait.php

+3-4
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,9 @@
1818
* following `public` property which can be changed from within a custom ruleset:
1919
* - `customPrintingFunctions`.
2020
*
21-
* @package WPCS\WordPressCodingStandards
22-
* @since 3.0.0 The properties in this trait were previously contained partially in the
23-
* `WordPressCS\WordPress\Sniff` class and partially in the `EscapeOutputSniff`
24-
* class and have been moved here.
21+
* @since 3.0.0 The properties in this trait were previously contained partially in the
22+
* `WordPressCS\WordPress\Sniff` class and partially in the `EscapeOutputSniff`
23+
* class and have been moved here.
2524
*/
2625
trait PrintingFunctionsTrait {
2726

‎WordPress/Helpers/RulesetPropertyHelper.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,8 @@
1919
*
2020
* @internal
2121
*
22-
* @package WPCS\WordPressCodingStandards
23-
* @since 3.0.0 The method in this class was previously contained in the
24-
* `WordPressCS\WordPress\Sniff` class and has been moved here.
22+
* @since 3.0.0 The method in this class was previously contained in the
23+
* `WordPressCS\WordPress\Sniff` class and has been moved here.
2524
*/
2625
final class RulesetPropertyHelper {
2726

‎WordPress/Helpers/SanitizingFunctionsTrait.php

+3-4
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,9 @@
1919
* - `customSanitizingFunctions`.
2020
* - `customUnslashingSanitizingFunctions`
2121
*
22-
* @package WPCS\WordPressCodingStandards
23-
* @since 3.0.0 The properties in this trait were previously contained partially in the
24-
* `WordPressCS\WordPress\Sniff` class and partially in the `NonceVerificationSniff`
25-
* and the `ValidatedSanitizedInputSniff` classes and have been moved here.
22+
* @since 3.0.0 The properties in this trait were previously contained partially in the
23+
* `WordPressCS\WordPress\Sniff` class and partially in the `NonceVerificationSniff`
24+
* and the `ValidatedSanitizedInputSniff` classes and have been moved here.
2625
*/
2726
trait SanitizingFunctionsTrait {
2827

‎WordPress/Helpers/SnakeCaseHelper.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,8 @@
2424
*
2525
* @internal
2626
*
27-
* @package WPCS\WordPressCodingStandards
28-
* @since 3.0.0 The method in this class was previously contained in the
29-
* `WordPressCS\WordPress\Sniff` class and has been moved here.
27+
* @since 3.0.0 The method in this class was previously contained in the
28+
* `WordPressCS\WordPress\Sniff` class and has been moved here.
3029
*/
3130
final class SnakeCaseHelper {
3231

‎WordPress/Helpers/UnslashingFunctionsHelper.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,8 @@
1212
/**
1313
* Helper functions and function lists for checking whether a function is an unslashing function.
1414
*
15-
* @package WPCS\WordPressCodingStandards
16-
* @since 3.0.0 The property in this class was previously contained in the
17-
* `WordPressCS\WordPress\Sniff` class and has been moved here.
15+
* @since 3.0.0 The property in this class was previously contained in the
16+
* `WordPressCS\WordPress\Sniff` class and has been moved here.
1817
*/
1918
final class UnslashingFunctionsHelper {
2019

‎WordPress/Helpers/ValidationHelper.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,8 @@
2121
/**
2222
* Helper function for checking whether a token is validated.
2323
*
24-
* @package WPCS\WordPressCodingStandards
25-
* @since 3.0.0 The method in this class was previously contained in the
26-
* `WordPressCS\WordPress\Sniff` class and has been moved here.
24+
* @since 3.0.0 The method in this class was previously contained in the
25+
* `WordPressCS\WordPress\Sniff` class and has been moved here.
2726
*/
2827
final class ValidationHelper {
2928

‎WordPress/Helpers/VariableHelper.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,8 @@
2727
*
2828
* @internal
2929
*
30-
* @package WPCS\WordPressCodingStandards
31-
* @since 3.0.0 The methods in this class were previously contained in the
32-
* `WordPressCS\WordPress\Sniff` class and have been moved here.
30+
* @since 3.0.0 The methods in this class were previously contained in the
31+
* `WordPressCS\WordPress\Sniff` class and have been moved here.
3332
*/
3433
final class VariableHelper {
3534

‎WordPress/Helpers/WPDBTrait.php

+2-4
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,8 @@
1717
/**
1818
* Helper utilities for sniffs which examine WPDB method calls.
1919
*
20-
* @package WPCS\WordPressCodingStandards
21-
*
22-
* @since 3.0.0 The method in this trait was previously contained in the
23-
* `WordPressCS\WordPress\Sniff` class and has been moved here.
20+
* @since 3.0.0 The method in this trait was previously contained in the
21+
* `WordPressCS\WordPress\Sniff` class and has been moved here.
2422
*/
2523
trait WPDBTrait {
2624

‎WordPress/Helpers/WPGlobalVariablesHelper.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,8 @@
1212
/**
1313
* Helper utilities for recognizing WP global variables.
1414
*
15-
* @package WPCS\WordPressCodingStandards
16-
* @since 3.0.0 The property in this class was previously contained in the
17-
* `WordPressCS\WordPress\Sniff` class and has been moved here.
15+
* @since 3.0.0 The property in this class was previously contained in the
16+
* `WordPressCS\WordPress\Sniff` class and has been moved here.
1817
*/
1918
final class WPGlobalVariablesHelper {
2019

‎WordPress/Helpers/WPHookHelper.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,8 @@
1414
/**
1515
* Helper utilities for recognizing functions related to the WP Hook mechanism.
1616
*
17-
* @package WPCS\WordPressCodingStandards
18-
* @since 3.0.0 The property in this class was previously contained in the
19-
* `WordPressCS\WordPress\Sniff` class and has been moved here.
17+
* @since 3.0.0 The property in this class was previously contained in the
18+
* `WordPressCS\WordPress\Sniff` class and has been moved here.
2019
*/
2120
final class WPHookHelper {
2221

‎WordPress/Sniff.php

+1-2
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,7 @@
2323
*
2424
* Provides a bootstrap for the sniffs, to reduce code duplication.
2525
*
26-
* @package WPCS\WordPressCodingStandards
27-
* @since 0.4.0
26+
* @since 0.4.0
2827
*/
2928
abstract class Sniff implements PHPCS_Sniff {
3029

‎WordPress/Sniffs/Arrays/ArrayDeclarationSpacingSniff.php

+15-17
Original file line numberDiff line numberDiff line change
@@ -22,24 +22,22 @@
2222
* - Checks that associative arrays are multi-line.
2323
* - Checks that each array item in a multi-line array starts on a new line.
2424
*
25-
* @link https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#indentation
25+
* @link https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#indentation
2626
*
27-
* @package WPCS\WordPressCodingStandards
28-
*
29-
* @since 0.11.0 - The WordPress specific additional checks have now been split off
30-
* from the `WordPress.Arrays.ArrayDeclaration` sniff into this sniff.
31-
* - Added sniffing & fixing for associative arrays.
32-
* @since 0.12.0 Decoupled this sniff from the upstream sniff completely.
33-
* This sniff now extends the WordPressCS native `Sniff` class instead.
34-
* @since 0.13.0 Added the last remaining checks from the `WordPress.Arrays.ArrayDeclaration`
35-
* sniff which were not covered elsewhere.
36-
* The `WordPress.Arrays.ArrayDeclaration` sniff has now been deprecated.
37-
* @since 0.13.0 Class name changed: this class is now namespaced.
38-
* @since 0.14.0 Single item associative arrays are now by default exempt from the
39-
* "must be multi-line" rule. This behaviour can be changed using the
40-
* `allow_single_item_single_line_associative_arrays` property.
41-
* @since 3.0.0 Removed various whitespace related checks and fixers in favour of the PHPCSExtra
42-
* `NormalizedArrays.Arrays.ArrayBraceSpacing` sniff.
27+
* @since 0.11.0 - The WordPress specific additional checks have now been split off
28+
* from the `WordPress.Arrays.ArrayDeclaration` sniff into this sniff.
29+
* - Added sniffing & fixing for associative arrays.
30+
* @since 0.12.0 Decoupled this sniff from the upstream sniff completely.
31+
* This sniff now extends the WordPressCS native `Sniff` class instead.
32+
* @since 0.13.0 Added the last remaining checks from the `WordPress.Arrays.ArrayDeclaration`
33+
* sniff which were not covered elsewhere.
34+
* The `WordPress.Arrays.ArrayDeclaration` sniff has now been deprecated.
35+
* @since 0.13.0 Class name changed: this class is now namespaced.
36+
* @since 0.14.0 Single item associative arrays are now by default exempt from the
37+
* "must be multi-line" rule. This behaviour can be changed using the
38+
* `allow_single_item_single_line_associative_arrays` property.
39+
* @since 3.0.0 Removed various whitespace related checks and fixers in favour of the PHPCSExtra
40+
* `NormalizedArrays.Arrays.ArrayBraceSpacing` sniff.
4341
*/
4442
final class ArrayDeclarationSpacingSniff extends Sniff {
4543

‎WordPress/Sniffs/Arrays/ArrayIndentationSniff.php

+3-5
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,10 @@
1919
/**
2020
* Enforces WordPress array indentation for multi-line arrays.
2121
*
22-
* @link https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#indentation
22+
* @link https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#indentation
2323
*
24-
* @package WPCS\WordPressCodingStandards
25-
*
26-
* @since 0.12.0
27-
* @since 0.13.0 Class name changed: this class is now namespaced.
24+
* @since 0.12.0
25+
* @since 0.13.0 Class name changed: this class is now namespaced.
2826
*
2927
* {@internal This sniff should eventually be pulled upstream as part of a solution
3028
* for https://github.com/squizlabs/PHP_CodeSniffer/issues/582 }}

‎WordPress/Sniffs/Arrays/ArrayKeySpacingRestrictionsSniff.php

+6-8
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,13 @@
1515
/**
1616
* Check for proper spacing in array key references.
1717
*
18-
* @link https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#space-usage
18+
* @link https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#space-usage
1919
*
20-
* @package WPCS\WordPressCodingStandards
21-
*
22-
* @since 0.3.0
23-
* @since 0.7.0 This sniff now has the ability to fix a number of the issues it flags.
24-
* @since 0.12.0 This class now extends the WordPressCS native `Sniff` class.
25-
* @since 0.13.0 Class name changed: this class is now namespaced.
26-
* @since 2.2.0 The sniff now also checks the size of the spacing, if applicable.
20+
* @since 0.3.0
21+
* @since 0.7.0 This sniff now has the ability to fix a number of the issues it flags.
22+
* @since 0.12.0 This class now extends the WordPressCS native `Sniff` class.
23+
* @since 0.13.0 Class name changed: this class is now namespaced.
24+
* @since 2.2.0 The sniff now also checks the size of the spacing, if applicable.
2725
*/
2826
final class ArrayKeySpacingRestrictionsSniff extends Sniff {
2927

‎WordPress/Sniffs/Arrays/MultipleStatementAlignmentSniff.php

+2-4
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,9 @@
2222
* - Allows for new line(s) before a double arrow (configurable).
2323
* - Allows for handling multi-line array items differently if so desired (configurable).
2424
*
25-
* @link https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#indentation
25+
* @link https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#indentation
2626
*
27-
* @package WPCS\WordPressCodingStandards
28-
*
29-
* @since 0.14.0
27+
* @since 0.14.0
3028
*
3129
* {@internal This sniff should eventually be pulled upstream as part of a solution
3230
* for https://github.com/squizlabs/PHP_CodeSniffer/issues/582 }}

0 commit comments

Comments
 (0)