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

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.