Documentation: various minor improvements

... picked up along the way.

Fixes:
* A few typos.
* Alignment of parameter descriptions.
* Wrong example code for some sniffs implementing an abstract sniff.
* A warning about commented out code which would start showing once PHPCS 3.6.0 will be released.

Author: jrfnl

WordPressVIPMinimum/Sniffs/Functions/CheckReturnValueSniff.php

@@ -291,7 +291,7 @@ public function findNonCheckedVariables( $stackPtr ) {
 	 * Function used as as callback for the array_reduce call.
 	 *
 	 * @param string $carry The final string.
-	 * @param array  $item Processed item.
+	 * @param array  $item  Processed item.
 	 *
 	 * @return string
 	 */

WordPressVIPMinimum/Sniffs/Functions/RestrictedFunctionsSniff.php

@@ -396,7 +396,7 @@ public function is_targetted_token( $stackPtr ) {
 				if ( isset( $skipped[ $this->tokens[ $prev ]['code'] ] ) ) {
 					return false;
 				}
-				// Skip namespaced functions, ie: \foo\bar() not \bar().
+				// Skip namespaced functions, ie: `\foo\bar()` not `\bar()`.
 				if ( $this->tokens[ $prev ]['code'] === \T_NS_SEPARATOR ) {
 					$pprev = $this->phpcsFile->findPrevious( Tokens::$emptyTokens, $prev - 1, null, true );
 					if ( $pprev !== false && $this->tokens[ $pprev ]['code'] === \T_STRING ) {

WordPressVIPMinimum/Sniffs/Hooks/AlwaysReturnInFilterSniff.php

@@ -122,8 +122,8 @@ private function processArray( $stackPtr ) {
 	 * Process string.
 	 *
 	 * @param int $stackPtr The position in the stack where the token was found.
-	 * @param int $start The start of the token.
-	 * @param int $end The end of the token.
+	 * @param int $start    The start of the token.
+	 * @param int $end      The end of the token.
 	 */
 	private function processString( $stackPtr, $start = 0, $end = null ) {
 
@@ -149,8 +149,8 @@ private function processString( $stackPtr, $start = 0, $end = null ) {
 	 * Process function.
 	 *
 	 * @param int $stackPtr The position in the stack where the token was found.
-	 * @param int $start The start of the token.
-	 * @param int $end The end of the token.
+	 * @param int $start    The start of the token.
+	 * @param int $end      The end of the token.
 	 */
 	private function processFunction( $stackPtr, $start = 0, $end = null ) {
 

WordPressVIPMinimum/Sniffs/Hooks/PreGetPostsSniff.php

@@ -195,7 +195,7 @@ private function processClosure( $stackPtr ) {
 	/**
 	 * Process function's body
 	 *
-	 * @param int    $stackPtr The position in the stack where the token was found.
+	 * @param int    $stackPtr     The position in the stack where the token was found.
 	 * @param string $variableName Variable name.
 	 */
 	private function processFunctionBody( $stackPtr, $variableName ) {
@@ -363,7 +363,7 @@ private function isEarlyMainQueryCheck( $stackPtr ) {
 	 * Is the current code a WP_Query call?
 	 *
 	 * @param int  $stackPtr The position in the stack where the token was found.
-	 * @param null $method Method.
+	 * @param null $method   Method.
 	 *
 	 * @return bool
 	 */

WordPressVIPMinimum/Sniffs/JS/StringConcatSniff.php

@@ -65,8 +65,8 @@ public function process_token( $stackPtr ) {
 	/**
 	 * Consolidated violation.
 	 *
-	 * @param int   $stackPtr  The position of the current token in the stack passed in $tokens.
-	 * @param array $data      Replacements for the error message.
+	 * @param int   $stackPtr The position of the current token in the stack passed in $tokens.
+	 * @param array $data     Replacements for the error message.
 	 */
 	private function addFoundError( $stackPtr, array $data ) {
 		$message = 'HTML string concatenation detected, this is a security risk, use DOM node construction or a templating language instead: %s.';

WordPressVIPMinimum/Sniffs/Performance/RegexpCompareSniff.php

@@ -18,16 +18,14 @@ class RegexpCompareSniff extends AbstractArrayAssignmentRestrictionsSniff {
 
 	/**
 	 * Groups of variables to restrict.
-	 * This should be overridden in extending classes.
 	 *
 	 * Example: groups => array(
-	 *     'wpdb' => array(
-	 *         'type'          => 'error' | 'warning',
-	 *         'message'       => 'Dont use this one please!',
-	 *         'variables'     => array( '$val', '$var' ),
-	 *         'object_vars'   => array( '$foo->bar', .. ),
-	 *         'array_members' => array( '$foo['bar']', .. ),
-	 *     )
+	 *  'groupname' => array(
+	 *      'type'     => 'error' | 'warning',
+	 *      'message'  => 'Dont use this one please!',
+	 *      'keys'     => array( 'key1', 'another_key' ),
+	 *      'callback' => array( 'class', 'method' ), // Optional.
+	 *  )
 	 * )
 	 *
 	 * @return array

WordPressVIPMinimum/Sniffs/Performance/RemoteRequestTimeoutSniff.php

@@ -18,16 +18,14 @@ class RemoteRequestTimeoutSniff extends AbstractArrayAssignmentRestrictionsSniff
 
 	/**
 	 * Groups of variables to restrict.
-	 * This should be overridden in extending classes.
 	 *
 	 * Example: groups => array(
-	 *     'wpdb' => array(
-	 *         'type'          => 'error' | 'warning',
-	 *         'message'       => 'Dont use this one please!',
-	 *         'variables'     => array( '$val', '$var' ),
-	 *         'object_vars'   => array( '$foo->bar', .. ),
-	 *         'array_members' => array( '$foo['bar']', .. ),
-	 *     )
+	 *  'groupname' => array(
+	 *      'type'     => 'error' | 'warning',
+	 *      'message'  => 'Dont use this one please!',
+	 *      'keys'     => array( 'key1', 'another_key' ),
+	 *      'callback' => array( 'class', 'method' ), // Optional.
+	 *  )
 	 * )
 	 *
 	 * @return array

WordPressVIPMinimum/Sniffs/Security/ProperEscapingFunctionSniff.php

@@ -146,7 +146,7 @@ public function is_html_attr( $content ) {
 	 * A helper function which tests whether string ends with some other.
 	 *
 	 * @param string $haystack String which is being tested.
-	 * @param string $needle The substring, which we try to locate on the end of the $haystack.
+	 * @param string $needle   The substring, which we try to locate on the end of the $haystack.
 	 *
 	 * @return bool True if haystack ends with needle.
 	 */

WordPressVIPMinimum/Sniffs/UserExperience/AdminBarRemovalSniff.php

@@ -319,7 +319,7 @@ public function process_text_for_style( $stackPtr, $file_name ) {
 	/**
 	 * Processes this test for T_STYLE tokens in CSS files.
 	 *
-	 * @param int $stackPtr  The position of the current token in the stack passed in $tokens.
+	 * @param int $stackPtr The position of the current token in the stack passed in $tokens.
 	 *
 	 * @return void
 	 */
@@ -370,7 +370,7 @@ protected function process_css_style( $stackPtr ) {
 	/**
 	 * Consolidated violation.
 	 *
-	 * @param int $stackPtr  The position of the current token in the stack passed in $tokens.
+	 * @param int $stackPtr The position of the current token in the stack passed in $tokens.
 	 */
 	private function addHidingDetectedError( $stackPtr ) {
 		$message = 'Hiding of the admin bar is not allowed.';

WordPressVIPMinimum/Sniffs/Variables/VariableAnalysisSniff.php

@@ -17,7 +17,7 @@
 use PHP_CodeSniffer\Files\File;
 
 /**
- * Checks the for undefined function variables.
+ * Checks for undefined function variables.
  *
  * This sniff checks that all function variables
  * are defined in the function body.