WPDBTrait::is_wpdb_method_call(): improve docblock description (#2719)

- Clarified that the method supports static method calls as well.
- Replaced incomplete description with a list of the three properties that may be automatically set: `$methodPtr`, `$i`, and `$end`.
- Added clarification that `$methodPtr` and `$i` may be set even when the method returns false (e.g., for property access like `$wpdb->show_errors`).
- Updated `$stackPtr` parameter description to mention it can be a "wpdb class name token" as well.
- Made the `$end` description more precise: it points to the comma after the first parameter, or to one past the last token of the first parameter if there is no comma.

Author: rodrigoprimo

WordPress/Helpers/WPDBTrait.php

@@ -23,12 +23,23 @@
 trait WPDBTrait {
 
 	/**
-	 * Checks whether this is a call to a $wpdb method that we want to sniff.
+	 * Checks whether this is a call to one of a specific group of $wpdb method(s).
 	 *
-	 * If available in the class using this trait, the $methodPtr, $i and $end properties
-	 * are automatically set to correspond to the start and end of the method call.
-	 * The $i property is also set if this is not a method call but rather the
-	 * use of a $wpdb property.
+	 * Supports both instance method calls (e.g., `$wpdb->prepare()`) and static
+	 * method calls (e.g., `wpdb::esc_like()`).
+	 *
+	 * Note: Static calls on non-static wpdb methods are problematic at runtime, but this
+	 * helper still matches them so sniffs can flag them in the code under scan.
+	 *
+	 * If the following properties are explicitly declared in the class using this trait,
+	 * they will be automatically set:
+	 * - `$methodPtr`: Stack pointer to the method name.
+	 * - `$i`:         Stack pointer to the opening parenthesis of the method call.
+	 * - `$end`:       Stack pointer to the comma after the first parameter, or to the
+	 *                 token directly after the first parameter if there is no comma.
+	 *
+	 * The `$methodPtr` and `$i` properties may be set even when this method returns `false`
+	 * (e.g., for property access like `$wpdb->show_errors`).
 	 *
 	 * @since 0.8.0
 	 * @since 0.9.0  The return value is now always boolean. The $end and $i member
@@ -41,7 +52,7 @@ trait WPDBTrait {
 	 *            for properties in the sniff class(es) using it.}}
 	 *
 	 * @param \PHP_CodeSniffer\Files\File $phpcsFile      The file being scanned.
-	 * @param int                         $stackPtr       The index of the $wpdb variable.
+	 * @param int                         $stackPtr       The index of the $wpdb variable or wpdb (class) name token.
 	 * @param array                       $target_methods Array of methods. Key(s) should be method name
 	 *                                                    in lowercase.
 	 *