Merge pull request #148 from PHPCSStandards/docs/enhance-documentation-texts

Docs: enhance documentation

Author: jrfnl

PHPCSUtils/AbstractSniffs/AbstractArrayDeclarationSniff.php

@@ -69,7 +69,7 @@ abstract class AbstractArrayDeclarationSniff implements Sniff
      *
      * The array index is 1-based and contains the following information on each array item:
      * - 'start' : The stack pointer to the first token in the array item.
-     * - 'end'   : The stack pointer to the first token in the array item.
+     * - 'end'   : The stack pointer to the last token in the array item.
      * - 'raw'   : A string with the contents of all tokens between `start` and `end`.
      * - 'clean' : Same as `raw`, but all comment tokens have been stripped out.
      *
@@ -100,6 +100,8 @@ abstract class AbstractArrayDeclarationSniff implements Sniff
     /**
      * List of tokens which can safely be used with an eval() expression.
      *
+     * This list gets enhanced with additional token groups in the constructor.
+     *
      * @since 1.0.0
      *
      * @var array
@@ -203,7 +205,19 @@ final public function process(File $phpcsFile, $stackPtr)
     /**
      * Process every part of the array declaration.
      *
-     * This contains the default logic for the sniff, but can be overloaded in a concrete child class
+     * Controller which calls the individual `process...()` methods for each part of the array.
+     *
+     * The method starts by calling the {@see AbstractArrayDeclarationSniff::processOpenClose()} method
+     * and subsequently calls the following methods for each array item:
+     *
+     * Unkeyed arrays | Keyed arrays
+     * -------------- | ------------
+     * processNoKey() | processKey()
+     * -              | processArrow()
+     * processValue() | processValue()
+     * processComma() | processComma()
+     *
+     * This is the default logic for the sniff, but can be overloaded in a concrete child class
      * if needed.
      *
      * @since 1.0.0
@@ -265,7 +279,7 @@ public function processArray(File $phpcsFile)
     /**
      * Process the array opener and closer.
      *
-     * Optional method to be implemented in concrete child classes.
+     * Optional method to be implemented in concrete child classes. By default, this method does nothing.
      *
      * @since 1.0.0
      *
@@ -277,6 +291,8 @@ public function processArray(File $phpcsFile)
      * @param int                         $closePtr  The position of the array closer token in the token stack.
      *
      * @return true|void Returning `true` will short-circuit the sniff and stop processing.
+     *                   In effect, this means that the sniff will not examine the individual
+     *                   array items if `true` is returned.
      */
     public function processOpenClose(File $phpcsFile, $openPtr, $closePtr)
     {
@@ -285,10 +301,10 @@ public function processOpenClose(File $phpcsFile, $openPtr, $closePtr)
     /**
      * Process the tokens in an array key.
      *
-     * Optional method to be implemented in concrete child classes.
+     * Optional method to be implemented in concrete child classes. By default, this method does nothing.
      *
-     * The $startPtr and $endPtr do not discount whitespace or comments, but are all inclusive to
-     * allow examining all tokens in an array key.
+     * Note: The `$startPtr` and `$endPtr` do not discount whitespace or comments, but are all inclusive
+     * to allow for examining all tokens in an array key.
      *
      * @since 1.0.0
      *
@@ -306,6 +322,8 @@ public function processOpenClose(File $phpcsFile, $openPtr, $closePtr)
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
      * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     *                   In effect, this means that the sniff will not examine the double arrow, the array
+     *                   value or comma for this array item and will not process any array items after this one.
      */
     public function processKey(File $phpcsFile, $startPtr, $endPtr, $itemNr)
     {
@@ -314,12 +332,17 @@ public function processKey(File $phpcsFile, $startPtr, $endPtr, $itemNr)
     /**
      * Process an array item without an array key.
      *
-     * Optional method to be implemented in concrete child classes.
+     * Optional method to be implemented in concrete child classes. By default, this method does nothing.
+     *
+     * Note: This method is _not_ intended for processing the array _value_. Use the
+     * {@see AbstractArrayDeclarationSniff::processValue()} method to implement processing of the array value.
      *
      * @since 1.0.0
      *
      * @codeCoverageIgnore
      *
+     * @see \PHPCSUtils\AbstractSniffs\AbstractArrayDeclarationSniff::processValue() Method to process the array value.
+     *
      * @param \PHP_CodeSniffer\Files\File $phpcsFile The PHP_CodeSniffer file where the
      *                                               token was found.
      * @param int                         $startPtr  The stack pointer to the first token in the array item,
@@ -329,6 +352,8 @@ public function processKey(File $phpcsFile, $startPtr, $endPtr, $itemNr)
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
      * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     *                   In effect, this means that the sniff will not examine the array value or
+     *                   comma for this array item and will not process any array items after this one.
      */
     public function processNoKey(File $phpcsFile, $startPtr, $itemNr)
     {
@@ -337,7 +362,7 @@ public function processNoKey(File $phpcsFile, $startPtr, $itemNr)
     /**
      * Process the double arrow.
      *
-     * Optional method to be implemented in concrete child classes.
+     * Optional method to be implemented in concrete child classes. By default, this method does nothing.
      *
      * @since 1.0.0
      *
@@ -350,6 +375,8 @@ public function processNoKey(File $phpcsFile, $startPtr, $itemNr)
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
      * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     *                   In effect, this means that the sniff will not examine the array value or
+     *                   comma for this array item and will not process any array items after this one.
      */
     public function processArrow(File $phpcsFile, $arrowPtr, $itemNr)
     {
@@ -358,10 +385,10 @@ public function processArrow(File $phpcsFile, $arrowPtr, $itemNr)
     /**
      * Process the tokens in an array value.
      *
-     * Optional method to be implemented in concrete child classes.
+     * Optional method to be implemented in concrete child classes. By default, this method does nothing.
      *
-     * The $startPtr and $endPtr do not discount whitespace or comments, but are all inclusive to
-     * allow examining all tokens in an array value.
+     * Note: The `$startPtr` and `$endPtr` do not discount whitespace or comments, but are all inclusive
+     * to allow for examining all tokens in an array value.
      *
      * @since 1.0.0
      *
@@ -377,6 +404,8 @@ public function processArrow(File $phpcsFile, $arrowPtr, $itemNr)
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
      * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     *                   In effect, this means that the sniff will not examine the comma for this
+     *                   array item and will not process any array items after this one.
      */
     public function processValue(File $phpcsFile, $startPtr, $endPtr, $itemNr)
     {
@@ -385,7 +414,7 @@ public function processValue(File $phpcsFile, $startPtr, $endPtr, $itemNr)
     /**
      * Process the comma after an array item.
      *
-     * Optional method to be implemented in concrete child classes.
+     * Optional method to be implemented in concrete child classes. By default, this method does nothing.
      *
      * @since 1.0.0
      *
@@ -398,6 +427,8 @@ public function processValue(File $phpcsFile, $startPtr, $endPtr, $itemNr)
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
      * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     *                   In effect, this means that the sniff will not process any array items
+     *                   after this one.
      */
     public function processComma(File $phpcsFile, $commaPtr, $itemNr)
     {
@@ -406,7 +437,8 @@ public function processComma(File $phpcsFile, $commaPtr, $itemNr)
     /**
      * Determine what the actual array key would be.
      *
-     * Optional helper function for processsing array keys in the processKey() function.
+     * Helper function for processsing array keys in the processKey() function.
+     * Using this method is up to the sniff implementation in the child class.
      *
      * @since 1.0.0
      *

PHPCSUtils/BackCompat/BCFile.php

@@ -63,7 +63,7 @@
  *   array return type declarations.
  * - Typed properties were not recognized prior to PHPCS 3.5.0, including the
  *   `?` nullability token not being converted to `T_NULLABLE`.
- * - Arrow functions were not recognized properly until PHPCS 3.5.3.
+ * - Arrow functions were not recognized properly until PHPCS 3.5.3/4.
  * - General PHP cross-version incompatibilities.
  *
  * Most functions in this class will have a related twin-function in the relevant
@@ -76,7 +76,7 @@
  * The differences between the functions here and the twin functions are documented
  * in the docblock of the respective twin-function.
  *
- * @see \PHP_CodeSniffer\Files\File Source of these utility methods.
+ * @see \PHP_CodeSniffer\Files\File Original source of these utility methods.
  *
  * @since 1.0.0
  */
@@ -104,7 +104,8 @@ class BCFile
      *
      * Note: For ES6 classes in combination with PHPCS 2.x, passing a `T_STRING` token to
      *       this method will be accepted for JS files.
-     * Note: support for JS ES6 method syntax has not been back-filled for PHPCS < 3.0.0.
+     * Note: Support for JS ES6 method syntax has not been back-filled for PHPCS < 3.0.0.
+     *       and sniffing JS files is not officially supported by PHPCSUtils.
      *
      * @see \PHP_CodeSniffer\Files\File::getDeclarationName() Original source.
      * @see \PHPCSUtils\Utils\ObjectDeclarations::getName()   PHPCSUtils native improved version.
@@ -232,8 +233,8 @@ public static function getDeclarationName(File $phpcsFile, $stackPtr)
      * - PHPCS 3.3.0: The return array now contains a new "type_hint_token" array index.
      *                - Provides the position in the token stack of the first token in the type declaration.
      * - PHPCS 3.3.1: Fixed incompatibility with PHP 7.3.
-     * - PHPCS 3.5.0: The Exception thrown changed from a `TokenizerException` to
-     *                `\PHP_CodeSniffer\Exceptions\RuntimeException`.
+     * - PHPCS 3.5.0: The Exception thrown changed from a `\PHP_CodeSniffer\Exceptions\TokenizerException`
+     *                to `\PHP_CodeSniffer\Exceptions\RuntimeException`.
      * - PHPCS 3.5.0: Added support for closure USE groups.
      * - PHPCS 3.5.0: The return array now contains yet more more information.
      *                - If a type hint is specified, the position of the last token in the hint will be
@@ -526,8 +527,8 @@ public static function getMethodParameters(File $phpcsFile, $stackPtr)
      * - PHPCS 3.4.0: New `has_body` array index.
      *                - `false` if the method has no body (as with abstract and interface methods)
      *                  or `true` otherwise.
-     * - PHPCS 3.5.0: The Exception thrown changed from a `TokenizerException` to
-     *                `\PHP_CodeSniffer\Exceptions\RuntimeException`.
+     * - PHPCS 3.5.0: The Exception thrown changed from a `\PHP_CodeSniffer\Exceptions\TokenizerException`
+     *                to `\PHP_CodeSniffer\Exceptions\RuntimeException`.
      * - PHPCS 3.5.3: Added support for PHP 7.4 T_FN arrow functions.
      *
      * @see \PHP_CodeSniffer\Files\File::getMethodProperties()      Original source.
@@ -731,8 +732,8 @@ public static function getMethodProperties(File $phpcsFile, $stackPtr)
      *                - If the type is nullable, a `nullable_type` array index will also be set to TRUE.
      *                - If the type contains namespace information, it will be cleaned of whitespace
      *                  and comments in the `type` value.
-     * - PHPCS 3.5.0: The Exception thrown changed from a `TokenizerException` to
-     *                `\PHP_CodeSniffer\Exceptions\RuntimeException`.
+     * - PHPCS 3.5.0: The Exception thrown changed from a `\PHP_CodeSniffer\Exceptions\TokenizerException`
+     *                to `\PHP_CodeSniffer\Exceptions\RuntimeException`.
      *
      * @see \PHP_CodeSniffer\Files\File::getMemberProperties() Original source.
      * @see \PHPCSUtils\Utils\Variables::getMemberProperties() PHPCSUtils native improved version.
@@ -899,8 +900,8 @@ public static function getMemberProperties(File $phpcsFile, $stackPtr)
      * - Introduced in PHPCS 1.3.0.
      * - PHPCS 3.0.0: The Exception thrown changed from a `PHP_CodeSniffer_Exception` to
      *                `\PHP_CodeSniffer\Exceptions\TokenizerException`.
-     * - PHPCS 3.5.0: The Exception thrown changed from a `TokenizerException` to
-     *                `\PHP_CodeSniffer\Exceptions\RuntimeException`.
+     * - PHPCS 3.5.0: The Exception thrown changed from a `\PHP_CodeSniffer\Exceptions\TokenizerException`
+     *                to`\PHP_CodeSniffer\Exceptions\RuntimeException`.
      *
      * @see \PHP_CodeSniffer\Files\File::getClassProperties()          Original source.
      * @see \PHPCSUtils\Utils\ObjectDeclarations::getClassProperties() PHPCSUtils native improved version.

PHPCSUtils/BackCompat/BCTokens.php

@@ -111,6 +111,8 @@ public static function __callStatic($name, $args)
     }
 
     /**
+     * Tokens that represent assignment operators.
+     *
      * Retrieve the PHPCS assignment tokens array in a cross-version compatible manner.
      *
      * Changelog for the PHPCS native array:
@@ -146,6 +148,8 @@ public static function assignmentTokens()
     }
 
     /**
+     * Tokens that represent comparison operators.
+     *
      * Retrieve the PHPCS comparison tokens array in a cross-version compatible manner.
      *
      * Changelog for the PHPCS native array:
@@ -173,6 +177,8 @@ public static function comparisonTokens()
     }
 
     /**
+     * Tokens that represent arithmetic operators.
+     *
      * Retrieve the PHPCS arithmetic tokens array in a cross-version compatible manner.
      *
      * Changelog for the PHPCS native array:
@@ -193,6 +199,8 @@ public static function arithmeticTokens()
     }
 
     /**
+     * Tokens that perform operations.
+     *
      * Retrieve the PHPCS operator tokens array in a cross-version compatible manner.
      *
      * Changelog for the PHPCS native array:
@@ -228,6 +236,8 @@ public static function operators()
     }
 
     /**
+     * Token types that open parentheses.
+     *
      * Retrieve the PHPCS parenthesis openers tokens array in a cross-version compatible manner.
      *
      * Changelog for the PHPCS native array:
@@ -236,9 +246,14 @@ public static function operators()
      *
      * Note: While `T_LIST` and `T_ANON_CLASS` will be included in the return value for this
      * method, the associated parentheses will not have the `'parenthesis_owner'` index set
-     * until PHPCS 3.5.0.
+     * until PHPCS 3.5.0. Use the {@see \PHPCSUtils\Utils\Parentheses::getOwner()}
+     * or {@see \PHPCSUtils\Utils\Parentheses::hasOwner()} methods if you need to check for
+     * a `T_LIST` or `T_ANON_CLASS` parentheses owner.
      *
      * @see \PHP_CodeSniffer\Util\Tokens::$parenthesisOpeners Original array.
+     * @see \PHPCSUtils\Utils\Parentheses                     Class holding utility methods for
+     *                                                        working with the `'parenthesis_...'`
+     *                                                        index keys in a token array.
      *
      * @since 1.0.0
      *
@@ -254,10 +269,13 @@ public static function parenthesisOpeners()
     }
 
     /**
+     * Tokens that are comments containing PHPCS instructions.
+     *
      * Retrieve the PHPCS comment tokens array in a cross-version compatible manner.
      *
      * Changelog for the PHPCS native array:
-     * - Introduced in PHPCS 3.2.3.
+     * - Introduced in PHPCS 3.2.3. The PHPCS comment tokens, however, were introduced in
+     *   PHPCS 3.2.0.
      *
      * @see \PHP_CodeSniffer\Util\Tokens::$phpcsCommentTokens Original array.
      *
@@ -290,6 +308,8 @@ public static function phpcsCommentTokens()
     }
 
     /**
+     * Tokens that represent text strings.
+     *
      * Retrieve the PHPCS text string tokens array in a cross-version compatible manner.
      *
      * Changelog for the PHPCS native array:
@@ -311,6 +331,8 @@ public static function textStringTokens()
     }
 
     /**
+     * Tokens that represent the names of called functions.
+     *
      * Retrieve the PHPCS function name tokens array in a cross-version compatible manner.
      *
      * Changelog for the PHPCS native array:
@@ -333,6 +355,8 @@ public static function functionNameTokens()
     }
 
     /**
+     * Tokens that open class and object scopes.
+     *
      * Retrieve the OO scope tokens array in a cross-version compatible manner.
      *
      * Changelog for the PHPCS native array:

PHPCSUtils/BackCompat/Helper.php

@@ -97,6 +97,9 @@ public static function setConfigData($key, $value, $temp = false, $config = null
     /**
      * Get the value of a single PHP_CodeSniffer config key.
      *
+     * @see Helper::getCommandLineData() Alternative for the same which is more reliable
+     *                                   if the `$phpcsFile` object is available.
+     *
      * @since 1.0.0
      *
      * @param string $key The name of the config value.