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 VIPCS, so I'm proposing to remove the `@package` tags from the VIPCS 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
Automattic · Aug 25, 2023 · f962816 · f962816
1 parent 5f34bbe
commit f962816
Show file tree

Hide file tree

Showing 81 changed files with 9 additions and 171 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -140,8 +140,6 @@ use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
 
 /**
  * Unit test class for the WP_Query params sniff.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class WPQueryParamsUnitTest extends AbstractSniffUnitTest {
 

diff --git a/WordPressVIPMinimum/Sniffs/AbstractVariableRestrictionsSniff.php b/WordPressVIPMinimum/Sniffs/AbstractVariableRestrictionsSniff.php
@@ -18,8 +18,6 @@
  * Restricts usage of some variables.
  *
  * Originally part of WordPress Coding Standards repo.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 abstract class AbstractVariableRestrictionsSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Classes/DeclarationCompatibilitySniff.php b/WordPressVIPMinimum/Sniffs/Classes/DeclarationCompatibilitySniff.php
@@ -14,8 +14,6 @@
 
 /**
  * Class WordPressVIPMinimum_Sniffs_Classes_DeclarationCompatibilitySniff
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class DeclarationCompatibilitySniff extends AbstractScopeSniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Classes/RestrictedExtendClassesSniff.php b/WordPressVIPMinimum/Sniffs/Classes/RestrictedExtendClassesSniff.php
@@ -12,8 +12,6 @@
 /**
  * WordPressVIPMinimum_Sniffs_Classes_RestrictedExtendClassesSniff.
  *
- * @package VIPCS\WordPressVIPMinimum
- *
  * @since 0.4.0
  */
 class RestrictedExtendClassesSniff extends AbstractClassRestrictionsSniff {

diff --git a/WordPressVIPMinimum/Sniffs/Constants/ConstantStringSniff.php b/WordPressVIPMinimum/Sniffs/Constants/ConstantStringSniff.php
@@ -14,8 +14,6 @@
 
 /**
  * Sniff for properly using constant name when checking whether a constant is defined.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class ConstantStringSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Constants/RestrictedConstantsSniff.php b/WordPressVIPMinimum/Sniffs/Constants/RestrictedConstantsSniff.php
@@ -13,8 +13,6 @@
 
 /**
  * Restricts usage of some constants.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class RestrictedConstantsSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Files/IncludingFileSniff.php b/WordPressVIPMinimum/Sniffs/Files/IncludingFileSniff.php
@@ -14,8 +14,6 @@
  * WordPressVIPMinimum_Sniffs_Files_IncludingFileSniff.
  *
  * Checks for custom variables, functions and constants, and external URLs used in file inclusion.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class IncludingFileSniff extends AbstractFunctionRestrictionsSniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Files/IncludingNonPHPFileSniff.php b/WordPressVIPMinimum/Sniffs/Files/IncludingNonPHPFileSniff.php
@@ -15,8 +15,6 @@
  * Ensure that non-PHP files are included via `file_get_contents()` instead of using `include/require[_once]`.
  *
  * This prevents potential PHP code embedded in those files from being automatically executed.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class IncludingNonPHPFileSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Functions/RestrictedFunctionsSniff.php b/WordPressVIPMinimum/Sniffs/Functions/RestrictedFunctionsSniff.php
@@ -12,8 +12,6 @@
 
 /**
  * Restricts usage of some functions in VIP context.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class RestrictedFunctionsSniff extends AbstractFunctionRestrictionsSniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Functions/StripTagsSniff.php b/WordPressVIPMinimum/Sniffs/Functions/StripTagsSniff.php
@@ -12,8 +12,6 @@
 /**
  * This sniff ensures proper tag stripping.
  *
- * @package VIPCS\WordPressVIPMinimum
- *
  * @since 0.4.0
  */
 class StripTagsSniff extends AbstractFunctionParameterSniff {

diff --git a/WordPressVIPMinimum/Sniffs/Hooks/AlwaysReturnInFilterSniff.php b/WordPressVIPMinimum/Sniffs/Hooks/AlwaysReturnInFilterSniff.php
@@ -14,8 +14,6 @@
 
 /**
  * This sniff validates that filters always return a value
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class AlwaysReturnInFilterSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Hooks/PreGetPostsSniff.php b/WordPressVIPMinimum/Sniffs/Hooks/PreGetPostsSniff.php
@@ -15,8 +15,6 @@
  * This sniff validates a proper usage of pre_get_posts action callback.
  *
  * It looks for cases when the WP_Query object is being modified without checking for WP_Query::is_main_query().
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class PreGetPostsSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Hooks/RestrictedHooksSniff.php b/WordPressVIPMinimum/Sniffs/Hooks/RestrictedHooksSniff.php
@@ -12,8 +12,6 @@
 /**
  * This sniff restricts usage of some action and filter hooks.
  *
- * @package VIPCS\WordPressVIPMinimum
- *
  * @since 0.4.0
  */
 class RestrictedHooksSniff extends AbstractFunctionParameterSniff {

diff --git a/WordPressVIPMinimum/Sniffs/JS/DangerouslySetInnerHTMLSniff.php b/WordPressVIPMinimum/Sniffs/JS/DangerouslySetInnerHTMLSniff.php
@@ -14,8 +14,6 @@
  * WordPressVIPMinimum_Sniffs_JS_DangerouslySetInnerHTMLSniff.
  *
  * Looks for instances of React's dangerouslySetInnerHMTL.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class DangerouslySetInnerHTMLSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/JS/HTMLExecutingFunctionsSniff.php b/WordPressVIPMinimum/Sniffs/JS/HTMLExecutingFunctionsSniff.php
@@ -14,8 +14,6 @@
  * WordPressVIPMinimum_Sniffs_JS_HTMLExecutingFunctions.
  *
  * Flags functions which are executing HTML passed to it.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class HTMLExecutingFunctionsSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/JS/InnerHTMLSniff.php b/WordPressVIPMinimum/Sniffs/JS/InnerHTMLSniff.php
@@ -14,8 +14,6 @@
  * WordPressVIPMinimum_Sniffs_JS_InnerHTMLSniff.
  *
  * Looks for instances of .innerHMTL.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class InnerHTMLSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/JS/StringConcatSniff.php b/WordPressVIPMinimum/Sniffs/JS/StringConcatSniff.php
@@ -14,8 +14,6 @@
  * WordPressVIPMinimum_Sniffs_JS_StringConcatSniff.
  *
  * Looks for HTML string concatenation.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class StringConcatSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/JS/StrippingTagsSniff.php b/WordPressVIPMinimum/Sniffs/JS/StrippingTagsSniff.php
@@ -14,8 +14,6 @@
  * WordPressVIPMinimum_Sniffs_JS_StrippingTagsSniff.
  *
  * Looks for incorrect way of stripping tags.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class StrippingTagsSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/JS/WindowSniff.php b/WordPressVIPMinimum/Sniffs/JS/WindowSniff.php
@@ -14,8 +14,6 @@
  * WordPressVIPMinimum_Sniffs_JS_WindowSniff.
  *
  * Looks for instances of window properties that should be flagged.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class WindowSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Performance/CacheValueOverrideSniff.php b/WordPressVIPMinimum/Sniffs/Performance/CacheValueOverrideSniff.php
@@ -12,8 +12,6 @@
 
 /**
  * This sniff check whether a cached value is being overridden.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class CacheValueOverrideSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Performance/FetchingRemoteDataSniff.php b/WordPressVIPMinimum/Sniffs/Performance/FetchingRemoteDataSniff.php
@@ -13,8 +13,6 @@
 
 /**
  * Restricts usage of file_get_contents().
- *
- *  @package VIPCS\WordPressVIPMinimum
  */
 class FetchingRemoteDataSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Performance/LowExpiryCacheTimeSniff.php b/WordPressVIPMinimum/Sniffs/Performance/LowExpiryCacheTimeSniff.php
@@ -16,8 +16,6 @@
  *
  * {@internal VIP uses the Memcached object cache implementation. {@link https://github.com/Automattic/wp-memcached}}
  *
- * @package VIPCS\WordPressVIPMinimum
- *
  * @since 0.4.0
  */
 class LowExpiryCacheTimeSniff extends AbstractFunctionParameterSniff {

diff --git a/WordPressVIPMinimum/Sniffs/Performance/NoPagingSniff.php b/WordPressVIPMinimum/Sniffs/Performance/NoPagingSniff.php
@@ -16,9 +16,7 @@
  *
  * @link https://docs.wpvip.com/technical-references/code-review/#no-limit-queries
  *
- * @package VIPCS\WordPressVIPMinimum
- *
- * @since   0.5.0
+ * @since 0.5.0
  */
 class NoPagingSniff extends AbstractArrayAssignmentRestrictionsSniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Performance/OrderByRandSniff.php b/WordPressVIPMinimum/Sniffs/Performance/OrderByRandSniff.php
@@ -17,9 +17,7 @@
  *
  * @link https://docs.wpvip.com/technical-references/code-review/vip-errors/#h-order-by-rand
  *
- * @package VIPCS\WordPressVIPMinimum
- *
- * @since   0.5.0
+ * @since 0.5.0
  */
 class OrderByRandSniff extends AbstractArrayAssignmentRestrictionsSniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Performance/RegexpCompareSniff.php b/WordPressVIPMinimum/Sniffs/Performance/RegexpCompareSniff.php
@@ -12,8 +12,6 @@
 
 /**
  * Flag REGEXP and NOT REGEXP in meta compare
- *
- *  @package VIPCS\WordPressVIPMinimum
  */
 class RegexpCompareSniff extends AbstractArrayAssignmentRestrictionsSniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Performance/RemoteRequestTimeoutSniff.php b/WordPressVIPMinimum/Sniffs/Performance/RemoteRequestTimeoutSniff.php
@@ -11,8 +11,6 @@
 
 /**
  * Flag use of a timeout of more than 3 seconds for remote requests.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class RemoteRequestTimeoutSniff extends AbstractArrayAssignmentRestrictionsSniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Performance/TaxonomyMetaInOptionsSniff.php b/WordPressVIPMinimum/Sniffs/Performance/TaxonomyMetaInOptionsSniff.php
@@ -13,8 +13,6 @@
 
 /**
  * Restricts the implementation of taxonomy term meta via options.
- *
- *  @package VIPCS\WordPressVIPMinimum
  */
 class TaxonomyMetaInOptionsSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Performance/WPQueryParamsSniff.php b/WordPressVIPMinimum/Sniffs/Performance/WPQueryParamsSniff.php
@@ -14,8 +14,6 @@
  * Flag suspicious WP_Query and get_posts params.
  *
  * @link https://docs.wpvip.com/technical-references/caching/uncached-functions/
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class WPQueryParamsSniff extends AbstractArrayAssignmentRestrictionsSniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Security/EscapingVoidReturnFunctionsSniff.php b/WordPressVIPMinimum/Sniffs/Security/EscapingVoidReturnFunctionsSniff.php
@@ -17,8 +17,6 @@
  *
  * E.g. esc_html( _e( 'foo' ) );
  *
- * @package VIPCS\WordPressVIPMinimum
- *
  * @uses \WordPressCS\WordPress\Helpers\PrintingFunctionsTrait::$customPrintingFunctions
  */
 class EscapingVoidReturnFunctionsSniff extends Sniff {

diff --git a/WordPressVIPMinimum/Sniffs/Security/ExitAfterRedirectSniff.php b/WordPressVIPMinimum/Sniffs/Security/ExitAfterRedirectSniff.php
@@ -13,8 +13,6 @@
 
 /**
  * Require `exit;` being called after wp_redirect and wp_safe_redirect.
- *
- *  @package VIPCS\WordPressVIPMinimum
  */
 class ExitAfterRedirectSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Security/MustacheSniff.php b/WordPressVIPMinimum/Sniffs/Security/MustacheSniff.php
@@ -12,8 +12,6 @@
 
 /**
  * Looks for instances of unescaped output for Mustache templating engine and Handlebars.js.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class MustacheSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Security/PHPFilterFunctionsSniff.php b/WordPressVIPMinimum/Sniffs/Security/PHPFilterFunctionsSniff.php
@@ -12,8 +12,6 @@
 /**
  * This sniff ensures that proper sanitization is occurring when PHP's filter_* functions are used.
  *
- * @package VIPCS\WordPressVIPMinimum
- *
  * @since 0.4.0
  */
 class PHPFilterFunctionsSniff extends AbstractFunctionParameterSniff {

diff --git a/WordPressVIPMinimum/Sniffs/Security/ProperEscapingFunctionSniff.php b/WordPressVIPMinimum/Sniffs/Security/ProperEscapingFunctionSniff.php
@@ -15,8 +15,6 @@
 
 /**
  * Checks whether proper escaping function is used.
- *
- *  @package VIPCS\WordPressVIPMinimum
  */
 class ProperEscapingFunctionSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Security/StaticStrreplaceSniff.php b/WordPressVIPMinimum/Sniffs/Security/StaticStrreplaceSniff.php
@@ -13,8 +13,6 @@
 
 /**
  * Restricts usage of str_replace with all 3 params being static.
- *
- *  @package VIPCS\WordPressVIPMinimum
  */
 class StaticStrreplaceSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Security/TwigSniff.php b/WordPressVIPMinimum/Sniffs/Security/TwigSniff.php
@@ -12,8 +12,6 @@
 
 /**
  * Looks for instances of unescaped output for Twig templating engine.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class TwigSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Security/UnderscorejsSniff.php b/WordPressVIPMinimum/Sniffs/Security/UnderscorejsSniff.php
@@ -14,8 +14,6 @@
 
 /**
  * Looks for instances of unescaped output for Underscore.js templating engine.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class UnderscorejsSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Security/VuejsSniff.php b/WordPressVIPMinimum/Sniffs/Security/VuejsSniff.php
@@ -12,8 +12,6 @@
 
 /**
  * Looks for instances of unescaped output for Twig templating engine.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class VuejsSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Sniff.php b/WordPressVIPMinimum/Sniffs/Sniff.php
@@ -15,8 +15,6 @@
  * Represents a WordPress\Sniff for sniffing VIP coding standards.
  *
  * Provides a bootstrap for the sniffs, to reduce code duplication.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 abstract class Sniff extends WPCS_Sniff {
 }
diff --git a/WordPressVIPMinimum/Sniffs/UserExperience/AdminBarRemovalSniff.php b/WordPressVIPMinimum/Sniffs/UserExperience/AdminBarRemovalSniff.php
@@ -19,9 +19,7 @@
  *
  * @link https://docs.wpvip.com/technical-references/code-review/vip-warnings/#h-removing-the-admin-bar
  *
- * @package VIPCS\WordPressVIPMinimum
- *
- * @since   0.5.0
+ * @since 0.5.0
  */
 class AdminBarRemovalSniff extends AbstractFunctionParameterSniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Variables/RestrictedVariablesSniff.php b/WordPressVIPMinimum/Sniffs/Variables/RestrictedVariablesSniff.php
@@ -14,9 +14,7 @@
 /**
  * Restricts usage of some variables in VIP context.
  *
- * @package VIPCS\WordPressVIPMinimum
- *
- * @since   0.5.0
+ * @since 0.5.0
  */
 class RestrictedVariablesSniff extends AbstractVariableRestrictionsSniff {
 

diff --git a/WordPressVIPMinimum/Sniffs/Variables/ServerVariablesSniff.php b/WordPressVIPMinimum/Sniffs/Variables/ServerVariablesSniff.php
@@ -12,8 +12,6 @@
 
 /**
  * Restricts usage of some server variables.
- *
- * @package VIPCS\WordPressVIPMinimum
  */
 class ServerVariablesSniff extends Sniff {
 

diff --git a/WordPressVIPMinimum/Tests/Classes/DeclarationCompatibilityUnitTest.php b/WordPressVIPMinimum/Tests/Classes/DeclarationCompatibilityUnitTest.php
@@ -12,8 +12,6 @@
 /**
  * Unit test class for the DeclarationCompatibility sniff.
  *
- * @package VIPCS\WordPressVIPMinimum
- *
  * @covers \WordPressVIPMinimum\Sniffs\Classes\DeclarationCompatibilitySniff
  */
 class DeclarationCompatibilityUnitTest extends AbstractSniffUnitTest {

diff --git a/WordPressVIPMinimum/Tests/Classes/RestrictedExtendClassesUnitTest.php b/WordPressVIPMinimum/Tests/Classes/RestrictedExtendClassesUnitTest.php
@@ -12,8 +12,6 @@
 /**
  * Unit test class for the RestrictedExtendClasses sniff.
  *
- * @package VIPCS\WordPressVIPMinimum
- *
  * @covers \WordPressVIPMinimum\Sniffs\Classes\RestrictedExtendClassesSniff
  */
 class RestrictedExtendClassesUnitTest extends AbstractSniffUnitTest {