Documentation: improve sniff class descriptions

PHPCompatibility/AbstractComplexVersionSniff.php

@@ -14,6 +14,8 @@
 
 /**
  * Abstract base class for sniffs based on complex arrays with PHP version information.
+ *
+ * @since 7.1.0
  */
 abstract class AbstractComplexVersionSniff extends Sniff implements ComplexVersionInterface
 {

PHPCompatibility/AbstractFunctionCallParameterSniff.php

@@ -16,6 +16,8 @@
 
 /**
  * Abstract class to use as a base for examining the parameter values passed to function calls.
+ *
+ * @since 8.2.0
  */
 abstract class AbstractFunctionCallParameterSniff extends Sniff
 {

PHPCompatibility/AbstractNewFeatureSniff.php

@@ -14,6 +14,8 @@
 
 /**
  * Base class for new feature sniffs.
+ *
+ * @since 7.1.0
  */
 abstract class AbstractNewFeatureSniff extends AbstractComplexVersionSniff
 {

PHPCompatibility/AbstractRemovedFeatureSniff.php

@@ -14,6 +14,8 @@
 
 /**
  * Base class for removed feature sniffs.
+ *
+ * @since 7.1.0
  */
 abstract class AbstractRemovedFeatureSniff extends AbstractComplexVersionSniff
 {

PHPCompatibility/ComplexVersionInterface.php

@@ -18,6 +18,8 @@
  * Interface to be implemented by sniffs using a multi-dimensional array of
  * PHP features (functions, classes etc) being sniffed for with version
  * information in sub-arrays.
+ *
+ * @since 7.1.0
  */
 interface ComplexVersionInterface
 {

PHPCompatibility/PHPCSHelper.php

@@ -21,6 +21,16 @@
  * Those classes cannot be aliased as they don't represent the same object.
  * This class provides helper methods for functions which were contained in
  * one of these classes and which are used within the PHPCompatibility library.
+ *
+ * Additionally, this class contains some duplicates of PHPCS native methods.
+ * These methods have received bug fixes or improved functionality between the
+ * lowest supported PHPCS version and the latest PHPCS stable version and
+ * to provide the same results cross-version, PHPCompatibility needs to use
+ * the up-to-date versions of these methods.
+ *
+ * @since 8.0.0
+ * @since 8.2.0 The duplicate PHPCS methods have been moved from the `Sniff`
+ *              base class to this class.
  */
 class PHPCSHelper
 {

PHPCompatibility/Sniff.php

@@ -18,6 +18,8 @@
 
 /**
  * Base class from which all PHPCompatibility sniffs extend.
+ *
+ * @since 5.6
  */
 abstract class Sniff implements PHPCS_Sniff
 {

PHPCompatibility/Sniffs/Classes/ForbiddenAbstractPrivateMethodsSniff.php

@@ -17,13 +17,13 @@
  * Abstract private methods are not allowed since PHP 5.1.
  *
  * Abstract private methods were supported between PHP 5.0.0 and PHP 5.0.4, but
- * were then disallowed on the grounds that the behaviours of private and abstract
+ * were then disallowed on the grounds that the behaviours of `private` and `abstract`
  * are mutually exclusive.
  *
- * @link https://www.php.net/manual/en/migration51.oop.php#migration51.oop-methods
- *
  * PHP version 5.1
  *
+ * @link https://www.php.net/manual/en/migration51.oop.php#migration51.oop-methods
+ *
  * @since 9.2.0
  */
 class ForbiddenAbstractPrivateMethodsSniff extends Sniff

PHPCompatibility/Sniffs/Classes/NewAnonymousClassesSniff.php

@@ -15,9 +15,14 @@
 use PHP_CodeSniffer_Tokens as Tokens;
 
 /**
- * Anonymous classes are supported in PHP 7.0
+ * Anonymous classes are supported since PHP 7.0.
  *
  * PHP version 7.0
+ *
+ * @link https://www.php.net/manual/en/language.oop5.anonymous.php
+ * @link https://wiki.php.net/rfc/anonymous_classes
+ *
+ * @since 7.0.0
  */
 class NewAnonymousClassesSniff extends Sniff
 {

PHPCompatibility/Sniffs/Classes/NewClassesSniff.php

@@ -15,6 +15,20 @@
 
 /**
  * Detect use of new PHP native classes.
+ *
+ * The sniff analyses the following constructs to find usage of new classes:
+ * - Class instantiation using the `new` keyword.
+ * - (Anonymous) Class declarations to detect new classes being extended by userland classes.
+ * - Static use of class properties, constants or functions using the double colon.
+ * - Function/closure declarations to detect new classes used as parameter type declarations.
+ * - Function/closure declarations to detect new classes used as return type declarations.
+ * - Try/catch statements to detect new exception classes being caught.
+ *
+ * PHP version All
+ *
+ * @since 5.5
+ * @since 5.6   Now extends the base `Sniff` class.
+ * @since 7.1.0 Now extends the `AbstractNewFeatureSniff` class.
  */
 class NewClassesSniff extends AbstractNewFeatureSniff
 {

PHPCompatibility/Sniffs/Classes/NewConstVisibilitySniff.php

@@ -18,6 +18,11 @@
  * Visibility for class constants is available since PHP 7.1.
  *
  * PHP version 7.1
+ *
+ * @link https://wiki.php.net/rfc/class_const_visibility
+ * @link https://www.php.net/manual/en/language.oop5.constants.php#language.oop5.basic.class.this
+ *
+ * @since 7.0.7
  */
 class NewConstVisibilitySniff extends Sniff
 {

PHPCompatibility/Sniffs/Classes/NewLateStaticBindingSniff.php

@@ -17,7 +17,17 @@
 /**
  * Detect use of late static binding as introduced in PHP 5.3.
  *
+ * Checks for:
+ * - Late static binding as introduced in PHP 5.3.
+ * - Late static binding being used outside of class scope (unsupported).
+ *
  * PHP version 5.3
+ *
+ * @link https://www.php.net/manual/en/language.oop5.late-static-bindings.php
+ * @link https://wiki.php.net/rfc/lsb_parentself_forwarding
+ *
+ * @since 7.0.3
+ * @since 9.0.0 Renamed from `LateStaticBindingSniff` to `NewLateStaticBindingSniff`.
  */
 class NewLateStaticBindingSniff extends Sniff
 {

PHPCompatibility/Sniffs/Classes/NewTypedPropertiesSniff.php

@@ -15,10 +15,11 @@
 use PHP_CodeSniffer_Tokens as Tokens;
 
 /**
- * Typed properties are available since PHP 7.4.
+ * Typed class property declarations are available since PHP 7.4.
  *
  * PHP version 7.4
  *
+ * @link https://www.php.net/manual/en/migration74.new-features.php#migration74.new-features.core.typed-properties
  * @link https://wiki.php.net/rfc/typed_properties_v2
  *
  * @since 9.2.0

PHPCompatibility/Sniffs/Classes/RemovedOrphanedParentSniff.php

@@ -14,15 +14,15 @@
 use PHP_CodeSniffer_File as File;
 
 /**
- * Using "parent" inside a class without parent is deprecated since PHP 7.4.
+ * Using `parent` inside a class without parent is deprecated since PHP 7.4.
  *
  * This will throw a compile-time error in the future. Currently an error will only
  * be generated if/when the parent is accessed at run-time.
  *
- * @link https://github.com/php/php-src/blob/42cc58ff7b2fee1c17a00dc77a4873552ffb577f/UPGRADING#L303
- *
  * PHP version 7.4
  *
+ * @link https://www.php.net/manual/en/migration74.deprecated.php#migration74.deprecated.core.parent
+ *
  * @since 9.2.0
  */
 class RemovedOrphanedParentSniff extends Sniff

PHPCompatibility/Sniffs/Constants/NewConstantsSniff.php

@@ -15,6 +15,10 @@
 
 /**
  * Detect use of new PHP native global constants.
+ *
+ * PHP version All
+ *
+ * @since 8.1.0
  */
 class NewConstantsSniff extends AbstractNewFeatureSniff
 {

PHPCompatibility/Sniffs/Constants/NewMagicClassConstantSniff.php

@@ -15,10 +15,18 @@
 use PHP_CodeSniffer_Tokens as Tokens;
 
 /**
- * The special ClassName::class constant is available as of PHP 5.5.0, and allows for
- * fully qualified class name resolution at compile.
+ * Detect usage of the magic `::class` constant introduced in PHP 5.5.
+ *
+ * The special `ClassName::class` constant is available as of PHP 5.5.0, and allows
+ * for fully qualified class name resolution at compile time.
  *
  * PHP version 5.5
+ *
+ * @link https://wiki.php.net/rfc/class_name_scalars
+ * @link https://www.php.net/manual/en/language.oop5.constants.php#example-186
+ *
+ * @since 7.1.4
+ * @since 7.1.5 Removed the incorrect checks against invalid usage of the constant.
  */
 class NewMagicClassConstantSniff extends Sniff
 {

PHPCompatibility/Sniffs/Constants/RemovedConstantsSniff.php

@@ -15,6 +15,10 @@
 
 /**
  * Detect use of deprecated and/or removed PHP native global constants.
+ *
+ * PHP version All
+ *
+ * @since 8.1.0
  */
 class RemovedConstantsSniff extends AbstractRemovedFeatureSniff
 {

PHPCompatibility/Sniffs/ControlStructures/DiscouragedSwitchContinueSniff.php

@@ -15,9 +15,21 @@
 use PHP_CodeSniffer_Tokens as Tokens;
 
 /**
- * PHP 7.3 will throw a warning when continue is used to target a switch control structure.
+ * Detect use of `continue` in `switch` control structures.
+ *
+ * As of PHP 7.3, PHP will throw a warning when `continue` is used to target a `switch`
+ * control structure.
+ * The sniff takes numeric arguments used with `continue` into account.
  *
  * PHP version 7.3
+ *
+ * @link https://www.php.net/manual/en/migration73.incompatible.php#migration73.incompatible.core.continue-targeting-switch
+ * @link https://wiki.php.net/rfc/continue_on_switch_deprecation
+ * @link https://github.com/php/php-src/commit/04e3523b7d095341f65ed5e71a3cac82fca690e4
+ *       (actual implementation which is different from the RFC).
+ * @link https://www.php.net/manual/en/control-structures.switch.php
+ *
+ * @since 8.2.0
  */
 class DiscouragedSwitchContinueSniff extends Sniff
 {

PHPCompatibility/Sniffs/ControlStructures/ForbiddenBreakContinueOutsideLoopSniff.php

@@ -14,9 +14,15 @@
 use PHP_CodeSniffer_File as File;
 
 /**
- * Forbids use of break or continue statements outside of looping structures.
+ * Detect using `break` and/or `continue` statements outside of a looping structure.
  *
  * PHP version 7.0
+ *
+ * @link https://www.php.net/manual/en/migration70.incompatible.php#migration70.incompatible.other.break-continue
+ * @link https://www.php.net/manual/en/control-structures.break.php
+ * @link https://www.php.net/manual/en/control-structures.continue.php
+ *
+ * @since 7.0.7
  */
 class ForbiddenBreakContinueOutsideLoopSniff extends Sniff
 {

PHPCompatibility/Sniffs/ControlStructures/ForbiddenBreakContinueVariableArgumentsSniff.php

@@ -15,9 +15,20 @@
 use PHP_CodeSniffer_Tokens as Tokens;
 
 /**
- * Forbids variable arguments on break or continue statements.
+ * Detects using 0 and variable numeric arguments on `break` and `continue` statements.
+ *
+ * This sniff checks for:
+ * - Using `break` and/or `continue` with a variable as the numeric argument.
+ * - Using `break` and/or `continue` with a zero - 0 - as the numeric argument.
  *
  * PHP version 5.4
+ *
+ * @link https://www.php.net/manual/en/migration54.incompatible.php
+ * @link https://www.php.net/manual/en/control-structures.break.php
+ * @link https://www.php.net/manual/en/control-structures.continue.php
+ *
+ * @since 5.5
+ * @since 5.6 Now extends the base `Sniff` class.
  */
 class ForbiddenBreakContinueVariableArgumentsSniff extends Sniff
 {

PHPCompatibility/Sniffs/ControlStructures/ForbiddenSwitchWithMultipleDefaultBlocksSniff.php

@@ -14,9 +14,14 @@
 use PHP_CodeSniffer_File as File;
 
 /**
- * Switch statements can not have multiple default blocks since PHP 7.0
+ * Switch statements can not have multiple default blocks since PHP 7.0.
  *
  * PHP version 7.0
+ *
+ * @link https://wiki.php.net/rfc/switch.default.multiple
+ * @link https://www.php.net/manual/en/control-structures.switch.php
+ *
+ * @since 7.0.0
  */
 class ForbiddenSwitchWithMultipleDefaultBlocksSniff extends Sniff
 {

PHPCompatibility/Sniffs/ControlStructures/NewExecutionDirectivesSniff.php

@@ -17,6 +17,23 @@
 
 /**
  * Check for valid execution directives set with `declare()`.
+ *
+ * The sniff contains three distinct checks:
+ * - Check if the execution directive used is valid. PHP currently only supports
+ *   three execution directives.
+ * - Check if the execution directive used is available in the PHP versions
+ *   for which support is being checked.
+ *   In the case of the `encoding` directive on PHP 5.3, support is conditional
+ *   on the `--enable-zend-multibyte` compilation option. This will be indicated as such.
+ * - Check whether the value for the directive is valid.
+ *
+ * PHP version All
+ *
+ * @link https://www.php.net/manual/en/control-structures.declare.php
+ * @link https://wiki.php.net/rfc/scalar_type_hints_v5#strict_types_declare_directive
+ *
+ * @since 7.0.3
+ * @since 7.1.0 Now extends the `AbstractNewFeatureSniff` instead of the base `Sniff` class.
  */
 class NewExecutionDirectivesSniff extends AbstractNewFeatureSniff
 {

PHPCompatibility/Sniffs/ControlStructures/NewForeachExpressionReferencingSniff.php

@@ -14,12 +14,16 @@
 use PHP_CodeSniffer_File as File;
 
 /**
- * New `foreach` Expression Referencing.
+ * Detect `foreach` expression referencing.
  *
- * Before PHP 5.5.0, referencing $value is only possible if the iterated array
- * can be referenced (i.e. if it is a variable).
+ * Before PHP 5.5.0, referencing `$value` in a `foreach` was only possible
+ * if the iterated array could be referenced (i.e. if it is a variable).
  *
  * PHP version 5.5
+ *
+ * @link https://www.php.net/manual/en/control-structures.foreach.php
+ *
+ * @since 9.0.0
  */
 class NewForeachExpressionReferencingSniff extends Sniff
 {

PHPCompatibility/Sniffs/ControlStructures/NewListInForeachSniff.php

@@ -14,9 +14,15 @@
 use PHP_CodeSniffer_File as File;
 
 /**
- * Detect unpacking nested arrays with list() in a foreach().
+ * Detect unpacking nested arrays with `list()` in a `foreach()` as available since PHP 5.5.
  *
  * PHP version 5.5
+ *
+ * @link https://www.php.net/manual/en/migration55.new-features.php#migration55.new-features.foreach-list
+ * @link https://wiki.php.net/rfc/foreachlist
+ * @link https://www.php.net/manual/en/control-structures.foreach.php#control-structures.foreach.list
+ *
+ * @since 9.0.0
  */
 class NewListInForeachSniff extends Sniff
 {

PHPCompatibility/Sniffs/ControlStructures/NewMultiCatchSniff.php

@@ -17,6 +17,12 @@
  * Catching multiple exception types in one statement is available since PHP 7.1.
  *
  * PHP version 7.1
+ *
+ * @link https://www.php.net/manual/en/migration71.new-features.php#migration71.new-features.mulit-catch-exception-handling
+ * @link https://wiki.php.net/rfc/multiple-catch
+ * @link https://www.php.net/manual/en/language.exceptions.php#language.exceptions.catch
+ *
+ * @since 7.0.7
  */
 class NewMultiCatchSniff extends Sniff
 {