Merge pull request #154 from PHPCSStandards/docs/move-array-specs-to-return-tags

Docs: move array return value specs to the `@return` tag

Author: jrfnl

PHPCSUtils/Utils/ControlStructures.php

@@ -348,21 +348,21 @@ public static function getDeclareScopeOpenClose(File $phpcsFile, $stackPtr)
     /**
      * Retrieve the exception(s) being caught in a CATCH condition.
      *
-     * The returned array will contain the following information for each caught exception:
-     * ```php
-     * 0 => array(
-     *   'type'           => string,  // The type declaration for the exception being caught.
-     *   'type_token'     => integer, // The stack pointer to the start of the type declaration.
-     *   'type_end_token' => integer, // The stack pointer to the end of the type declaration.
-     * )
-     * ```
-     *
      * @since 1.0.0
      *
      * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
      * @param int                         $stackPtr  The position of the token we are checking.
      *
-     * @return array
+     * @return array Array with information about the caught Exception(s).
+     *               The returned array will contain the following information for
+     *               each caught exception:
+     *               ```php
+     *               0 => array(
+     *                 'type'           => string,  // The type declaration for the exception being caught.
+     *                 'type_token'     => integer, // The stack pointer to the start of the type declaration.
+     *                 'type_end_token' => integer, // The stack pointer to the end of the type declaration.
+     *               )
+     *               ```
      *
      * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified `$stackPtr` is not of
      *                                                      type `T_CATCH` or doesn't exist.

PHPCSUtils/Utils/FunctionDeclarations.php

@@ -160,24 +160,6 @@ public static function getName(File $phpcsFile, $stackPtr)
     /**
      * Retrieves the visibility and implementation properties of a method.
      *
-     * The format of the return value is:
-     * ```php
-     * array(
-     *   'scope'                 => 'public', // Public, private, or protected
-     *   'scope_specified'       => true,     // TRUE if the scope keyword was found.
-     *   'return_type'           => '',       // The return type of the method.
-     *   'return_type_token'     => integer,  // The stack pointer to the start of the return type
-     *                                        // or FALSE if there is no return type.
-     *   'return_type_end_token' => integer,  // The stack pointer to the end of the return type
-     *                                        // or FALSE if there is no return type.
-     *   'nullable_return_type'  => false,    // TRUE if the return type is nullable.
-     *   'is_abstract'           => false,    // TRUE if the abstract keyword was found.
-     *   'is_final'              => false,    // TRUE if the final keyword was found.
-     *   'is_static'             => false,    // TRUE if the static keyword was found.
-     *   'has_body'              => false,    // TRUE if the method has a body
-     * );
-     * ```
-     *
      * Main differences with the PHPCS version:
      * - Bugs fixed:
      *   - Handling of PHPCS annotations.
@@ -199,7 +181,24 @@ public static function getName(File $phpcsFile, $stackPtr)
      * @param int                         $stackPtr  The position in the stack of the function token to
      *                                               acquire the properties for.
      *
-     * @return array
+     * @return array Array with information about a function declaration.
+     *               The format of the return value is:
+     *               ```php
+     *               array(
+     *                 'scope'                 => 'public', // Public, private, or protected
+     *                 'scope_specified'       => true,     // TRUE if the scope keyword was found.
+     *                 'return_type'           => '',       // The return type of the method.
+     *                 'return_type_token'     => integer,  // The stack pointer to the start of the return type
+     *                                                      // or FALSE if there is no return type.
+     *                 'return_type_end_token' => integer,  // The stack pointer to the end of the return type
+     *                                                      // or FALSE if there is no return type.
+     *                 'nullable_return_type'  => false,    // TRUE if the return type is nullable.
+     *                 'is_abstract'           => false,    // TRUE if the abstract keyword was found.
+     *                 'is_final'              => false,    // TRUE if the final keyword was found.
+     *                 'is_static'             => false,    // TRUE if the static keyword was found.
+     *                 'has_body'              => false,    // TRUE if the method has a body
+     *               );
+     *               ```
      *
      * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified position is not a T_FUNCTION
      *                                                      or T_CLOSURE token, nor an arrow function.

PHPCSUtils/Utils/ObjectDeclarations.php

@@ -153,14 +153,6 @@ public static function getName(File $phpcsFile, $stackPtr)
     /**
      * Retrieves the implementation properties of a class.
      *
-     * The format of the return value is:
-     * ```php
-     * array(
-     *   'is_abstract' => false, // TRUE if the abstract keyword was found.
-     *   'is_final'    => false, // TRUE if the final keyword was found.
-     * );
-     * ```
-     *
      * Main differences with the PHPCS version:
      * - Bugs fixed:
      *   - Handling of PHPCS annotations.
@@ -177,7 +169,14 @@ public static function getName(File $phpcsFile, $stackPtr)
      * @param int                         $stackPtr  The position in the stack of the `T_CLASS`
      *                                               token to acquire the properties for.
      *
-     * @return array
+     * @return array Array with implementation properties of a class.
+     *               The format of the return value is:
+     *               ```php
+     *               array(
+     *                 'is_abstract' => false, // TRUE if the abstract keyword was found.
+     *                 'is_final'    => false, // TRUE if the final keyword was found.
+     *               );
+     *               ```
      *
      * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified position is not a
      *                                                      `T_CLASS` token.

PHPCSUtils/Utils/Variables.php

@@ -75,21 +75,6 @@ class Variables
     /**
      * Retrieve the visibility and implementation properties of a class member variable.
      *
-     * The format of the return value is:
-     * ```php
-     * array(
-     *   'scope'           => string,  // Public, private, or protected.
-     *   'scope_specified' => boolean, // TRUE if the scope was explicitly specified.
-     *   'is_static'       => boolean, // TRUE if the static keyword was found.
-     *   'type'            => string,  // The type of the var (empty if no type specified).
-     *   'type_token'      => integer, // The stack pointer to the start of the type
-     *                                 // or FALSE if there is no type.
-     *   'type_end_token'  => integer, // The stack pointer to the end of the type
-     *                                 // or FALSE if there is no type.
-     *   'nullable_type'   => boolean, // TRUE if the type is nullable.
-     * );
-     * ```
-     *
      * Main differences with the PHPCS version:
      * - Removed the parse error warning for properties in interfaces.
      *   This will now throw the same _"$stackPtr is not a class member var"_ runtime exception as
@@ -105,7 +90,21 @@ class Variables
      * @param int                         $stackPtr  The position in the stack of the `T_VARIABLE` token
      *                                               to acquire the properties for.
      *
-     * @return array
+     * @return array Array with information about the class member variable.
+     *               The format of the return value is:
+     *               ```php
+     *               array(
+     *                 'scope'           => string,  // Public, private, or protected.
+     *                 'scope_specified' => boolean, // TRUE if the scope was explicitly specified.
+     *                 'is_static'       => boolean, // TRUE if the static keyword was found.
+     *                 'type'            => string,  // The type of the var (empty if no type specified).
+     *                 'type_token'      => integer, // The stack pointer to the start of the type
+     *                                               // or FALSE if there is no type.
+     *                 'type_end_token'  => integer, // The stack pointer to the end of the type
+     *                                               // or FALSE if there is no type.
+     *                 'nullable_type'   => boolean, // TRUE if the type is nullable.
+     *               );
+     *               ```
      *
      * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified position is not a
      *                                                      `T_VARIABLE` token.